はじめに
Amazon Bedrock AgentCore の CLI が、バージョン 1.0 として GA になりました。
コマンド体系が作り直されていて、0.x（以下 v0）で作ったプロジェクトはそのままでは v1 で扱えません。
そこで用意されたのが agentcore migrate です。
気になるのは「すでに動いているエージェントがどうなるのか」なので、v0 でデプロイしたエージェントを v1 に移行して確かめてみました。
agentcore migrate がやること
AgentCore CLI は裏で AWS CDK を使い、エージェントを CloudFormation スタックとしてデプロイしています。
v1 では CDK のコード構成が変わるため、何も考えずに v1 でデプロイし直すと「古いリソースを消して新しく作る」動きになりかねません。
agentcore migrate は、プロジェクトのファイルを v1 形式に書き換えたうえで、デプロイ済みのリソースは作り直さずに引き継ぎます。
- 論理 ID: CloudFormation テンプレートの中でリソースを呼ぶ名前。CDK はコードの構成からこれを決めるので、コードの構成が変わると論理 ID も変わる
- 物理 ID: AWS 上に実在するリソースの ID（Runtime の ARN など）
論理 ID が変わったテンプレートをそのままデプロイすると、CloudFormation は「別のリソースになった」と判断して作り直してしまいます。
そこで migrate は、CloudFormation のスタックリファクタリング（リソースを作り直さずに論理 ID だけを変更する機能）で、先に表札を新しい名前に掛け替えておきます。
やってみた
v0 の @aws/agentcore@0.31.1 でエージェントを us-west-2 にデプロイし、@aws/agentcore@1.0.1 で移行しました。
CLI の導入方法は割愛しますので Get started を参照してください。
手順 0: v0 でエージェントをデプロイしておく
移行元として、v0 の CLI で Strands Agents のエージェントを 1 つデプロイしておきます。すでに v0 のプロジェクトがある方は飛ばしてください。
# v0 でプロジェクトを作成
npx -y @aws/agentcore@0.31.1 create --name MigDemo --framework Strands --model-provider Bedrock --memory none
cd MigDemo
# モデルを Amazon Nova 2 Lite に変更
sed -i '' 's/global\.anthropic\.claude-sonnet-4-5-20250929-v1:0/us.amazon.nova-2-lite-v1:0/' app/MigDemo/model/load.py
grep model_id app/MigDemo/model/load.py
# デプロイ先を指定
ACC=$(aws sts get-caller-identity --query Account --output text)
printf '[{"name":"default","account":"%s","region":"us-west-2"}]\n' "$ACC" > agentcore/aws-targets.json
git add -A && git commit -qm "v0 project"
# v0 でデプロイして呼び出す
npx -y @aws/agentcore@0.31.1 deploy -y
npx -y @aws/agentcore@0.31.1 invoke "1+1は? 数字だけ答えて"
デプロイ結果の RuntimeArnOutput に出る ARN を控えておきます。 (移行後にこれが変わっていなければ成功です)
手順 1: agentcore migrate を実行する
migrate は git で未コミットの変更がない状態 でしか動きません（ドキュメント）。
移行による変更だけを git diff で確認し、必要なら元に戻せるようにするためです。
# デプロイで deployed-state.json が更新されているので、先にコミットする
git add -A && git commit -qm "deployed by v0"
# v1 で移行（--yes で確認なしに適用）
npx -y @aws/agentcore@1.0.1 migrate --yes
Migration plan: MigDemo → v1 (target default, 123456789012/us-west-2)
Keeps the names of 1 deployed resource (runtime MigDemo)
Moves 3 resources in AgentCore-MigDemo-default to new logical IDs (stack refactor)
First v1 deploy: replaces nothing; updates 1 resource in place
Changes 11 files (agentcore/agentcore.json, agentcore/cdk/…)
...
✔ AgentCore-MigDemo-default: refactored, every physical ID unchanged
replaces nothing（作り直すリソースはない）と
every physical ID unchanged（物理 ID はすべてそのまま）が、
今回いちばん見たかった行です。
詳しい計画は agentcore/.cli/migrate/plan-*.md に書き出されます。
計画ファイルによると、論理 ID が変わったのは次の 3 つでした。
| リソース | v0 の論理 ID | v1 の論理 ID |
|---|---|---|
| Runtime | ApplicationAgentMigDemoRuntime… |
ApplicationRuntimeMigDemoRuntime… |
| 実行ロール | ApplicationAgentMigDemoRuntimeExecutionRole… |
ApplicationRuntimeMigDemoRuntimeExecutionRole… |
| ロールのポリシー | …ExecutionRoleDefaultPolicy… |
…ExecutionRoleDefaultPolicy…（接頭辞が同様に変わる） |
ファイル側の変更は git diff で確認できます。
-
agentcore/agentcore.json:"version": 1が"version": 2になり、"migratedFrom": "v1"（v0 時代のリソース名を保つ印）が付く -
agentcore/cdk/lib/cdk-stack.ts: 291 行から 32 行に。v1 では CDK の構成をライブラリ側に任せる形になったようです
手順 2: v1 でデプロイして呼び出す
移行の結果をコミットして、v1 でデプロイします。
git add -A && git commit -qm "migrate to v1"
npx -y @aws/agentcore@1.0.1 deploy --yes
npx -y @aws/agentcore@1.0.1 status
{
"agentRuntimeArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MigDemo_MigDemo-Y9V9k1CEEH"
}
ARN は手順 0 で控えたものと同じでした。
Runtime のバージョンは進みましたが、エージェント自体は作り直されていません。
v1 では invoke の書き方が変わり、プロンプトを引数で渡せなくなっています。--payload で JSON を渡します。
npx -y @aws/agentcore@1.0.1 invoke --runtime MigDemo --payload '{"prompt":"1+1は? 数字だけ答えて"}'
status=200 が返り、移行前と同じエージェントが v1 から応答しました。
(出力は v0 のように整形されたテキストではなく、ストリーミングのイベント（data: {...}）がそのまま表示されます。)
手順 3: 後片付け
npx -y @aws/agentcore@1.0.1 remove all --yes
npx -y @aws/agentcore@1.0.1 deploy --yes
aws logs delete-log-group --region us-west-2 \
--log-group-name /aws/bedrock-agentcore/runtimes/MigDemo_MigDemo-Y9V9k1CEEH-DEFAULT
まとめ
agentcore migrate は、スタックリファクタリングで論理 ID だけを付け替え、デプロイ済みの Runtime を ARN ごと引き継いでくれました
v0 のプロジェクトを持っている方は、まずはコミットしてから agentcore migrate（--yes なし）で計画だけ眺めてみるのがおすすめです。