evaluation

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

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

適用するタイミング

次の場合に、このスキルを適用してください。

• エージェントのパフォーマンスを体系的にテストする
• コンテキストエンジニアリングの選択を検証する
• 時間の経過に伴う改善を測定する
• デプロイ前にリグレッションを検出する
• エージェントのパイプラインに品質ゲートを構築する
• 異なるエージェント構成を比較する
• 本番システムを継続的に評価する

ほかのスキルが担当する関連作業には、このスキルを適用しないでください。

• LLM ジャッジ自体、ペアワイズ比較、ジャッジのキャリブレーション、またはバイアス軽減の設計：advanced-evaluation。
• 自律制御サーフェス、ノベルティゲート、ロールバック、または PR 承認の境界の設計：harness-engineering。
• 測定前に特定のコンテキスト失敗モードをデバッグする作業：context-degradation。

基本概念

エージェントは目標に到達するために別の有効な経路を見つけることがあるため、実行経路ではなく成果を中心に評価してください。特定の手順に従ったかどうかではなく、妥当なプロセスを通じて適切な成果を達成したかどうかを判定します。

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

決定論的チェックと評価基準が安定してから、モデルによる判定を使用してください。作業の中心がジャッジ用プロンプト、ペアワイズ比較、キャリブレーション、またはバイアス軽減にある場合は、Advanced Evaluation に切り替えてください。

成果物に機械的にチェックできる構造がある場合は、LLM による判定の前に決定論的な検証を実行してください。スキーマの有効性、重複キー、評価基準の計算、マニフェストの同期、検索ステータス、必須のエビデンスパスは、評価者がトークンを消費したり主観的なスコアを返したりする前に、速やかに失敗させる必要があります。

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

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

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

評価を設計する際は、次の点を考慮してください。

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

詳細なトピック

評価における課題

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

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

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

エージェントの失敗は微妙な形でコンテキストに依存することが多いため、複雑さや対話の長さを幅広く変えて評価します。エージェントは、単純なクエリでは成功しても複雑なクエリでは失敗したり、あるツールセットではうまく動作しても別のツールセットでは失敗したり、コンテキストの蓄積に伴って長時間の対話後に性能が低下したりする可能性があります。こうした傾向を明らかにするため、単純、中程度、複雑、非常に複雑なテストケースを含めます。

複合的な品質の各側面を個別に採点する

エージェントの品質を個別の側面（事実の正確性、完全性、一貫性、ツールの効率性、プロセスの品質）に分け、それぞれを独立して採点します。エージェントは正確性が高くても効率性が低い、またはその逆の場合があるためです。その後、ユースケースの優先事項に合わせた重み付きの総合スコアを算出します。この方法なら、各側面の違いを平均化して見えなくすることなく、改善が必要な側面を特定できます。

評価ルーブリックの設計

多次元ルーブリックを作成する

優秀から不合格までの記述的なレベルを設け、主要な側面を網羅するルーブリックを定義します。次の主要な側面を含め、ユースケースごとに重みを調整します。

• 事実の正確性：主張が正解データと一致していること（知識タスクでは重みを高くします）
• 完全性：出力が要求された側面を網羅していること（調査タスクでは重みを高くします）
• 引用の正確性：引用が主張された情報源と一致していること（信頼性が重視される状況で重みを高くします）
• 情報源の品質：適切な一次情報源を使用していること（信頼性の高い出力で重みを高くします）
• ツールの効率性：適切なツールを妥当な回数使用していること（コスト重視のシステムで重みを高くします）

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

各側面の評価を数値スコア（0.0〜1.0）に変換し、側面ごとの重みを適用して、重み付きの総合スコアを算出します。ユースケースの要件に基づいて合格基準を設定します。通常は一般用途で0.7、重大な結果を伴う用途で0.9です。内訳が改善箇所の特定に役立つため、総合スコアとともに各側面の個別スコアも保存します。

評価方法

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

次の要素を含むLLMベースの評価プロンプトを作成します。明確なタスクの説明、評価対象のエージェント出力、入手可能な場合は正解データ、各レベルの説明が明確な評価尺度、理由を添えた構造化評価の要求です。LLMによる評価者を使用すると、大規模なテストセットを一貫性のある方法で拡張可能に評価できます。自己強化バイアスを避けるため、評価対象のエージェントとは異なるモデルファミリーを使用します。

人間による評価で補完する

エッジケース、珍しいクエリ、そして本番トラフィックのランダムサンプルを人間のレビュアーに回します。自動評価では見逃される、幻覚を含む回答、システム障害、微妙なバイアスに人間が気づくためです。人間によるレビューの傾向を追跡して、体系的な問題を特定し、その結果を自動評価の基準に反映します。

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

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

テストセットの設計

代表的なサンプルを選ぶ

開発初期は、小規模なサンプル（20～30 件）から始めましょう。この段階では変更の影響が大きく、簡単に改善できる点も多くあります。システムが成熟するにつれて、信頼できるシグナルを得るために 50 件以上に拡大します。実際の使用パターンからサンプルを選び、既知のエッジケースを追加し、複雑さの各レベルを網羅してください。

複雑さごとに層別化する

簡単な例によってスコアが水増しされないよう、テストセットを複雑さのレベルごとに構成します。

• シンプル：単一のツール呼び出し、事実の検索
• 中程度：複数のツール呼び出し、比較ロジック
• 複雑：多数のツール呼び出し、大きな曖昧さ
• 非常に複雑：長いやり取り、深い推論、統合

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

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

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

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

劣化テストを実施する

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

継続的な評価

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

評価を開発ワークフローに統合し、エージェントの変更時に自動で評価が実行されるようにします。結果を時系列で追跡し、バージョンを比較するとともに、重要な指標が後退した場合はデプロイをブロックします。

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

本番環境でのやり取りをサンプリングし、継続的に評価します。警告しきい値（合格率 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. 評価を一度限りのものとして扱う：評価はリリース時のゲートではなく、継続的に行う必要があります。モデルの更新、ツールの変更、利用パターンの変化に応じて、エージェントの品質は変動します。変更のたびに、また本番環境では定期的な間隔で評価を実行してください。

統合

このスキルは、結果の測定と品質ゲートを担います。隣接するスキルは、専門的な評価者の設計と制御ループのガバナンスを担います。

• advanced-evaluation：LLM-as-judge のプロンプト設計、ペアワイズ比較、キャリブレーション、バイアスの軽減。
• harness-engineering：固定された評価者、編集可能な領域、ロールバック、人間による承認の境界。
• context-degradation：劣化パターンの検出と測定。
• context-optimization：最適化によるトークン数、コスト、レイテンシ、品質への影響の測定。
• multi-agent-patterns：連携の品質と並列化によるトレードオフの評価。
• tool-design：ツールの選択と復旧の有効性の評価。
• memory-systems：メモリの取得と保持の品質の評価。

参考資料

内部資料：

• 指標のリファレンス - 読むタイミング：具体的な評価指標の設計、スコアリング尺度の選択、重み付き評価基準の計算の実装時

内部スキル：

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

外部リソース：

• LLM 評価ベンチマーク - 読むタイミング：エージェント比較用のベンチマークスイートを選定または構築する時
• エージェント評価に関する研究論文 - 読むタイミング：新しい評価手法を採用する時、または現在のアプローチを検証する時
• 本番環境の監視プラクティス - 読むタイミング：稼働中のシステム向けにアラート、ダッシュボード、サンプリング戦略を設定する時

---

スキルのメタデータ

作成日：2025-12-20 最終更新日：2026-05-15 作成者：Agent Skills for Context Engineering Contributors バージョン：1.2.0