Amazon Bedrock AgentCore ベストプラクティス

Amazon Bedrock AgentCore で本番運用レベルの AI エージェントを構築・運用するための推奨事項をまとめたもの。AWS 公式ドキュメント、AWS Machine Learning Blog、Well-Architected Agentic AI Lens をもとに整理している。

0. AgentCore の構成要素（前提）
1. 設計・スコーピング
2. ツール戦略（Gateway）
3. Runtime
4. Memory
5. Identity と認証
6. IAM と最小権限
7. Policy とガードレール
8. ネットワーク
9. Observability（初日から計測する）
10. Evaluations と継続的テスト
11. 組織としてのスケール
12. 責任共有モデル
本番前チェックリスト

0. AgentCore の構成要素（前提）

コンポーネント	役割
Runtime	エージェントコードのサーバーレス実行環境。セッションごとに専用 microVM で分離
Gateway	API / Lambda / 既存サービスを MCP 互換ツールに変換する統一入口
Memory	セッション（短期）＋長期メモリ（セマンティック／要約／ユーザー嗜好／エピソード）
Identity	エージェントのワークロード ID、インバウンド認証、アウトバウンド資格情報（トークン Vault）
Policy	Gateway 経由のツール呼び出しを Cedar ベースで決定的に許可／拒否
Observability	OpenTelemetry トレース、CloudWatch GenAI Observability ダッシュボード
Evaluations	LLM-as-judge／コード評価器によるオンライン・バッチ品質評価
Browser / Code Interpreter	マネージドなヘッドレスブラウザとサンドボックス実行環境

各コンポーネントは単独でも組み合わせても使え、フレームワーク（Strands Agents、LangGraph、CrewAI など）やモデルは自由に選べる。

1. 設計・スコーピング

小さく始め、成功の定義を明確にする

「何ができるか」ではなく「どの課題を解くか」から逆算する。最初はよくあるタスク 3〜5 件に絞り、確実に動かしてから範囲を広げる。
着手前に次の 4 点を文書化してステークホルダーと合意する。
1. エージェント定義：やること／やらないこと（スコープ外の要求を断る根拠になる）
2. トーン・人格：口調、挨拶、スコープ外の質問への対応
3. ツール定義：全ツール・パラメータ・ナレッジソースの曖昧さのない説明
4. 正解データセット：一般的なクエリとエッジケース（断るべき質問を含む）を 40〜50 件程度

エージェントと決定的コードを使い分ける

エージェント（LLM）は「意図解釈」「ツール選択」など曖昧な入力に対する推論に使う。
計算、バリデーション、ルールベースの処理は通常のコードで行う。
現在日時のような決定的な値はツール呼び出しにせず、コンテキストとして渡す（レイテンシ・コスト・LLM 呼び出し回数を削減）。

複雑さはマルチエージェントで分割する

1 つのエージェントに責務を詰め込まず、シンプルな指示とツールセットを持つ専門エージェントに分ける。
ワークフローに合うオーケストレーション（逐次／階層／ピアツーピア）を選ぶ。
ハンドオフ時のコンテキスト引き継ぎを設計し、ハンドオフ自体を監視対象にする。
通信プロトコル（MCP、A2A など）と協調パターンは分けて設計する。

2. ツール戦略（Gateway）

ツール説明には入力・出力・有効値を正確に書く。曖昧な説明はツール選択ミスの最大要因。
失敗モードごとのエラー処理（リトライ／代替／ユーザーへの説明）を定義する。
Slack、GitHub、Salesforce など既存の MCP サーバーは再利用し、独自統合を作らない。
社内 API は AgentCore Gateway で MCP ツールとしてラップする。
セキュリティレビュー済みの中央ツールカタログを整備し、各ツールに動作するコードサンプルを付ける。
Runtime の前段に Gateway を置き、単一の統制された入口にする（後述のセキュリティ節を参照）。

3. Runtime

実装

エントリポイントは @app.entrypoint デコレータで定義する。
入力は必ずスキーマ検証する。ペイロードは任意 JSON なので、prompt が文字列でない（リストやオブジェクト）場合を弾く。

@app.entrypoint
def invoke(payload, context):
    user_message = payload.get("prompt", "")
    if not isinstance(user_message, str) or not user_message.strip():
        return {"error": "Invalid input: 'prompt' must be a non-empty string"}
    result = agent(user_message)
    return {"response": result.message}

文字列以外の toolUse ブロックが渡ると、モデルの推論を経ずにツールが実行されガードレールを迂回されうる。ユーザー由来のメッセージ履歴から toolUse ブロックを除去する。
Pydantic / Zod などで prompt: str と型を固定する（Any にしない）。payload.get("prompt", "Hello") のようなデフォルト値はバリデーションではない。
コンテナは non-root ユーザーで実行する。
ビルドやテストなど決定的に実行すべき処理は LLM を経由させず、直接コマンドとして実行する。

セッション管理

各セッションは専用 microVM で CPU・メモリ・ファイルシステムが分離され、終了時に破棄・サニタイズされる。
ただしセッション ID とユーザーの対応付けは AgentCore が強制しない。どのユーザーがどのセッション ID を所有するかはバックエンドで管理し、ユーザーあたりのセッション数も制限する。
永続ファイルシステム上のパーミッションは保存されるがセッション内では強制されない点に注意する。

パッチ・更新

直接コードデプロイの場合、言語ランタイムのサポート終了後はパッチが当たらない。そのリスクを許容できない場合はコンテナイメージでデプロイし、自分で更新する。

4. Memory

設計

ユーザーごとに名前空間を分けた長期メモリで嗜好やコンテキストを保持し、パーソナライズする。
マルチテナントでは名前空間と IAM 条件でテナント境界をまたいだ読み取りを防ぐ。
長期メモリの戦略（セマンティック、要約、ユーザー嗜好、エピソード）はユースケースに応じて選ぶ。

セキュリティ

保存データは常に KMS で暗号化される。要件に応じて、メモリ作成時に encryptionKeyArn を指定してカスタマーマネージドキーを使う。
メモリポイズニング（会話に虚偽情報を埋め込み長期メモリを汚染）とプロンプトインジェクション（抽出処理時のシステムプロンプト上書き）に備える。
- CreateEvent の段階でガードレールにより入力をサニタイズしてから永続化する。
- ペネトレーションテスト、静的解析、DAST を定期的に実施する。
IAM 条件で、サービスロールを特定の Memory リソースからのみ引き受けられるように制限する。

5. Identity と認証

インバウンド認証

サービス間呼び出しは IAM SigV4、エンドユーザーが IdP で認証する場合は JWT ベアラートークンを使う。1 つの Runtime がサポートする方式は 1 つなので、両方が必要ならバージョンを分ける。
JWT オーソライザーは discovery URL、allowed audiences / clients / scopes、必須カスタムクレームまですべて設定する。
本番では GetWorkloadAccessTokenForJWT（発行者・署名・有効期限を検証）を使う。GetWorkloadAccessTokenForUserId と X-Amzn-Bedrock-AgentCore-Runtime-User-Id ヘッダーの経路は IdP 検証なしで識別子を信頼するため、開発用途か上流で ID 解決済みの構成に限定する。
User ID は認証済みプリンシパル（IAM 呼び出し元や JWT クレーム）から導出し、クライアントが送ってきた値をそのまま使わない。
JWT が常に使える構成では、GetWorkloadAccessTokenForUserId と InvokeAgentRuntimeForUser を IAM で明示的に Deny する。

{
  "Statement": [{
    "Sid": "DenyUserIdDelegation",
    "Effect": "Deny",
    "Action": "bedrock-agentcore:InvokeAgentRuntimeForUser",
    "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:runtime/*"
  }]
}

アウトバウンド認証（資格情報管理）

サードパーティ（Slack、GitHub、Zoom など）へのアクセスはすべて AgentCore Identity のトークン Vault 経由にし、資格情報をコード・システムプロンプト・ツール定義・ログに置かない。モデル自体にトークンを見せない。
ユーザー代理の操作は Authorization Code Grant、エージェント単独の自律処理は Client Credentials Grant と使い分ける。
トークンをハードコードしない。
単一の過剰権限サービスロールで全ツールを呼ぶのではなく、操作ユーザーの ID を伝播させる。監査証跡の価値がここで決まる。

6. IAM と最小権限

CLI が自動作成する実行ロールは、デフォルトでアカウント内の全基盤モデル・推論プロファイルを呼び出せる。agentcore build 後に生成物を確認し、本番では最小権限ロールを --role-arn で指定する。
Resource にはワイルドカードではなく完全な ARN を使う。
実行ロールの権限は、Runtime を呼び出せるプリンシパル以下にする（権限昇格の防止）。
microVM 内のコードはメタデータエンドポイント（MMDS）から実行ロールの資格情報を読めるため、ロールは厳しく絞る。MMDSv2 を必須化する（UpdateAgentRuntime の metadataConfiguration で requireMMDSV2: true。未設定の Runtime は呼び出し不可になる）。
実行ロールの信頼ポリシーに aws:SourceAccount / aws:SourceArn を付け、混乱した代理（confused deputy）問題を防ぐ。

{
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Service": "bedrock-agentcore.amazonaws.com" },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": { "aws:SourceAccount": "123456789012" },
      "ArnLike": { "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*" }
    }
  }]
}

bedrock-agentcore:subnets / bedrock-agentcore:securityGroups 条件キーで、承認済み VPC へのデプロイを強制する。
クロスアカウントでは Runtime とエンドポイントの両方のリソースベースポリシーで許可が必要。明示的 Deny は常に優先される。
AWS マネージドポリシーから始め、ユースケース別のカスタマーマネージドポリシーで最小権限に寄せていく。IAM Access Analyzer でポリシーを検証する。

7. Policy とガードレール

ツール呼び出しの可否は、プロンプトではなく Gateway にアタッチした Policy（Cedar）で決定的に制御する。Policy はエージェントのコード外で評価されるため、エージェントがロジックを見て回避することができない。
自然言語でルールを書いて Cedar に変換できるが、生成されたポリシーは必ずレビューし、テストケースで検証する。
Runtime の前段に Gateway を置くと、次をエージェント環境の外側で適用できる。
- 呼び出し元・ターゲットに対するポリシーベース認可
- Amazon Bedrock Guardrails
- Lambda によるリクエスト／レスポンスインターセプター
Runtime への直接アクセスを塞ぐ（そうしないと上記の統制を迂回される）。
- SigV4 の Runtime：Gateway の実行ロールのみ許可するリソースベースポリシーを付ける
- JWT の Runtime：オーソライザーに allowedWorkloadConfiguration を設定する
構築順序は「Gateway 作成 → Runtime デプロイ → Runtime を Gateway ターゲットに追加」。

8. ネットワーク

プライベートなデータベースや社内 API に接続する場合は VPC 接続を使う。ENI はプライベートサブネット＋NAT ゲートウェイ構成にする（パブリックサブネットではインターネットに出られない）。
PrivateLink でデータプレーン（com.amazonaws.<region>.bedrock-agentcore）とコントロールプレーン（com.amazonaws.<region>.bedrock-agentcore-control）の VPC エンドポイントを作成し、インターネットを経由させない。
VPC 内コンテナエージェントには ECR（ecr.dkr / ecr.api）、S3 ゲートウェイ、CloudWatch Logs のエンドポイントを用意する。S3 エンドポイントポリシーは必要なバケットに限定する。
セキュリティグループのアウトバウンドは必要最小限にする。
VPC エンドポイントポリシーが制限できるのは IAM プリンシパルのみ。OAuth リクエスト用には Principal: * が必要。
通信は TLS 1.2 以上（1.3 推奨）。WebSocket は WSS のみ。
ネットワーク系ツールでは URL フィルタリングを行い、エージェントコードから localhost への任意リクエストを制限する。

9. Observability（初日から計測する）

AgentCore は OpenTelemetry トレースを自動で出力する。モデル呼び出し、ツール呼び出し、推論ステップを最初のテストクエリから可視化する。
CloudWatch Generative AI Observability ダッシュボードで本番を監視し、トークン使用量、レイテンシのパーセンタイル、エラー率、ツール呼び出しパターンを追う。
開発者にはトレースレベルのデバッグ情報、プラットフォームチームにはガバナンス用の集計情報と、ロールに応じたビューを用意する。
集計とセッション単位の両方で挙動を監視する。

監査

CloudTrail（誰が呼んだか）と CloudWatch Logs（何が実行されたか）をリクエスト ID で突合する。
メトリクスフィルターとアラームで異常なコマンドパターンや不正アクセスを検知する。
認証済み IAM プリンシパルと User ID ヘッダー値の対応をログに残す。
VPC 接続の Runtime では VPC Flow Logs を有効にする。
GuardDuty で認証異常を検知し、Security Hub に集約する。

10. Evaluations と継続的テスト

評価は最初から自動化する。技術指標（ツール選択精度、パラメータ抽出精度、レイテンシ、コスト）とビジネス指標をバランスよく定義する。
テストデータには言い換え、エッジケース、曖昧なクエリを含める。本番データからテストセットを継続的に育てる。
プロンプト・ツール・モデルを変更するたびに評価スイートを再実行し、トレードオフを定量化する。
デプロイゲート：正解データセットで精度しきい値を下回ったらデプロイを失敗させる。
A/B テストで段階的に展開し、本番トラフィックをサンプリングしてドリフトを検知する。品質メトリクスがしきい値を割ったら自動ロールバックする。
オンライン評価（本番トレースのサンプリング）とバッチ評価（リリース前回帰）を併用する。

11. 組織としてのスケール

個別プロジェクトではなくプラットフォームとして捉える。共有ツール、標準、中央ダッシュボードを整備する。
ツールと評価手法をチーム間で共有する。
段階的に拡大する：Crawl（社内パイロット）→ Walk（限定された外部ユーザー）→ Run（全面展開）。
コストは主にモデル推論と Runtime のセッション時間で決まる。Memory の保持期間、Gateway の呼び出し量、ログ保持期間も見積もりに含める。

12. 責任共有モデル

AWS の責任	利用者の責任
microVM の分離、OS パッチ、ネットワーク基盤、AgentCore インフラの保護	エージェントコードと依存関係、IAM 設定、セッションとユーザーの対応付け、入力検証、プロンプトインジェクション対策、コンテナイメージの更新、コマンド実行の安全性

エクスプローラー