Amazon Bedrock AgentCore、エージェントワークロードの移行を支援

ノートブック上で動作するエージェントは、本番環境で稼働しているとは言えません。実際のユーザーが訪れるようになると、その作業はエージェントの推論とは無関係な部分にまで及びます。各ユーザーのセッションを混在させず、会話のターンや数日間にわたって状態を保持する必要があります。また、エージェントが呼び出すすべてのツールに対する認証処理もコード内に実装する必要があり、背後にあるオペレーティングシステムのパッチ適用も必要になります。これらは本記事で解説する 10 の運用上の課題のうち 4 つに過ぎません。

エージェントが本番環境へ移行する際は、Amazon Bedrock Guardrails を追加して有害なコンテンツをフィルタリングし、ソースドキュメントとの整合性を検証し、プロンプトインジェクションの試行をブロックします。これらの制御機能は、停止させる段階に関わらず、あらゆるエージェントに適用可能です。

本記事では、すでに保有しているエージェントを出発点とします。これは LangGraph を活用したカスタマーサポート用エージェントで、各メッセージを分類し、怒っている顧客はエスカレーション、それ以外の顧客には 3 つのツールを使って回答するものです。また、モデル呼び出しは既に Amazon Bedrock 経由で行われています。コンテナ、Web サーバー、プロセス内の会話状態はすべてユーザーが管理しています。推論に関する呼び出しのみが移行対象外となるため、すでに Amazon Bedrock を利用しているからといって、それが思われるほどのアドバンテージになるわけではありません。もしモデル呼び出しを OpenAI や Anthropic へ直接行っている場合は、ステージ 0 で示される通り、コンストラクタの 1 つを変更するだけで済みます。

この記事では、エージェントの移行を 2 つの段階に分けて行います。第 1 段階では、グラフ構造はそのままに、Amazon Bedrock AgentCore のランタイム、ゲートウェイ、メモリ機能へ移行します。第 2 段階では、Strands Agents 上でモデル駆動型のプランニングとしてループを再構築します。第 1 段階で停止すれば、管理されたツールと永続的な状態を持つホスト型エージェントが完成します。第 3 段階では、AgentCore ハーネス（Amazon Bedrock AgentCore の機能の一つ）にループを引き渡しますが、これはここで文書化されるものであり、実装されるものではありません。

現在の状況

この記事で扱うエージェントはサポート関連の質問に応答するものです。顧客が注文の場所を尋ねたり、返品方法を聞いたりすると、エージェントは該当情報を検索し、回答可能な範囲では即座に答え、対応できない場合は適切な担当者にエスカレーションします。このエージェントは、あなたが用意した計算リソース上で動作しており、パッチ適用やスケーリングもすべて手動で行う必要があります。

この最後の点こそが、この記事の主題です。記事の内容は、エージェントが何を行うかについては一切記述していません。

コードレベルでの移行範囲は限定されており、影響を受けるのは 4 つの構成要素だけです。実際にはあなたが管理しているリストの方が長く、次のセクションでその対応関係を示します。

最後の行は「AgentCore が私から奪うものは何か」という問いに対する答えです。答えは「何もない」です。ランタイムとは、エージェントが動作する場所であり、次のステップを決定するものではありません。手書きの分岐ロジックを手放すのは、第 2 ステージで下された選択です。

ソリューション概要

移行の目的は、エージェントの推論に直接関係しない作業から解放されることです。Amazon Bedrock AgentCore は、あらゆるフレームワークやモデルに対応し、大規模なエージェントの構築・接続・最適化を可能にするプラットフォームです。各サービスは順次連携させ、それぞれが特定の負担を解消します。以下の図では、10 の機能要素がそれぞれの役割にどのように対応しているかが示されています。

ランタイムは計算リソースを担当するため、OS のパッチ適用、自動スケーリング、セッションの分離といった課題から解放されます。デフォルトでは AWS が管理するインフラ上で動作しますが、必要に応じてあなたが所有する仮想プライベートクラウド（VPC）に接続することも可能です。いずれの場合でも、ネットワーク設計はあなたが行い、エッジ保護をエントリーポイントの前に配置し、認証方針を決定します。

ゲートウェイはツールの認証処理を担当し、独自の実行ロールで関数を呼び出します。チェックポイントの保存は「Memory」に移管され、会話の状態をターン間やプロセス、日付を超えて保持・管理します。

AWS Identity and Access Management (IAM) ポリシー、VPC 設定、Web アプリケーションファイアウォール（WAF）ルール、シークレットのローテーションについては、すべての段階で引き続きあなたが管理します。依存関係の更新は第 3 ステージ以降のみ行われ、それより早い段階では実施されません。

残りの3つのサービスは、既存の構成を置き換えることなく追加されます。IDブローカーは、エージェントが他者の代わりに呼び出すAPI のための認証情報を仲介し、OAuth アクセストークンを更新します。ただし、この手順ではその機能は使用しません。エージェントは、Gateway への呼び出しに署名バージョン4（Signature Version 4）を使用して自身の IAM 資格情報で署名します。その後、Gateway は実行ロールの下で AWS Lambda ターゲットを呼び出します。このパスにはサードパーティ製のトークンは不要です。個別のツール呼び出しは、Gateway でポリシーが決定します。観測機能は、設定なしでランタイムログ、メトリクス、トレースを Amazon CloudWatch に送信します。

手順は順番に実行してください。ステージ1ではエージェントの実行場所を変更し、思考方法には変更を加えません。これにより、変数を一つに絞ることができます。ステージ2では、すでに検証済みのランタイムに対して計画方法を移行します。エージェント自体を書き換えるチームであれば、ステージ2から着手可能です。なぜなら、最初に構築された Gateway、ターゲット、メモリストアはどちらのステージでも使用できるからです。ステージ3 は文書化済みですが、実装は行われていません。

図1：運用対象から外れる部分と、エージェントの次のステップを計画する主体。ステージ1で前者が移行され、ステージ2で後者が移行されます。

移行の手順

サンプルリポジトリは、各ステージを前後のステージと比較できるように以下の構成になっています。次の図は、その比較構造を示しています：各ステージがどこから始まり、何が移動し、なぜ次のステージが続くのかです。本記事で「何かが移動した数」をカウントする場合は、推定値ではなくコミットされたサンプルベースで計測されています。

Figure 2: Where each stage started, what moved, and why the next one follows

Prerequisites

Amazon Bedrock AgentCore への移行を行うには、AWS アカウントが必要です。このアカウントでは Amazon Bedrock のモデルアクセスが有効化されていること、Python 3.12 がインストールされていること、そして AWS Command Line Interface (AWS CLI) が設定済みであることが条件です。CLI は、AgentCore、Lambda、Amazon Simple Storage Service（Amazon S3）、IAM リソースを作成できる認証情報で構成されている必要があります。

また、CloudWatch Transaction Search をアカウントごとに一度だけ有効化しておくことも必須です。これを設定しないと、本チュートリアルで生成されるトレースを閲覧することができなくなります。

git clone https://github.com/aws-samples/sample-migrate-agents-to-amazon-bedrock-agentcore.git
cd sample-migrate-agents-to-amazon-bedrock-agentcore
./setup.sh

これにより仮想環境が作成され、7 つの依存関係がインストールされます。すでに Amazon Bedrock に対して LangGraph エージェントを実行している場合、新たに追加されるのは以下の通りです。

「strands-agents」, 「bedrock-agentcore」, 「MCP」、および「langgraph-checkpoint-aws」といった技術スタックを、Amazon Bedrock AgentCore へ移行する際の基盤となります。 （原文の技術表記: mcp）

2 つの依存関係は固定（pinned）されています。これは、langchain-aws を固定しない場合、そのバージョンが優先されて boto3 も一緒に最新化されてしまうためです。

インストールの確認にはテストスイートを使用します。このテストでは認証情報は不要です。

source .venv/bin/activate
python -m unittest discover -s tests -q

ステージ 0：すでに持っているエージェント

エージェントを変更する前に、まずその動作を確認してください。現在の挙動は、後続のすべての段階で維持されるべき基準となるからです。

これはコンパイルされた StateGraph です。classify_intent はモデルに単語を 1 つ要求し、手書きの route_intent がそれを読み取ります。

怒った顧客が escalate を実行すると、固定された引き継ぎが返され、モデル呼び出しは行われません。それ以外のケースでは assist が呼ばれ、バインドされたツール付きでモデルが呼び出されます。

builder.add_edge(START, "classify_intent")
builder.add_conditional_edges(
    "classify_intent",
    route_intent,
    {"escalate": "escalate", "assist": "assist"},
)
builder.add_edge("escalate", END)
builder.add_conditional_edges("assist", tools_condition)
builder.add_edge("tools", "assist")

return builder.compile(checkpointer=checkpointer)

HTTP バックエンド上で動作する 3 つのツールが @tool 関数として実装されています。具体的には、注文照会を行う lookup_order、返品処理を行う process_return、および FAQ 検索を行う search_faq です。

例外を発生させるのではなく、{"error": ...} というペイロードを返します。

ツールノード内での実行終了はエラーペイロードを伴いますが、これはモデルが対処可能な状態です。

状態は、呼び出し時に渡される thread_id をキーとして持つ MemorySaver チェックポインタであり、これが唯一の厳格な制限事項です。プロセス内の辞書はプロセスが終了するとともに消滅するため、2 つのレプリカ同士がお互いの会話を閲覧することはできません。それ以外の部分はすべて、本番環境でのスケーラビリティに問題ありません。ただし、この状態管理については例外です。

モデルは ChatBedrockConverse を使用するため、推論処理はすでに Amazon Bedrock 経由で行われ、ステージ 0 では AgentCore API にアクセスしません。もし OpenAI や Anthropic から移行する場合は、このコンストラクタが唯一の変更点となります。モデル ID と AWS リージョンを引数として指定してください。リージョン別の利用可能モデルについては、Amazon Bedrock の AWS リージョン別サポートモデル をご参照ください。

移行前に必ずベースラインを記録しておきましょう。どのツールが実行され、グラフ状態から最終的にどのようなメッセージが出力されたかを確認します（モデルの応答そのものではありません）。これにより、次のステージでは単なる期待ではなく、明確な比較が可能になります。この処理はローカル環境で完結し、AWS 上に何ものも作成しません。

python -m examples.run_walkthrough --stage 0

ステージ 1：同じエージェントを移行する

ステージ 0 で動作するエージェントと記録済みのベースラインが用意されました。ステージ 1 では、10 の課題のうち 5 つが不再負荷となり、エージェントの振る舞い自体は変化しません。変更されるのは主に 3 つのポイントです。

まず、ランタイム処理を管理権限に移譲します。次に、3 つあるツールのうち 2 つを Gateway の背後に配置します。最後に、会話の状態を Memory に格納します。推論部分は問題となっていなかったため、ここは変更されません。

移行後のパッケージはステージ 0 をコピーするのではなく、それをインポートします。

from examples.stage0_langgraph.agent import build_graph
from examples.stage0_langgraph.tools import SUPPORT_TOOLS

これらのインポートには、グラフトポロジ、ルーター、状態スキーマ、3 つのプロンプト、そして 3 つのツール本体が含まれています。そのため、これらが意図せず変更されることはありません。また、コストもディスク上の行数としてカウント可能になります。

具体的には、エージェント内部で変更された行は45 行、SDK に含まれていない新規サポートコードが22 行、そしてインポート元のコードはそのままの85 行です。この「22 行」という数が少ないのには理由があります。以前は AgentCore Memory に対して手書きで LangGraph のチェックポインタを実装する必要がありましたが、現在はパッケージ化された形で提供されるようになりました。そのため、残る作業はツールアダプターを接続するだけの接着剤役です。

ランタイム：ループの実行

運用上の 10 の負担は依然としてあなたの責任ですが、そのベースラインは 3 つのターンにわたって記録されます。ループの下にある基盤が先に動くのは、オペレーティングシステムの修正をエージェントが行うわけではないからです。これは、最も少ないコード変更で最大の効果を得られる部分でもあります。OS のパッチ管理から解放され、セッションごとの分離はマイクロ VM 1 つずつで行われるようになります。

既存のループを BedrockAgentCoreApp でラップし、エントリーポイントを与えてください：

from bedrock_agentcore import BedrockAgentCoreApp
from langchain_core.messages import HumanMessage

app = BedrockAgentCoreApp()

@app.entrypoint
def agent_invocation(payload, context):
    state = support_graph().invoke(
        {"messages": [HumanMessage(payload.get("prompt", ""))]},
        config={"configurable": {"thread_id": context.session_id or "local-session"}},
    )
    return {"result": state["messages"][-1].text}

if __name__ == "__main__":
    app.run()

内部の invoke コールはステージ 0 のものです。ここでの変化点は、thread_id がどこから来るかです。ステージ 0 では一つを選択しましたが、ここでは context.session_id として渡されます。