はじめに
AgentCoreを触り始めたとき、Claude Codeに全部任せてデプロイしていた。
動いた。エージェントも返事をした。「AgentCoreデプロイできたじゃん！！」と思っていた。
...でもしばらくして気づいた。自分が使っていたのは現在非推奨のlegacy版CLIだった。
しかも一番厄介だったのが、agentcore deployというコマンドをちゃんと打っていたのに気づけなかった、という点だ。
この記事はその失敗の記録と、なぜ気づきにくいのかの解説。
何が起きたか
1つ目のアプリ
AgentCoreを触り始めてすぐ、Claude Codeに「AgentCoreにデプロイして」と依頼した。
Claude Codeが実行したコマンドはこうだった。
pip install bedrock-agentcore-starter-toolkit
agentcore configure -e main.py
agentcore launch
動いた。特に疑わなかった。
しばらくして launch が deploy になった
次のアプリを作るとき、Claude Codeが使うコマンドが変わっていた。
agentcore deploy # launch だったのが deploy になっている
「あ、コマンド名が変わったんだ」と思った。それだけだった。
実際これは事実で、PR #370（2025年11月26日） でstarter-toolkitの launch コマンドが deploy にリネームされている。後方互換性のため launch も引き続き動くが、--help には表示されなくなった。
「あ〜なるほど、deployに統一されたんだな」と思った。完全に納得していた...。
さらに別のアプリで、コマンドが全然違う
複数のアプリを作っていくうち、Claude Codeが突然全然違うコマンドを使い出した。
npm install -g @aws/agentcore
agentcore create
agentcore dev
agentcore deploy
「ちょっと待って。configureじゃなくてcreate？？ npmからインストール？？」
ここで初めて「何かがおかしい...」と気づいて調べ始めた。
調べてわかったこと：CLIは2種類ある
AgentCore関連のCLIは現時点で2種類存在する。
| bedrock-agentcore-starter-toolkit | AgentCore CLI | |
|---|---|---|
| 状態 | Legacy（非推奨） | 現行・推奨 |
| インストール | pip install bedrock-agentcore-starter-toolkit |
npm install -g @aws/agentcore |
| 主なコマンド |
agentcore configure / agentcore deploy
|
agentcore create / agentcore dev / agentcore deploy
|
自分が最初からずっと使っていたのはpip版のstarter-toolkit（Legacy）だった...。
全然知らなかった。
一番わかりにくいポイント：両方 agentcore deploy を使う
ここが罠の本質だと思う。
starter-toolkit（pip・Legacy）
agentcore launch ← 2025年11月以前
↓ リネーム
agentcore deploy ← 2025年11月以降
AgentCore CLI（npm・現行）
agentcore deploy ← 全く別物なのに同じコマンド名！！
agentcore deploy と打っても、それがどちらのCLIかはコマンド名だけでは絶対にわからない。
「deployコマンドを使っているから最新版のはず」と思っていたら実はlegacy版だった...というのが自分のケースだった。しかもどちらも動く。何も壊れない。だから気づけない。
自分がどちらのCLIを使っているか確認する
気になった人はすぐ確認してほしい。
# pip版（Legacy）が入っているか
pip show bedrock-agentcore-starter-toolkit
# npm版（現行）が入っているか
npm list -g @aws/agentcore
インストールされていれば情報が表示される。入っていなければ not found や警告が出る。
両方入っている場合は混在している状態なので、starter-toolkitはアンインストールしておくと混乱が減る。
pip uninstall bedrock-agentcore-starter-toolkit
なぜAIアシスタントは古い方を薦めがちか
Claude Codeに限らず、AIアシスタントが古いCLIを使いがちな理由は単純で、starter-toolkitの方が長く存在していてネット上の情報量が多いからだと思う。
AgentCore CLI（npm版）は比較的最近リリースされたため、AIの学習データに含まれていないか、含まれていても少ない。
AIに任せること自体は全然問題ない。でも、新しいサービスのセットアップを任せるときは「AIが提案するインストール手順が本当に最新か？」を一度自分で確認するのが大事だと身をもって学んだ...。
正しいインストール方法（2026年5月時点）
npm install -g @aws/agentcore
# バージョン確認
agentcore --version
Node.js 20以上が必要。
preview機能（Managed harnessなど）を使いたい場合：
npm install -g @aws/agentcore@preview
おわりに
agentcore deploy と打っていたのに古いCLIを使っていた、というのは初心者には本当に気づきにくい罠だった。
コマンド名が同じで、動きもする。何もエラーが出ない。だから「正しくやれている」と思ってしまう...。
AgentCoreはまだ新しいサービスで情報が少ない。だからこそ、CLIのバージョンだけは最初に確認しておくと後が楽になる。