Amazon Bedrock AgentCore と GitHub Actions のエージェント評価自動化

Amazon Bedrock AgentCore と GitHub Actions を活用した、自動化されたエージェント評価の仕組みを構築します。これは、ロールベースの MCP ツールを持つエージェントをデプロイし、そのパフォーマンスを評価する CI/CD 品質ゲートです。評価スコアが低下した場合、PR（プルリクエスト）は自動的にブロックされます。

あなたはすでに Amazon Bedrock AgentCore runtime で AI エージェントを稼働させています。このエージェントは OAuth で保護された MCP サーバー を通じてツールを呼び出しています。さて、本番環境に到達する前にコード変更がパフォーマンスを低下させた場合に CI が警告してくれる仕組みが必要ではありませんか。

この記事では、AgentCore runtime にエージェントをデプロイし、AgentCore Evaluate API を使用して評価用プロンプトでエージェントを検証する GitHub Actions パイプラインの構築方法を解説します。もしエージェントのパフォーマンスが低下（回帰）した場合、PR は失敗扱いとなります。

ここでは、ロールベースアクセス制御を持つ MCP サーバーに接続する Strands エージェント、機械間通信（M2M）とユーザースコープの認証フローの両方をサポートする共有 Cognito プール、CDK によるインフラストラクチャとしてのコード、そして統合された評価スクリプトなど、スタック全体をカバーします。完全なリファレンス実装は、対応するリポジトリ で公開されています。

本記事で扱う内容

• CDK を使用して、AgentCore runtime にエージェントと MCP サーバーをデプロイする方法。

MCP ツールにおけるロールベースのアクセス制御（3 層認証パターン）。

CI から OAuth で保護されたランタイムを呼び出す（マシン間通信の client_credentials フロー）。

組み込み評価器を使用したオンデマンド評価の実行。

回帰が発生した際にマージをブロックする品質ゲートの適用。

OAuth チェンジの対応：ユーザーコンテキストがない CI パイプラインがどのように認証を行うか。

主要概念

詳しく掘り下げる前に、まずは基本となる構成要素を簡単に解説します。すでにこれらの知識をお持ちの場合は、次のセクションへお進みください。

• **AgentCore runtime** は、AI エージェント向けのマネージドホスティングプラットフォームです。Python や任意のフレームワークで記述したエージェントコードをデプロイするだけで、スケーリング、セッションの分離、インフラ管理は AgentCore が自動的に処理します。要するに、エージェント版の AWS Lambda と言えます。

• **AgentCore Evaluations** は Amazon Bedrock AgentCore の機能の一つで、大規模言語モデル（LLM）を審査員として用いてエージェントの動作をスコアリングします。Amazon CloudWatch から取得した OpenTelemetry トレースを読み込み、「有用性」「正しさ」「ツールの選択精度」などの観点から回答を評価します。

MCP (Model Context Protocol) は、エージェントが標準化されたインターフェースを通じて外部ツールを呼び出すために使用するオープンプロトコルです。MCP サーバーはツールを公開し、エージェントがそれらを検出して呼び出します。AgentCore ランタイムでは MCP サーバーをホストでき、エージェントとの接続も可能です。

OpenID Connect (OIDC) フェデレーションは、GitHub Actions が長期の認証情報を保存することなく AWS Identity and Access Management (AWS IAM) ロールを引き受ける仕組みです。GitHub が短期間のトークンを発行し、AWS がそれを検証することで、ワークフローに一時的な認証情報が付与されます。

Quality Gate（品質ゲート）は、ビルドが進行する前にパイプラインのステップがある閾値をクリアしなければならない CI/CD のパターンです。今回のケースでは、エージェントの評価スコアが最低基準（例えば 1.0 中 0.8 など）を満たす必要があります。これを満たさない場合、プルリクエストはブロックされたままになります。

これが重要な理由： 自動化された評価が行われないと、エージェントの品質は主観的なものになってしまいます。開発者がシステムプロンプトを変更すると、エージェントが回答の質を低下させることがあります。しかし、ユーザーから苦情が来るまで誰もそれに気づきません。品質ゲートがあれば、本番環境に到達する前にプルリクエストの段階でこの問題を検出できます。

シナリオを想像してください。AgentCore ランタイム上にデプロイされたエージェントがあり、MCP サーバーを通じてツールを呼び出しています。一部のツールは公開されていますが、他のツールはユーザーのロールによって制限されています。

システムプロンプトの変更やモデルの入れ替え、ツールの設定更新が行われるたびに、「エージェントのパフォーマンスは向上したのか、それとも低下したのか」を確認したいものです。

手動テストではスケーラビリティに限界があります。CI（継続的インテグレーション）における自動評価が必要です。具体的には、開発環境に自動的にエージェントをデプロイし、代表的なプロンプトで実行してレスポンスを採点します。品質が低下した場合はマージをブロックする仕組みです。

ここで課題が生じます。MCP サーバーは OAuth とロールベースのアクセス制御（RBAC）を使用しています。CI パイプラインにはユーザーコンテキストが存在しません。では、トークンを転送して MCP サーバーでユーザーロールを期待する、OAuth で保護されたエージェントに対して、ヘッドレスなパイプラインがどのように認証すればよいのでしょうか？

AgentCore Evaluations: 位置づけ

AgentCore Evaluations は、Amazon Bedrock AgentCore プラットフォームにおける品質測定レイヤーです。

これは、エージェントをホストする AgentCore runtime や、トレースを取得して「構築→デプロイ→監視→評価」というライフサイクルを完結させる Amazon Bedrock AgentCore の機能である AgentCore Observability と並んで位置づけられています。

このサービスは、デフォルトで LLM-as-a-judge（LLM を審査員として活用）を用いてエージェントのやり取りをスコアリングしますが、AWS Lambda によるコードベースの評価も選択可能です。動作基盤となるのは OpenTelemetry のトレースで、AgentCore Observability を通じて既にエージェントが出力しているものと同じデータです。

オンデマンド評価では、API コール内で直接スパンデータを指定します。一方、オンライン評価とバッチ評価は CloudWatch からデータを読み取ります。

3 つの評価モードがあり、それぞれ異なる段階に対応しています。

• オンデマンド評価: 特定のセッションをいつでも評価できます。スパンデータを指定し、評価者を選択するだけでスコアが返されます。この機能が CI/CD の品質ゲートとして機能しており、本記事の焦点となっています。

• オンライン評価: 設定可能なサンプリングレートでプロダクショントラフィックを常時監視します。その結果は CloudWatch ダッシュボードにフィードされ、トレンドのモニタリングに活用されます。

• バッチ評価: 非同期ジョブとして一度に複数のセッションをスコアリングします。CloudWatch Logs を指し示して評価者を選択すると、集計結果と個々のセッションごとの結果が得られます。これはベースライン測定や事前・事後の回帰テストを支える機能です。

評価者は以下の 4 つのカテゴリに分類されます。

• 組み込み評価者: Helpfulness（有用性）、Correctness（正しさ）、GoalSuccessRate（目標達成率）、ToolSelectionAccuracy（ツール選択精度）、ToolParameterAccuracy（ツールパラメータ精度）など、一般的な品質次元をカバーします。セッションレベル、トレースレベル、ツール呼び出しレベルで動作します。また、3 つの軌道評価者（TrajectoryExactOrderMatch、TrajectoryInOrderMatch、TrajectoryAnyOrderMatch）が用意されており、実際のツール呼び出しシーケンスと期待される軌道を比較します。

• カスタム評価器では、ドメイン固有の採点に独自の「LLM-as-a-judge」プロンプトを使用できます。Ground truth フィールド（expectedResponse、assertions、expectedTrajectory）も、カスタム評価器のプロンプト内でプレースホルダーとして利用可能です。

• コードベースの評価器は、各トレースまたはセッションに対して Lambda 関数を実行し、独自の実装で計算されたスコア、ラベル、解説を返します。LLM のコストをかけずに、正規表現の一致やスキーマ検証、キーワードの有無といった決定論的なチェックに活用できます。

DeepEval や AutoEval といったオープンソースライブラリから提供されるサードパーティ製評価器は、サービス上で組み込み評価器と同様に管理されます。モデルや設定を指定せず、ID を選択するだけで利用可能です。また、既存の組み込み評価器やサードパーティ製評価器をベースにカスタム評価器を作成し、独自のモデルに対してそのロジックを実行することもできます。

Evaluate API は sessionSpans（CloudWatch からの OpenTelemetry トレースデータ）を受け取り、構造化されたスコアを返します。各 evaluate() コールには、必ず単一のセッションに属するスパンのみを含める必要があります。複数のセッションのスパンを混在させると、ValidationException が発生します。

API は、オプションの正解データも evaluationReferenceInputs を通じて受け付けます。ここでは「Correctness」で利用される expectedResponse や、assertions などを提供可能です。

ゴール達成率（Goal Success Rate）または、軌道評価器で用いられる期待される軌道（expectedTrajectory）のいずれかです。

正解（グランドトゥルース）が存在しないトレースについては、正解不要の評価手法に自動的に切り替わるため、必要なターンに対してのみ正解データを提供すれば十分です。

アーキテクチャ

本パイプラインは、共有の Cognito ユーザープールを介して 2 つの AgentCore ランタイムを展開します。1 つは Strands エージェント用、もう 1 つは MCP サーバー用です。

単一の Cognito ユーザープールは、2 つの認証フローに対応しています。

GitHub Actions パイプラインは、エージェントスタックを開発環境にデプロイし、設定された Cognito インスタンスから JWT トークンを取得して API 呼び出しの認証を行います。その後、評価用データセットでエージェントを起動し、Amazon CloudWatch Logs に生成されたトレースを分析して、定義された閾値に対するパフォーマンスを評価します。総合スコアが許容基準を満たすかどうかに基づいて、プルリクエスト（PR）の自動承認またはブロックを実行します。

CI における OAuth で保護された MCP サーバーへの対応

エージェントが OAuth で保護された MCP サーバーを呼び出す場合、CI パイプラインには課題が生じます。ユーザーコンテキストが存在しないためです。MCP サーバーはロール権限を含む JWT を期待していますが、ヘッドレスな CI ランナーでは対話型の OAuth 同意フローを完了できません。

エージェントの評価には主に3つのアプローチがあり、それぞれに異なるトレードオフがあります。

アプローチ A：保存されたトレースで評価する

評価プロセスとライブな MCP 呼び出しを完全に切り離します。ステージングパイプラインが代表的なプロンプトでエージェントを実行し、その結果のトレースを JSON ファイルとして記録・コミットします。PR 提出時には、CI がこれらの保存されたトレースに対して評価を行います。ライブでの呼び出しは不要です。

Evaluate API は、生の実行環境にあるエージェントを必要としません。提供された OpenTelemetry スパンに対してスコアリングを行うだけです。この方法により CI パイプラインは決定論的（既存のトレースを確認するだけ）となり、OAuth の問題を完全に回避できます。

トレードオフ：ここで評価するのは、現在の PR に含まれるコードそのものではなく、ステージング環境へのデプロイ後の挙動です。このアプローチを始めるには、同梱のリポジトリにある scripts/evaluate_stored_traces.py スクリプトと、fixtures/ ディレクトリ内のサンプルフィクスチャをご利用ください。

アプローチ B：事前承認された権限を持つサービスアカウント

ID プロバイダーに専用のテストユーザーを作成し、OAuth の同意フローを一度だけ対話型で完了させます。その後、更新トークンを AWS Secrets Manager にキャッシュします。CI はこのトークンを使用して、そのテストユーザーとしてエージェントを呼び出します。

トレードオフ： 更新トークンは期限切れになります。そのため、トークンのローテーション機能を用意するか、定期的に手動で再同意を行う必要があります。

アプローチ C：M2M 認証（本記事のアプローチ）

MCP サーバーが M2M とユーザースコープの両方のグラントタイプをサポートするように設定します。CI は M2M トークンを使用し、対話型のユーザーは標準的な OAuth の同意フローを経由します。

MCP サーバーのミドルウェアはトークンタイプを区別します。M2M トークンはスコープを含みますがロールを持たないため、ロールチェックはスキップされ、すべてのツールにアクセス可能となります。一方、ユーザートークンは custom:roles クレームを含むため、ツールレベルでのアクセス制御が適用されます。

このスキップは安全です。なぜなら M2M トークンにはクライアントシークレットが必要であり、これはエンドユーザーに露出しないからです。これらのトークンを取得できるのは CI パイプラインとエージェントランタイムのみで、信頼できない呼び出し元がロールなしのトークンを入手することを防いでいます。

トレードオフ: M2M トークンは設計上、ロールチェックをバイパスします。CI においてロール制御の厳密なテストが必要な場合は、アプローチ B を使用してください。

以下の意思決定ツリーを用いて、ユースケースに最適なアプローチを見つけてください：

ヒント: 品質ゲートを迅速に構築するには、まずアプローチ A から始めることをお勧めします。その後、実際の PR のコード変更をテストする完全なエンドツーエンドの CI を実現するために、本記事で紹介するアプローチ C へと移行してください。

事前準備

• AgentCore にアクセスできる AWS アカウントと、CDK のブートストラップ済み 環境。
• Docker がインストールされ、実行されていること。
• Python 3.12 以上、Node.js 20 以上。
• 必要な Python パッケージのインストール：pip install boto3 requests bedrock-agentcore-starter-toolkit

注意: bedrock-agentcore-starter-toolkit に含まれる Evaluation クラスは、CloudWatch からのトレース収集とスコアリングを自動で行うため、手動でロググループを照会したり、生の Evaluate API を呼び出したりする必要はありません。

MCP サーバー：3 レイヤー認証

アプローチ C では、MCP サーバーが M2M（マシン間）トークンとユーザースコープのトークンの両方をサポートするために 3 つのレイヤーを使用します。これが、CI 評価を本番環境でのロール強制処理と並行して動作させるための重要なパターンです。

レイヤー 1 JWT 検証 (AgentCore): プラットフォームがリクエストがコードに到達する前に、署名、発行者、オーディエンス、有効期限を検証します。実装は不要です。AgentCore は カスタム JWT オーサライザー を通じてこれを処理します。

レイヤー 2 ヘッダーのパススルー: request_header_allowlist=["Authorization"] を両方のランタイムで設定することで、JWT がエージェントと MCP コンテナに確実に到達します。AgentCore は、呼び出し元の Authorization ヘッダーをコンテナに対して変更せずに転送します。

# infrastructure/stack.py — on both CfnRuntime constructs
request_header_configuration=CfnRuntime.RequestHeaderConfigurationProperty(
    request_header_allowlist=["Authorization"]
)

レイヤー 3：ロールベースのツールアクセス権限（AuthMiddleware）

これは FastMCP ネイティブのミドルウェアで、fastmcp.server.dependencies.get_http_headers() を通じて JWT を読み込み、PyJWT でクレームをデコードします。その後、ツールのメタデータにある custom:roles と照合してアクセス権限を制御します。

M2M（マシン間）トークンはスコープは持つもののロールを持たないため、フルアクセスが許可されます。一方、ユーザートークンを使用する場合は、適切なロールが付与されている必要があります。 （原文の技術表記: meta）

ミドルウェアは、FastMCP サーバーインスタンスに直接追加されます。

mcp.add_middleware(AuthMiddleware())
app = mcp.http_app(stateless_http=True)

インフラストラクチャ：CDK スack

CDK スタックを使用すれば、1 コマンドで Cognito プール、両方のランタイム、IAM ロール、事前に作成されたテストユーザーなど、すべてのリソースをデプロイできます。完全な実装については、infrastructure/stack.py を参照してください。

このスタックによって作成される主要なリソースは以下の通りです。

• Cognito ドメイン

CI 用の M2M アプリクライアント（client_credentials フロー）と、対話的な利用向けのユーザーアプリクライアント（authorization_code フロー）です。

事前に作成された 2 つのユーザー：user-a（FinanceUser）と user-b（HRUser）。

• JWT 認証機能を持つ MCP サーバー（AgentCore ランタイム、プロトコル：MCP）
• JWT 認証機能を持つ Strands エージェント（AgentCore ランタイム、プロトコル：HTTP）

<code class="la