Agent-EvalKit で AI エージェントを体系的に評価する

AI エージェントを構築するチームは、通常、他のソフトウェアと同じように評価します。つまり、出力が期待通りかどうかをチェックします。しかし、自律的にツールを選択し、複数のソースにわたって操作を順序付けるエージェントは、出力レベルのテストだけでは完全に特徴付けられない動作を生み出します。エージェントは、ツールが空の結果を返したために幻覚を見て事実を捏造しながらも、構造化された実用的な応答を提供する可能性があります。また、信頼できるプロセスに必要な検証手順をスキップしたまま正しい結論に達することもあります。これらの失敗は最終応答の表面下に潜んでいるため、それらを捕捉するには、エージェントの完全な実行パス（エージェントが呼び出したツール、それらのツールが返したデータ、および応答がそのデータを忠実に反映しているかどうか）を追跡する評価が必要です。

このギャップを埋めるには、ほとんどのエージェントチームがゼロから構築する人員を抱えていないインフラが必要です。グラウンドトゥルースの結果を持つテストケース、ツールコールと中間状態をキャプチャするための可観測性計装、および表面精度に加えて忠実性とツール使用状況を評価するメトリクスが必要です。

Agent-EvalKit は、Claude Code、Kiro CLI、Kilo Code などの AI コーディングアシスタントと統合することで、この評価インフラを利用可能にするオープンソースツールキット (Apache 2.0) です。評価をデプロイ後の別個の作業として扱うのではなく、ワークフロー全体を開発環境に取り込みます。評価目標を自然言語で記述すると、ツールキットが各フェーズを処理します。エージェントのソースコードを読み取り、対象を絞ったテストケースを生成し、評価を実行し、コードベースの特定の場所を参照する改善推奨事項を含むレポートを生成します。以下のセクションでは、Agent-EvalKit が6つの評価フェーズでどのように機能するかを、Strands Agents SDK と Amazon Bedrock で構築された旅行調査エージェントを例に説明します。

エージェント評価に必要なもの

インフラ自体に加えて、何を測定するかを選択することも同様に重要です。エージェントの品質は、単一のメトリクスでは捉えきれない複数の次元にまたがります。応答がツールが実際に返した内容に基づいているかどうか、エージェントが適切なパラメータで正しいツールを呼び出したかどうか、最終出力が首尾一貫しており質問者にとって有用かどうか。応答は読みやすい一方で、空のツール結果に対して静かに幻覚を見ている可能性があり、エージェントは壊れたツールコールのシーケンスを経てもっともらしい答えに到達する可能性があるため、各次元は個別にチェックする必要があります。

単一の評価スタイルですべての3つを適切に処理できるものはありません。コードベースの評価は高速で再現可能な結果を提供しますが、有効なバリエーションを罰します。大規模言語モデル (LLM) を判定者とする評価は、追加の推論と注意深いプロンプト設計を犠牲にして、微妙な評価を提供します。最も効果的な評価戦略は、両方のアプローチを組み合わせます。評価スコアを具体的なコード変更に変換することは、多くの取り組みが最終的に行き詰まる場所であり、そのため評価ワークフローは数字のダッシュボードではなく、具体的なコードレベルの推奨事項で終了する必要があります。

Agent-EvalKit の仕組み

Agent-EvalKit は、別の評価プラットフォームとしてではなく、既存の AI コーディングアシスタントを介して動作します。Claude Code、Kiro CLI、Kilo Code のいずれであっても、アシスタントは、コードを読み取り、評価プロセスの各フェーズでエージェントの動作について推論する能力を適用することで、評価エンジンになります。このワークフローは、/evalkit.plan や /evalkit.data などのスラッシュコマンドを介して駆動し、アシスタントにエージェントにとって最も重要な品質次元を伝える自然言語ガイダンスを追加します。この設計により、評価は開発環境内に留まり、エージェントの構築を支援するのと同じアシスタントが評価も支援します。

プロセスはエージェントのソースコードから始まり、アシスタントはツール定義、システムプロンプト、フレームワーク設定を読み取り、エージェントが何をするか、どのツールを呼び出せるか、その動作がどこで壊れる可能性があるかの詳細なモデルを構築します。ツールキットが後続のフェーズで生成するすべての成果物（評価計画から最終レポートまで）は、このコードレベルの理解に基づいています。

その基盤から、アシスタントはエージェントの能力とリスク領域に合わせたメトリクスを使用してパーソナライズされた評価計画を設計し、その後、テストケースの生成、OpenTelemetry 互換のトレースによるエージェントの計装、構造化トレースを収集しながらの各テストケースの実行、基準に基づく結果の評価のための後続フェーズを実行します。プロセスは、コード内の特定の場所を参照する優先順位付きの推奨事項を含むレポートで頂点に達し、評価結果を直接実用的な修正に結び付けます。たとえば、空のツール結果によって引き起こされる幻覚に焦点を当てるようにシステムに指示すると、そのガイダンスがテストケースの生成、メトリクスの選択、およびレポートが最終的に強調するパターンに影響を与えます。

次の図は、テストケースからメトリクス評価までのこのフローを示しています。

ツールキットはこの作業を6つのフェーズに整理し、各フェーズは eval/ ディレクトリに成果物を生成し、それが次のフェーズに供給されます。各フェーズは AI アシスタントを介してスラッシュコマンドとして呼び出し、コマンド後のテキストがそのフェーズの自然言語ガイダンスとして機能します。初期の成果物が整ったら、異なるガイダンスで任意のフェーズを再呼び出しして、焦点を移したり、ゼロから再構築することなく分析を深めたりできます。

これら6つのフェーズは、エージェントの能力の理解から具体的なコード改善の推奨まで、評価ライフサイクル全体をカバーします。

計画 (/evalkit.plan) エージェントのコードを読み取り、そのツールとフレームワークを理解し、すべてのメトリクスを具体的な評価方法とペアにする評価計画を生成します。ガイダンスによって、計画が優先する品質次元が決まり、その優先順位は後のフェーズの動作評価コードに引き継がれます。

データ (/evalkit.data) 評価計画に基づいてテストケースを生成し、各テストケースはエージェントが処理する必要がある特定の動作と障害モードをターゲットにした入力と期待される結果を持ちます。本番ログや手動テストからのテストデータがすでにある場合は、代わりにこのフェーズを既存のデータセットにポイントできます。

トレース (/evalkit.trace) OpenTelemetry 互換のトレースをエージェントに追加することで、完全な実行パスを可視化します。Strands、LangGraph、CrewAI などのサポートされているフレームワークの場合、フレームワークを検出し、適切な計装を適用します。現在のサポートマトリックスについては、Agent-EvalKit リポジトリを参照してください。

エージェント実行 (/evalkit.run_agent) 各テストケースに対してエージェントを実行し、ツールコール、モデル応答、中間状態の完全な履歴をキャプチャする構造化トレースファイルを実行ごとに生成します。

評価 (/evalkit.eval) 計画からのメトリクスを実行可能な評価コードとして実装し、収集されたトレースに対して実行し、構造化結果を保存します。DeepEval や Strands Evals SDK などの評価ライブラリをサポートし、エージェントとメトリクスに最適なアプローチを選択します。

レポート (/evalkit.report) テストケース全体のパターンを分析し、エージェントのコード内の特定の場所を参照する優先順位付きの推奨事項を生成し、各推奨事項には期待される影響が含まれるため、最も違いを生む場所に改善努力を向けることができます。

これらのフェーズを通じて、あいまいな品質の懸念は構造化された証拠の体系になります。つまり、テストケース、実行トレース、メトリクススコア、および優先順位付きの推奨事項はすべて、コード内の特定の場所に結び付けられます。

デモンストレーション研究：旅行調査エージェントの評価

Strands Agents SDK と Amazon Bedrock を使用して旅行調査エージェントを開発している間、エージェントが応答で不審なほど正確な数字を提供することがあることに気付きました。このエージェントは、ウェブ検索、フライト情報、気候データ、通貨換算、予算計算のためのツールを使用してユーザーの旅行計画を支援しますが、精度の問題がどの程度広範囲に及ぶのか、どのクエリがそれを引き起こすのかを特定できませんでした。

Agent-EvalKit はエージェントのコードを分析し、計画フェーズで3つのメトリクスに焦点を当てた評価を設計しました。忠実性は応答がツールが実際に返したデータに基づいているかどうかを測定し、ツールパラメータ精度はエージェントが正しい入力でツールを呼び出したかどうかをチェックし、応答品質は出力がどの程度首尾一貫していて有用かを評価します。データフェーズでは、目的地調査、季節のタイミング、旅程構築、比較質問、予算計算をカバーする100のマルチターンテストセッションを生成し、後続のフェーズで各セッションを実行しながら詳細な実行トレースをキャプチャしました。

結果は、品質と信頼性の間に明確な隔たりがあることを明らかにしました。応答品質は83.9％で、エージェントが明確で実用的な旅行アドバイスを生成したことを確認しました。ツールパラメータ精度は64.5％で、エージェントが通常は正しいツールを選択したが、時々不正確なパラメータを渡したことを示しています。忠実性はわずか32.3％で、ウェブ検索ツールが空または不完全な結果を返したときはいつでも、エージェントが為替レート、気温、観光地の詳細を捏造し、それらの発明をツールからのものとして提示していたことを明らかにしました。

次の図は、単一の実行内でこの幻覚パターンがどのように見えるかを示しています。エージェントは空のツール応答を受け取り、ツールからのものであるかのように捏造データを提示します。

レポートは、幻覚防止ガードレールを最優先の修正として特定し、ツールが空の結果を返したときに開示するためのシステムプロンプト命令と、すべてのコードパスにわたるツールエラーハンドリングの改善を推奨しました。Agent-EvalKit を実行する前は、エージェントが時々信頼性が低いように見えることを知っていました。実行後は、根本原因が空のツール出力による幻覚のトリガーであることを突き止め、それに対処する具体的なコード変更を得ました。

ウォークスルー

以下のセクションでは、Agent-EvalKit の前提条件、ツールキットのインストール、およびエージェントに対するエンドツーエンド評価の実行を案内します。

前提条件

Agent-EvalKit 評価を実行するには、基盤モデル推論のためのクラウドアクセスと、評価ワークフローのためのローカルツールが必要です。

Amazon Bedrock コンソールで基盤モデルが有効になっている有効な AWS アカウント。Agent-EvalKit はスコアリングに基盤モデルを必要とする LLM-as-judge メトリクスを使用するため、続行する前にモデルアクセスページでモデルが利用可能であることを確認してください。

Python 3.11 以降および Git。

uv パッケージマネージャー。macOS および Linux では、curl -LsSf https://astral.sh/uv/install.sh | sh でインストールします。

サポートされている AI コーディングアシスタント（Claude Code、Kiro CLI、または Kilo Code）がマシンにインストールおよび設定されていること。この記事の例では Claude Code を使用していますが、ワークフローは3つすべてに適用されます。各アシスタントのドキュメントを参照してインストール手順を確認してください。

はじめに

uv を使用してツールキットをインストールします。これにより、Agent-EvalKit GitHub リポジトリから直接プルされます。

uv tool install evalkit --from git+https://github.com/awslabs/Agent-EvalKit.git

評価プロジェクトを初期化し、エージェントコードをプロジェクトディレクトリにコピーします。エージェントディレクトリには、ソースコード、ツール定義、およびエージェントの実行に必要な設定が含まれている必要があります。サポートされているエージェントフレームワークとプロジェクト構造の詳細については、Agent-EvalKit リポジトリを参照してください。

evalkit init my-agent-evaluation cd my-agent-evaluation cp -r /path/to/your/agent .

評価プロジェクト内から AI アシスタントを起動します。Claude Code の場合は、claude コマンドを実行します。

claude

ガイド付きの初回評価の場合、quick コマンドは6つのフェーズすべてをステップバイステップで案内し、各フェーズの内容と次に実行するコマンドを説明します。

/evalkit.quick /evalkit.quick Evaluate my agent at ./my_agent for response quality and tool accuracy

より細かく制御するには、各フェーズを個別に実行します。