evaluation

エージェントシステムの評価方法

エージェントシステムは動的に判断を下し、実行ごとに動作が非決定的で、唯一の正解がない場合も多いため、従来のソフトウェアとは異なる方法で評価します。こうした特性を考慮し、実用的なフィードバックを提供し、リグレッションを検出し、コンテキストエンジニアリングの選択が意図した効果をもたらしていることを検証する評価フレームワークを構築してください。

有効にするタイミング

• エージェントのパフォーマンスを体系的にテストする
• コンテキストエンジニアリングの選択を検証する
• 時間の経過に伴う改善を測定する
• デプロイ前にリグレッションを検出する
• エージェントのパイプラインに品質ゲートを構築する
• 異なるエージェント設定を比較する
• 本番システムを継続的に評価する
• LLM ジャッジを構築する：直接採点、ペアワイズ比較、ルーブリック生成、人間による評価とのキャリブレーション、バイアス軽減

他のスキルが担当する隣接領域の作業には、このスキルを有効にしないでください。

• 測定前に特定のコンテキスト障害モードをデバッグする：context-optimization（診断モード、references/degradation.md）。
• 評価ツールのツール API コントラクト：tool-design。

モード

モード	使用する場面	参照先
デフォルト	成果の測定、ルーブリック、テストセット、決定論的なゲート、継続的なモニタリング	このファイルを読み、次に references/metrics.md
LLM による評価	モデルベースのジャッジの設計やデバッグ：直接採点とペアワイズ比較の選択、ルーブリック生成、信頼度のキャリブレーション、人間による評価との一致度、バイアス軽減、パネル形式または階層形式の評価	まず references/llm-as-judge.md を読み、次にタスクに合った以下のジャッジ関連リファレンスを参照

まずデフォルトモードを実行してください。決定論的なチェックとルーブリックが安定し、未解決の問題が「モデルにどう評価させるか」になった場合にのみ、LLM による評価モードに移行してください。

LLM による評価のリファレンス：

• 実装パターン - 読むタイミング：評価パイプラインを一から構築する場合、または CI/CD に LLM ジャッジを統合する場合
• バイアス軽減手法 - 読むタイミング：評価結果に一貫性のない採点パターンや不審な採点パターンが見られる場合
• ジャッジの指標選択 - 読むタイミング：ジャッジの信頼性を検証する統計指標を選ぶ場合（ルーブリックと成果の指標については references/metrics.md を参照）
• パイプライン図 - 読むタイミング：多段階の評価システムのアーキテクチャを設計する場合
• プロンプトテンプレートと作成例 - 読むタイミング：直接採点やペアワイズ比較のプロンプトを書く場合、または詳しい作成例を確認する場合

コアコンセプト

エージェントが目標に到達するための別の有効な経路を見つける可能性があるため、実行経路ではなく成果に重点を置いて評価します。エージェントが特定の手順を踏んだかどうかではなく、妥当なプロセスを通じて適切な成果を達成したかどうかを判断します。

1つの数値では特定の評価軸における重大な失敗が隠れてしまうため、単一のスコアではなく多次元のルーブリックを使用します。事実の正確性、網羅性、引用の正確性、情報源の品質、ツールの効率性をそれぞれ独立した評価軸として捉え、ユースケースに応じて重み付けします。

モデルによる評価は、決定論的なチェックとルーブリックが安定してから行います。評価者プロンプト、ペアワイズ比較、キャリブレーション、バイアス軽減が中心となる場合は、LLM-as-judge モードに切り替えます。

成果物に機械で検証できる構造がある場合は、LLM による評価より前に決定論的な検証を実行します。スキーマの妥当性、重複キー、ルーブリックの計算、マニフェストの同期、検索ステータス、必須の根拠パスは、評価者がトークンを消費したり主観的なスコアを返したりする前に、すぐに失敗として検出する必要があります。

パフォーマンスを左右する要因

評価予算を設計する際は、ブラウジングエージェントによる調査を適用します。トークン使用量、ツール呼び出し回数、モデルの選択が、測定されるパフォーマンスのばらつきを大きく左右する可能性があります（claim-evaluation-browsecomp-variance）。

要因	説明されるばらつき	意味
トークン使用量	主な要因	探索を増やすと、コストまたはコンテキストの品質が限界に達するまでは、パフォーマンスが向上する可能性があります
ツール呼び出し回数	副次的な要因	ツールの使用が有効なのは、呼び出しによって有用な根拠を取得できる場合に限られます
モデルの選択	副次的だが相乗的に作用する要因	より優れたモデルは、トークンやツールをより効率的に使うことがよくあります

評価を設計する際は、次の点を踏まえて対応します。

• 現実的なトークン予算を設定する：無制限のリソースではなく、本番環境に即した現実的なトークン上限でエージェントを評価します。
• モデルのアップグレードとトークン数の増加を比較する：より優れたモデルは、予算を増やした弱いモデルよりもトークンを効率的に使う可能性があります。
• マルチエージェントアーキテクチャを検証する：エージェントを増やすとトークンとツール呼び出しが増えます。単一エージェントのベースラインと比較して評価します。

詳細なトピック

評価における課題

非決定性と複数の有効な経路に対応する

エージェントは目標に到達するためにまったく異なる有効な経路を取る可能性があるため、経路の違いを許容する評価を設計します。あるエージェントは3つの情報源を検索し、別のエージェントは10個を検索するかもしれません。どちらも正しい回答を生成する可能性があります。特定の手順を確認することは避けてください。代わりに、成果の評価基準（正確性、網羅性、品質）を定め、それらに基づいて採点します。実行経路は評価基準ではなく、参考情報として扱います。

コンテキスト依存の失敗をテストする

エージェントの失敗は、コンテキストに応じて微妙に異なる形で発生することが多いため、複雑さややり取りの長さを幅広く変えて評価します。単純なクエリには成功しても複雑なクエリには失敗する、あるツールセットではうまく機能しても別のセットでは失敗する、またはやり取りが長引いてコンテキストが蓄積するにつれて性能が低下する、といった場合があります。こうした傾向を明らかにするため、単純、中程度、複雑、非常に複雑なテストケースを含めます。

複合的な品質評価軸を個別に採点する

エージェントの品質を別々の評価軸（事実の正確性、網羅性、一貫性、ツールの効率性、プロセスの品質）に分け、それぞれを独立して採点します。正確性のスコアは高くても効率性は低い、またはその逆の場合があるためです。その後、ユースケースの優先事項に合わせて重み付けした集計スコアを算出します。この方法なら、指標の傾向を平均化して見失うことなく、どの評価軸に改善が必要かを把握できます。

評価ルーブリックの設計

多次元のルーブリックを構築する

優秀から不合格まで、各レベルを具体的に説明した、主要な評価軸を網羅するルーブリックを定義します。以下の基本的な評価軸を含め、ユースケースに応じて重みを調整します。

• 事実の正確性：主張が正解と一致していること（知識タスクでは重く評価）
• 完全性：出力が依頼された内容を網羅していること（リサーチタスクでは重く評価）
• 引用の正確性：引用が主張された出典と一致していること（信頼性が重視される状況で評価）
• 情報源の質：適切な一次情報源を使用していること（権威ある出力が求められる場合に評価）
• ツールの効率性：適切なツールを妥当な回数使用していること（コスト重視のシステムで評価）

ルーブリックを数値スコアに変換する

評価軸ごとの判定を数値スコア（0.0～1.0）に変換し、各軸の重みを適用して、加重総合スコアを算出します。ユースケースの要件に基づいて合格しきい値を設定します。一般的な用途では通常0.7、重要度の高い用途では0.9です。各評価軸のスコアも総合スコアと合わせて保存してください。内訳は、改善すべき点を特定するために役立ちます。

評価手法

大規模な評価にはLLM-as-Judgeを使用する

以下を含む、LLMベースの評価プロンプトを作成します。明確なタスクの説明、評価対象のエージェント出力、入手可能な場合は正解、レベルを明示的に説明した評価基準、根拠を添えた構造化された判定の依頼です。LLMによる評価は、大規模なテストセットを一貫性のある方法で、効率よく評価できます。自己評価によるバイアスを避けるため、評価対象のエージェントとは異なるモデルファミリーを使用します。客観的な基準や正解がある場合は直接採点を、主観的な好みを評価する場合はペアワイズ比較を選びます。ペアワイズ比較では、必ず両方の順序で評価し、不一致は引き分けとして扱います。スコアを付ける前に根拠を求め、評価を信頼する前に、人間が採点したサンプルを使って評価者の妥当性を確認してください（詳細はLLM-as-Judgeモードを参照）。

人間による評価を補助的に取り入れる

自動評価では見落とされる、幻覚を含む回答、システム障害、微妙なバイアスに人間のレビュアーが気付けるよう、エッジケース、珍しいクエリ、本番トラフィックからランダムに抽出したサンプルを人間のレビュアーに回します。人間によるレビューで見られるパターンを追跡し、体系的な問題を特定するとともに、その調査結果を自動評価の基準に反映します。

状態を持つエージェントには最終状態の評価を適用する

永続状態（ファイル、データベース、設定）を変更するエージェントについては、エージェントの処理過程ではなく、最終状態が期待どおりかどうかを評価します。期待される最終状態のアサーションを定義し、各テスト実行後にプログラムで検証します。

テストセットの設計

代表的なサンプルを選ぶ

開発初期は、変更の影響が大きく、簡単に改善できる点も多いため、少数のサンプル（20～30件）から始めます。システムの成熟に合わせて、信頼性の高い結果を得られるよう50件以上に増やします。実際の使用パターンからサンプルを抽出し、既知のエッジケースを追加して、さまざまな複雑さのレベルを網羅してください。

複雑さごとに層別する

簡単な例によってスコアが不当に高くなるのを防ぐため、テストセットを複雑さのレベルごとに構成します。

• 単純：ツール呼び出しが1回、事実の検索
• 中程度：複数のツール呼び出し、比較ロジック
• 複雑：多数のツール呼び出し、かなりの曖昧さ
• 非常に複雑：長時間のやり取り、深い推論、統合

総合スコアと合わせて層ごとのスコアも報告し、エージェントが実際に苦手とする領域を明らかにします。

コンテキストエンジニアリングの評価

コンテキスト戦略を体系的に検証する

同じテストセットを使い、異なるコンテキスト戦略でエージェントを実行して、品質スコア、トークン使用量、効率性の指標を比較します。これにより、コンテキストエンジニアリングの影響を他の変数から切り分け、逸話に基づく判断を防げます。

性能低下テストを実施する

異なるコンテキストサイズでエージェントを実行し、コンテキストの劣化が性能に与える影響をテストします。コンテキストが問題になり始める性能の急激な低下点を特定し、安全な運用上限を定めます。これらの上限をコンテキスト管理戦略に反映します。

継続的評価

評価パイプラインを自動化する

評価を開発ワークフローに組み込み、エージェントに変更が加わるたびに評価が自動実行されるようにします。結果を時系列で追跡し、バージョンを比較して、主要な指標が悪化した場合はデプロイをブロックします。

本番環境の品質を監視する

本番環境でのインタラクションをサンプリングし、継続的に評価します。品質が警告しきい値（合格率 0.85）と重大しきい値（合格率 0.70）を下回った場合にアラートを設定します。時間範囲ごとの傾向分析を示すダッシュボードを維持し、緩やかな品質低下を検出できるようにします。

実践的なガイダンス

評価フレームワークの構築

以下の順序に従って評価フレームワークを構築してください。初期の手順を省略すると、実際の品質を反映しない測定につながるためです。

1. 評価コードを書く前に、ユースケースに関連する品質の側面を定義します。後から選んだ側面は、重要なものではなく測定しやすいものを反映する傾向があるためです。
2. 明確で具体的なレベル定義を含むルーブリックを作成し、評価者（人間または LLM）が一貫したスコアを付けられるようにします。
3. 実際の使用パターンとエッジケースを基に、複雑さごとに層別化したテストセットを作成します。信頼できるシグナルを得るため、少なくとも 50 件を用意します。
4. 重要な変更のたびに実行される自動評価パイプラインを実装します。
5. 変更を加える前にベースライン指標を確立し、既知の基準と比較して改善を測定できるようにします。
6. 重要な変更はすべて評価し、ベースラインと比較します。
7. 緩やかな品質低下は急激な低下より気付きにくいため、傾向分析のために指標を時系列で追跡します。
8. 定期的に人間によるレビューを行い、自動評価を補完します。
9. 決定論的な検証の失敗と品質判断を分け、不正な成果物が好意的な LLM スコアによって見逃されないようにします。

評価の落とし穴を避ける

評価の信頼性を損なう、よくある問題に注意してください。

• 特定の経路への過剰適合：エージェントは新しい有効な経路を見つけるため、特定の手順ではなく結果を評価します。
• エッジケースの無視：複雑さの全範囲を網羅する、多様なテストシナリオを含めます。
• 単一指標への執着：単一のスコアでは側面ごとの失敗が隠れるため、多次元のルーブリックを使用します。
• コンテキストの影響の軽視：クリーンルーム条件ではなく、現実的なコンテキストサイズと履歴でテストします。
• 人間による評価の省略：自動評価では、人間が確実に捉えられる微妙な問題を見落とします。

例

例 1：シンプルな評価

def evaluate_agent_response(response, expected):
    rubric = load_rubric()
    scores = {}
    for dimension, config in rubric.items():
        scores[dimension] = assess_dimension(response, expected, dimension)
    overall = weighted_average(scores, config["weights"])
    return {"passed": overall >= 0.7, "scores": scores}

例 2：テストセットの構成

包括的な評価を行うため、テストセットは複数の複雑さのレベルを網羅する必要があります。

test_set = [
    {
        "name": "simple_lookup",
        "input": "What is the capital of France?",
        "expected": {"type": "fact", "answer": "Paris"},
        "complexity": "simple",
        "description": "Single tool call, factual lookup"
    },
    {
        "name": "medium_query",
        "input": "Compare the revenue of Apple and Microsoft last quarter",
        "complexity": "medium",
        "description": "Multiple tool calls, comparison logic"
    },
    {
        "name": "multi_step_reasoning",
        "input": "Analyze sales data from Q1-Q4 and create a summary report with trends",
        "complexity": "complex",
        "description": "Many tool calls, aggregation, analysis"
    },
    {
        "name": "research_synthesis",
        "input": "Research emerging AI technologies, evaluate their potential impact, and recommend adoption strategy",
        "complexity": "very_complex",
        "description": "Extended interaction, deep reasoning, synthesis"
    }
]

例 3：モデルによる判断の前に行う決定論的ゲート

def evaluate_pr_candidate(candidate):
    structure = run_validate_repo(candidate)
    if not structure.ok:
        return {"passed": False, "reason": "deterministic validation failed", "details": structure.errors}

    quality = run_rubric_eval(candidate)
    return {"passed": quality.overall >= 0.8, "scores": quality.dimensions}

例 4：品質ゲートの評価軸

gate:
  deterministic:
    - schema_valid
    - required_files_present
    - no_duplicate_ids
  quality:
    factual_accuracy: min 0.85
    completeness: min 0.80
    source_traceability: min 0.90

ガイドライン

1. 単一の指標ではなく、多次元のルーブリックを使用します
2. 特定の実行経路ではなく、結果を評価します
3. シンプルなものから複雑なものまで、複雑さのレベルを網羅します
4. 現実的なコンテキストサイズと履歴でテストします
5. リリース前だけでなく、継続的に評価を実行します
6. LLM による評価を人間によるレビューで補完します
7. 傾向を検出できるよう、指標を時系列で追跡します
8. ユースケースに基づいて、明確な合否しきい値を設定します

注意事項

1. 特定のコードパスへの評価の過剰適合：テストに合格しても、入力がわずかに変わるとエージェントが失敗することがあります。表面的なパターンではなく、結果と意味に基づいて評価基準を作成し、テスト入力は定期的に入れ替えてください。
2. LLM 評価者の自己強化バイアス：モデルは、独立した評価者よりも自身の出力を高く評価します。評価対象のモデルとは異なるモデルファミリーを評価者に使用してください。
3. テストセットの汚染：評価例がトレーニングデータやプロンプトテンプレートに混入し、スコアが水増しされることがあります。評価セットにはバージョンを付け、プロンプトやファインチューニングに使うデータとは分離してください。
4. メトリクスの攻略：実際の品質ではなくメトリクスの最適化を行うと、スコアは高くてもユーザーを失望させるエージェントが生まれます。自動メトリクスは定期的に人間の判断と照合して検証してください。
5. 単一軸での採点：単一の集計値では、特定の軸における重大な失敗が隠れてしまいます。全体スコアと併せて軸ごとのスコアを必ず報告し、いずれかの軸が最低しきい値を下回った場合は評価を不合格にしてください。
6. 評価セットが小さすぎる：例が 50 件未満だと、実行ごとの分散が大きく、信頼できるシグナルが得られません。評価セットを少なくとも 50 件まで増やし、信頼区間を報告してください。
7. 難易度別に層別化しない：簡単な例によって全体スコアが水増しされ、難しいケースでの失敗が見えにくくなります。複雑さの層ごとにスコアを報告し、簡単なケースが全体を支配しないよう全体スコアに重み付けしてください。
8. 評価を一度限りのものとして扱う：評価はリリース時のゲートではなく、継続的に行う必要があります。モデルの更新、ツールの変更、使用パターンの変化に応じてエージェントの品質は変動します。変更のたびに、また本番環境で定期的に評価を実行してください。

統合

このスキルは、成果の測定、品質ゲート、評価者の設計を担います。隣接するスキルは、制御ループのガバナンスと測定対象のシステムを担います。

• context-optimization：最適化によるトークン、コスト、レイテンシ、品質への影響の測定、および劣化パターンの診断と測定（references/degradation.md）。
• tool-design：評価ツールのスキーマとエラー処理。
• multi-agent-patterns：連携品質と並列化のトレードオフの評価。
• tool-design：ツール選択と復旧の有効性の評価。
• memory-systems：メモリの検索および保持品質の評価。
• pstack：ベンチマークチェックリストのリファレンスで、測定した高速化または性能低下を報告する前に検証します（制限要因、チューニング、エラー、再現性）。

参考資料

内部リファレンス：

• メトリクスリファレンス - 次の場合に参照してください：具体的な評価メトリクスの設計、採点尺度の選択、または重み付きルーブリック計算の実装
• LLM-as-Judge - 次の場合に参照してください：モデルベースの評価者の設計。この資料には、judge-* リファレンス（プロンプトテンプレート、実装パターン、バイアス軽減、評価者のメトリクス、パイプライン図）と scripts/llm_judge_example.py が記載されています

内部スキル：

• ほかのすべてのスキルは、品質測定のために評価と連携します

外部リソース：

• LLM 評価ベンチマーク - 次の場合に参照してください：エージェント比較用のベンチマークスイートの選定または構築
• エージェント評価に関する研究論文 - 次の場合に参照してください：新しい評価手法の導入、または現在のアプローチの検証
• 本番環境のモニタリング手法 - 次の場合に参照してください：稼働中のシステムに対するアラート、ダッシュボード、サンプリング戦略の設定