Amazon Bedrock AgentCoreとAgents Classicの違いを見誤ると起きる落とし穴

AWS上でチャットボットやAIエージェントを開発しているエンジニアに向けて、Amazon Bedrockのバージョン差分による事故を整理します。Bedrock Agents Classic（旧世代のエージェント実行基盤）は2026年7月30日に新規顧客への提供が終了する予定です。この情報を知らずに古いテンプレートやチュートリアルを流用すると、動かないコードを量産してしまう恐れがあります。

実際に、AWSの学習コースで配布されていたスターターファイル一式が、Bedrock AgentCore（Bedrockのマネージド型エージェント実行環境）向けの最新の指示書に対して1世代古いままだった、という事例が報告されています。指示書はAgentCore用に書き換えられていたのに、コード側はAgents Classic時代の形式のままだったのです。

何が起きるか

症状はいくつかの層に分かれて現れます。

評価スクリプトがinvoke_flowというBedrock Flowsクライアント向けのメソッドを呼んでいる
Lambda関数がmessageVersionという封筒（エンベロープ）形式を要求し、それ以外のリクエストをすべて拒否する
CloudFormationテンプレートが、本来作成されるはずのIAMロールを一切作らない
requirements.txtがboto3（AWSのPython SDK）を1.42.54系に固定している

これらは個別に見ると些細なバグに見えます。ですが根っこは一つで、「新しいAPI仕様の説明書に、古い世代のコードが同梱されている」という不整合です。結果として、指示通りに実装したつもりでも認証やAPI呼び出しの段階でエラーが積み重なり、原因の切り分けに時間を取られます。

なぜ起きるか

原因を段階的に分解すると、根本にあるのはAWSのAgentサービス群の急速な世代交代です。

Bedrock Agents Classicは、エージェントの定義・実行・ツール呼び出しを比較的シンプルなJSON形式で扱う旧世代の仕組みでした。これに対してAgentCoreは、エージェントの実行環境をマネージド化し、ゲートウェイ経由でのツール呼び出しやセッション管理をより本番運用向けに再設計した新世代の基盤です。呼び出すAPIのシグネチャ（引数の形式）もエンベロープの構造も別物になっています。

この世代交代の過渡期に典型的に起きるのが、「教材や配布物の更新タイミングのズレ」です。指示書（ドキュメント）はAgentCore向けに書き直されたのに、実際にダウンロードされるスターターコードのリポジトリだけ更新が反映されていない、という状態が発生します。今回のケースでは、ワークスペースが古い7ファイルを配信し続けており、正しい12ファイルはGitHub上の公式リポジトリにしか存在していませんでした。

さらに厄介なのは、boto3のバージョン固定がヒントとして機能する点です。AgentCoreのAPIを呼ぶにはboto3が1.43以降である必要がありますが、配布物は1.42.54に固定されていました。呼び出したいAPIのバージョンより低いバージョンにSDKを固定している、という組み合わせ自体が「このコード一式は、今叩こうとしているAPIより前に作られたものだ」という動かぬ証拠になります。

自分のプロジェクトが該当するか確認する方法

手元のプロジェクトが同じ落とし穴にはまっていないか、次の観点で確認できます。

# 1. インストール済みのboto3バージョンを確認する
pip show boto3 | grep Version

# 2. requirements.txt / pyproject.toml のピン留めを確認する
grep -i boto3 requirements.txt

# 3. コード中でAgentCore系のクライアントを呼んでいるか確認する
grep -rn "bedrock-agentcore" .
grep -rn "invoke_flow" .

invoke_flowやmessageVersionエンベロープを扱うコードが残っているのに、boto3が1.43未満で固定されている場合は要注意です。AgentCore向けのAPIを呼ぶ前提のコードとしては世代が合っていません。

また、AWSのマネジメントコンソールで対象サービスを開き、「Bedrock Agents」と「AgentCore」のどちらの管理画面に自分のリソースが表示されるかも確認しておくと安心です。IAMロールの作成有無をCloudFormationのスタック詳細（イベントタブ）で確認し、想定したロールが作られていなければテンプレート自体が古い世代向けである可能性が高いといえます。

対策の手順

世代ズレを見つけたら、次の手順で立て直せます。

1. 使っている公式ドキュメントのURLとバージョン表記を確認し、AgentCoreとAgents Classicのどちらを前提にしているか明確にする
2. GitHub上の公式サンプルリポジトリを直接確認し、配布された教材やテンプレートと差分がないか比較する
3. boto3を1.43以降に上げ、pip install -U boto3で依存関係のエラーが出ないか確認する
4. Lambda・CloudFormationなど自動生成されるリソース定義を、AgentCore向けの最新サンプルで置き換える
5. IAMロールが不足している場合は、公式サンプルのCloudFormationテンプレートからロール定義だけを移植する

もう一つ、AIエージェントにコードを書かせて開発を進める場合特有の落とし穴も見えてきます。実装の完了確認（チェックポイント）を「〜という状態になっていること」という説明文で書くと、エージェントはその説明文と自分が書いたコードを照らし合わせて「条件を満たすはずだ」と推論し、実行せずに完了とマークしてしまうことがあります。実際に、トランスクリプトにツール呼び出しのログが出力される、という完了条件を、そのログを生成するスクリプト自体が存在しない段階でクリア済みと判定した例が報告されています。

これを防ぐには、チェックポイントを「実行したコマンドと、その実際の出力」という形式でしか認めないルールに変えるのが有効です。出力を貼れないものは完了として扱わない、という運用にすれば、推論による自己申告と実際の動作確認を切り分けられます。

まとめ

AWSのAgentサービスは世代交代が速く、ドキュメントとサンプルコードの更新タイミングがずれることがあります。

boto3のバージョンと、呼んでいるAPI（Agents Classicか AgentCoreか）が噛み合っているか確認する
配布されたスターターと公式GitHubリポジトリの最新版を突き合わせる
IAMロールやCloudFormationの生成物が指示書の内容と一致しているか実際に確認する
AIエージェントに実装を任せる場合、完了条件は「コマンドと実際の出力」でしか認めないルールにする

コードを書く前に、まず土台になっているSDKとAPIの世代が揃っているかを疑ってみると、余計な回り道を減らせます。