All Products
Search

This Product

    :Quick start

    Document Center

    :Quick start

    Last Updated:Sep 17, 2026

    This topic describes how to migrate control-plane resources from an AgentTeams (AT) instance to a new AgentCore (AC) workspace by using the official interactive migration service. The migration service guides you through each phase with explicit confirmations before any write operations.

    Migration scope and limitations

    The migration service transfers control-plane resources from one AT instance to a new AC workspace. By default, the target workspace is created in the same region with the same name as the source instance. Cross-region migration is supported and requires separate confirmation during the process.

    Migratable resources

    The following control-plane resources are included in the migration:

    • Workspace network configuration

    • Collaboration capabilities

    • Local users

    • Model providers and models

    • Credential metadata

    • MCP services

    • Skills

    • Agent templates

    • Managed agents

    • Team configurations

    Resources not included in migration

    The following items are outside the scope of this migration:

    • Runtime data stored in OSS, including configurations, memory, temporary artifacts, task artifacts, and other persistent data generated during agent execution

    • DingTalk and Feishu synchronization configurations in account integrations

    • External access configurations for agents

    • Historical tasks, sessions, invocations, and usage data

    • Business connectivity, third-party service availability, and business acceptance testing

      The target workspace generates new endpoints. After the migration completes, you must switch your callers to the new endpoints, verify external channels, and complete business acceptance testing.

    Do not create, update, or delete resources on the source AT instance during migration. If source resources change during the process, pause the migration and re-run the resource inventory and export to ensure consistency between the source and the migration output.

    The migration service first displays a source resource inventory. Resources that the source explicitly reports as stopped, disabled, failed, or deleted appear in the inventory for reference only. These resources are not exported, included in the migration plan, or created in AC. A missing status from the source API is not treated as an abnormal state.

    Prerequisites

    Before you start the migration, verify the following:

    • You have the permissions required to read the source AT instance and to create an AC workspace and its resources in the target region.

    • You are using an Alibaba Cloud account (not a RAM user).

    • A valid Alibaba Cloud CLI profile is available, or you have confirmed that the default profile is acceptable.

    • You have identified the source region that contains the AT instances to list.

      The migration service lists available AT instances in the specified region for you to select. You do not need to look up instance IDs in the console beforehand.

    Preparations

    Install the migration skills

    Obtain the migrate-agentteams-agentcore-*.zip package for your version from the release channel provided by the AgentCore team. The package contains three skills, all of which must be installed before first use:

    • alibabacloud-agentteams-manage: Manages and views source AT instances and their resources.

    • alibabacloud-agentcore-manage: Manages and views target AC workspaces and their resources.

    • migrate-agentteams-agentcore: Executes the AT-to-AC migration based on the confirmed scope.

      Run the following commands to install all three skills into the .agents skill directory for the current user:

    unzip -q ~/Downloads/migrate-agentteams-agentcore-*.zip -d ~/Downloads/migrate-agentteams-agentcore-install
mkdir -p ~/.agents/skills
package=~/Downloads/migrate-agentteams-agentcore-install/migrate-agentteams-agentcore
cp -R "$package/bundled-skills/alibabacloud-agentteams-manage" ~/.agents/skills/
cp -R "$package/bundled-skills/alibabacloud-agentcore-manage" ~/.agents/skills/
cp -R "$package" ~/.agents/skills/migrate-agentteams-agentcore

    After installation, open a new agent session that supports .agents skills and invoke $migrate-agentteams-agentcore to start the migration. If a skill with the same name already exists, follow the latest release instructions to upgrade. Back up any local customizations or request service support before updating.

    Prepare the Alibaba Cloud CLI

    The migration skill depends on the following local components:

    • Alibaba Cloud CLI (aliyun), version 3.3.0 or later

    • AgentTeams plugin (aliyun-cli-agentteams)

    • AgentCore plugin (aliyun-cli-agentcore)

      For instructions on installing and updating the Alibaba Cloud CLI, see Install, update, and uninstall Alibaba Cloud CLI. After you install the base CLI, run the following commands to install the plugins:

    aliyun plugin install --names aliyun-cli-agentteams
aliyun plugin install --names aliyun-cli-agentcore

    The migration service checks whether the CLI and plugins are available before it starts. Local checks or installations proceed only after you provide confirmation.

    Prepare a working directory

    After you confirm, the migration service creates a local working directory accessible only to the current user. This directory stores intermediate files and the final report. The recommended format is:

    /Users/<current-user>/Desktop/agentteams-to-agentcore-<source-instance-name-or-ID>-<date>

    If you initiate another migration for the same instance on the same day, use a new directory. To resume an existing migration, reuse the original directory.

    The migration service continuously displays the current phase and results. When the resource count is large or registry content is included, export, upload, and verification may take a long time. Wait for the service to report completion or failure for each step before proceeding.

    Step 1: Confirm the migration overview

    Read and acknowledge the migration scope, limitations, post-migration tasks you must complete manually, and the failure handling behavior.

    Step 2: Choose a confirmation mode

    Select one of the following confirmation modes:

    Mode

    Description

    Standard mode (item-by-item confirmation, default)

    Each local preparation, read-only query, export, resource-type creation, and retry step requires individual confirmation. Suitable for migrations where you want to review the scope and result at each stage.

    Dangerous mode (phased batch confirmation, optional)

    Consolidates confirmations into fewer checkpoints: one confirmation covers local dependency checks, instance listing, working directory preparation, and source resource inventory; a second confirmation occurs before export; a third confirmation occurs after the full resource dependency graph (DAG) is displayed, covering all AC imports, read-backs, and final verification. After import confirmation, multiple AC write operations execute consecutively. Suitable for migrations that have already been reviewed and where you want to reduce the number of interactive prompts.

    In both modes, if any creation or verification step fails, the service pauses immediately. It does not automatically roll back, delete created resources, or skip failed items.

    Step 3: Confirm account information and select the source instance

    Confirm the Alibaba Cloud account, CLI profile, and source region. The migration service lists the AT instances in that region for you to select.

    Step 4: Confirm the target and review the source resource inventory

    Confirm the default or custom target workspace and local working directory. The migration service then reads the selected instance's resource inventory in read-only mode and displays the count and name of each resource type.

    Step 5: Export and generate the migration plan

    After you confirm that source changes are paused during migration, the service reads the required resource details and generates a resource dependency graph and a per-type migration plan. This step may take a long time when many resources or registry content are involved. The complete model provider and MCP configurations are written to a local private export file only after you confirm, and this file is used to create target resources in subsequent steps.

    Step 6: Restore AC resources and generate the report

    The migration service first displays the resource dependency graph, then creates resources in dependency order and verifies each resource type after completion. When collaboration capabilities are enabled and member resources are complete, teams are restored as the last resource type.

    • In standard mode, each resource type requires individual confirmation.

    • In dangerous mode, all AC creation, read-back, and final verification are confirmed at once after the full dependency graph is displayed.

      After all resource batches complete, the service automatically verifies the target resources and generates a sanitized migration validation report and a user report. A successful migration is indicated when the report shows all resource types as created and all verification statuses as passed.

    Post-migration tasks

    Review the final report to confirm the migration status of the workspace, resource types, and any incomplete items. Complete the following required tasks:

    • Rebind real values to credentials.

    • Log on with the initial password generated by AC, then immediately reset the local user password.

    • Reconfigure the identity provider (IdP) and IM channels in AC.

    • For external agents, complete onboarding and bind runtime, model, tool, credential, and network settings.

    • Switch callers to the new endpoints and complete business verification.

      To protect sensitive information, passwords, credential values, API keys, tokens, client secrets, and complete authentication configurations do not appear in inventories, session output, or the final report. The complete model provider and MCP configurations are written to the local private export file only after your confirmation. Handle this file according to your organization's data retention and security policies after the migration completes.

    Failure handling and service support

    When resource creation or verification fails, the migration service retains successfully created target resources and pauses. It does not automatically delete or roll back resources. You can choose to:

    • Retry the current step.

    • Skip the failed item after reviewing its downstream impact, and continue processing resources that are confirmed to be unaffected.

    • Abort the migration.

      The service does not automatically skip failed items or proceed with subsequent write operations without your explicit choice.

    If you cannot determine the cause from the error message, or if the issue persists after retry, pause the migration and contact AgentTeams/AgentCore service support. When requesting support, provide the migration name, source and target resource identifiers, timestamp, error code, RequestId, HTTP status code, and affected resource names. Do not include passwords, API keys, tokens, client secrets, or private export files.

    Migration completion means that the approved migration steps and target verification have finished. It does not mean that caller switching, third-party channel verification, or business acceptance testing has been completed.