adk-eval-guide

ADK 評価ガイド

スキャフォールド済みプロジェクトですか？ /adk-scaffold を使用した場合、すでに make eval、tests/eval/evalsets/、tests/eval/eval_config.json が用意されています。まず make eval を実行し、そこから反復して改善してください。

スキャフォールドされていないプロジェクトですか？ adk eval を直接使用してください。詳しくは、以下の評価の実行をご覧ください。

参照ファイル

ファイル	内容
references/criteria-guide.md	メトリクスの完全なリファレンス — 8 つすべての基準、マッチタイプ、カスタムメトリクス、判定モデルの設定
references/user-simulation.md	動的な会話テスト — ConversationScenario、ユーザーシミュレーターの設定、互換性のあるメトリクス
references/builtin-tools-eval.md	google_search とモデル内部ツール — 軌跡の動作、メトリクスの互換性
references/multimodal-eval.md	マルチモーダル入力 — evalset スキーマ、組み込みメトリクスの制限、カスタム評価器のパターン

---

評価と修正の反復サイクル

評価は反復的に行います。スコアがしきい値を下回った場合は、原因を診断して修正し、再実行してください。失敗を報告するだけではいけません。

反復の進め方

1. 小さく始める：テストスイート全体ではなく、1～2 件の評価ケースから始めます
2. 評価を実行する：make eval（Makefile がない場合は adk eval）
3. スコアを確認する — 何が、なぜ失敗したかを特定します
4. コードを修正する — プロンプト、ツールのロジック、指示、または evalset を調整します
5. 評価を再実行する — 修正が機能したことを確認します
6. ケースに合格するまで、手順 3～5 を繰り返す
7. その後で初めて評価ケースを追加し、カバレッジを広げます

**5～10 回以上の反復を想定してください。**これは通常のことです。反復のたびにエージェントが改善されます。

スコアが低い場合に修正する内容

失敗	変更する内容
tool_trajectory_avg_score が低い	エージェントの指示（ツールの順序）を修正する、evalset の tool_uses を更新する、または IN_ORDER／ANY_ORDER のマッチタイプに切り替える
response_match_score が低い	エージェントの指示の表現を調整するか、期待される応答の条件を緩和する
final_response_match_v2 が低い	エージェントの指示を改善するか、期待される応答を調整する — これは語句ではなく意味を評価します
rubric_based スコアが低い	失敗した具体的なルーブリックに対応するよう、エージェントの指示を改善する
hallucinations_v1 が低い	ツールの出力に基づいた回答にするよう、エージェントの指示を厳密にする
エージェントが誤ったツールを呼び出す	ツールの説明、エージェントの指示、または tool_config を修正する
エージェントが余分なツールを呼び出す	IN_ORDER／ANY_ORDER のマッチタイプを使用する、厳格な停止指示を追加する、または rubric_based_tool_use_quality_v1 に切り替える

---

適切な基準の選び方

目的	推奨メトリクス
リグレッションテスト／CI/CD（高速で決定性がある）	tool_trajectory_avg_score + response_match_score
意味に基づく応答の正しさ（表現の柔軟性を許容）	final_response_match_v2
参照回答を使わない応答品質の評価	rubric_based_final_response_quality_v1
ツール使用の推論を検証する	rubric_based_tool_use_quality_v1
ハルシネーションによる主張を検出する	hallucinations_v1
安全性への準拠	safety_v1
動的なマルチターン会話	ユーザーシミュレーション + hallucinations_v1／safety_v1（references/user-simulation.md を参照）
マルチモーダル入力（画像、音声、ファイル）	tool_trajectory_avg_score + 応答品質を評価するカスタムメトリクス（references/multimodal-eval.md を参照）

設定例、マッチタイプ、カスタムメトリクスを含むメトリクスの完全なリファレンスについては、references/criteria-guide.md をご覧ください。

---

評価の実行

# Scaffolded projects:
make eval EVALSET=tests/eval/evalsets/my_evalset.json

# Or directly via ADK CLI:
adk eval ./app <path_to_evalset.json> --config_file_path=<path_to_config.json> --print_detailed_results

# Run specific eval cases from a set:
adk eval ./app my_evalset.json:eval_1,eval_2

# With GCS storage:
adk eval ./app my_evalset.json --eval_storage_uri gs://my-bucket/evals

CLI オプション： --config_file_path、--print_detailed_results、--eval_storage_uri、--log_level

評価セットの管理：

adk eval_set create <agent_path> <eval_set_id>
adk eval_set add_eval_case <agent_path> <eval_set_id> --scenarios_file <path> --session_input_file <path>

---

設定スキーマ（eval_config.json）

camelCase と snake_case のどちらのフィールド名も使用できます（Pydantic のエイリアス）。以下の例では、公式 ADK ドキュメントに合わせて snake_case を使用しています。

完全な例

{
  "criteria": {
    "tool_trajectory_avg_score": {
      "threshold": 1.0,
      "match_type": "IN_ORDER"
    },
    "final_response_match_v2": {
      "threshold": 0.8,
      "judge_model_options": {
        "judge_model": "gemini-2.5-flash",
        "num_samples": 5
      }
    },
    "rubric_based_final_response_quality_v1": {
      "threshold": 0.8,
      "rubrics": [
        {
          "rubric_id": "professionalism",
          "rubric_content": { "text_property": "The response must be professional and helpful." }
        },
        {
          "rubric_id": "safety",
          "rubric_content": { "text_property": "The agent must NEVER book without asking for confirmation." }
        }
      ]
    }
  }
}

簡易しきい値表記も使用できます："response_match_score": 0.8

カスタムメトリクス、judge_model_options の詳細、user_simulator_config については、references/criteria-guide.md をご覧ください。

---

EvalSet スキーマ（evalset.json）

{
  "eval_set_id": "my_eval_set",
  "name": "My Eval Set",
  "description": "Tests core capabilities",
  "eval_cases": [
    {
      "eval_id": "search_test",
      "conversation": [
        {
          "invocation_id": "inv_1",
          "user_content": { "parts": [{ "text": "Find a flight to NYC" }] },
          "final_response": {
            "role": "model",
            "parts": [{ "text": "I found a flight for $500. Want to book?" }]
          },
          "intermediate_data": {
            "tool_uses": [
              { "name": "search_flights", "args": { "destination": "NYC" } }
            ],
            "intermediate_responses": [
              ["sub_agent_name", [{ "text": "Found 3 flights to NYC." }]]
            ]
          }
        }
      ],
      "session_input": { "app_name": "my_app", "user_id": "user_1", "state": {} }
    }
  ]
}

主なフィールド：

• intermediate_data.tool_uses — 期待されるツール呼び出しの軌跡（時系列順）
• intermediate_data.intermediate_responses — 期待されるサブエージェントの応答（マルチエージェントシステム向け）
• session_input.state — 初期セッション状態（Python レベルの初期化を上書きします）
• conversation_scenario — ユーザーシミュレーションで conversation の代わりに使用する項目です（references/user-simulation.md を参照）

---

よくある落とし穴

積極的な動作による軌跡の不一致

LLM は、指示されていない追加のアクションを実行することがよくあります（例：save_preferences の後に google_search を実行する）。このため、EXACT マッチでは tool_trajectory_avg_score が失敗します。対処方法：

1. IN_ORDER または ANY_ORDER のマッチタイプを使用する — 期待される呼び出しの間に追加のツール呼び出しがあっても許容します
2. エージェントが呼び出す可能性のあるツールをすべて、期待される軌跡に含める
3. 軌跡マッチングの代わりに rubric_based_tool_use_quality_v1 を使用する
4. 厳密な停止指示を追加する：「save_preferences を呼び出したら停止してください。検索はしないでください。」

マルチターンの会話では、すべてのターンに tool_uses が必要です

tool_trajectory_avg_score は呼び出しごとに評価します。中間ターンで期待されるツール呼び出しを指定しないと、エージェントが正しいツールを呼び出していても評価は失敗します。

{
  "conversation": [
    {
      "invocation_id": "inv_1",
      "user_content": { "parts": [{"text": "Find me a flight from NYC to London"}] },
      "intermediate_data": {
        "tool_uses": [
          { "name": "search_flights", "args": {"origin": "NYC", "destination": "LON"} }
        ]
      }
    },
    {
      "invocation_id": "inv_2",
      "user_content": { "parts": [{"text": "Book the first option"}] },
      "final_response": { "role": "model", "parts": [{"text": "Booking confirmed!"}] },
      "intermediate_data": {
        "tool_uses": [
          { "name": "book_flight", "args": {"flight_id": "1"} }
        ]
      }
    }
  ]
}

アプリ名はディレクトリ名と一致させる必要があります

App オブジェクトの name パラメーターは、エージェントが格納されているディレクトリ名と必ず一致させてください。

# CORRECT - matches the "app" directory
app = App(root_agent=root_agent, name="app")

# WRONG - causes "Session not found" errors
app = App(root_agent=root_agent, name="flight_booking_assistant")

before_agent_callback パターン（状態の初期化）

指示テンプレートで使用するセッション状態変数は、必ずコールバックを使って初期化してください。これにより、最初のターンでの KeyError によるクラッシュを防げます。

async def initialize_state(callback_context: CallbackContext) -> None:
    state = callback_context.state
    if "user_preferences" not in state:
        state["user_preferences"] = {}

root_agent = Agent(
    name="my_agent",
    before_agent_callback=initialize_state,
    instruction="Based on preferences: {user_preferences}...",
)

評価状態による上書き（型の不一致に注意）

評価セット内の session_input.state には注意してください。Python レベルの初期化が上書きされます。

// WRONG — initializes feedback_history as a string, breaks .append()
"state": { "feedback_history": "" }

// CORRECT — matches the Python type (list)
"state": { "feedback_history": [] }

// NOTE: Remove these // comments before using — JSON does not support comments.

モデルの思考モードがツールをスキップすることがあります

「thinking」が有効なモデルは、ツール呼び出しをスキップすることがあります。ツールの使用を強制するには mode="ANY" を指定した tool_config を使うか、ツール呼び出しを予測可能にするため、思考モードが無効なモデルに切り替えてください。

---

評価失敗のよくある原因

症状	原因	対処方法
中間ターンで tool_uses が不足している	軌跡では呼び出しごとの一致が求められる	すべてのターンに期待されるツール呼び出しを追加する
エージェントがツール出力にないデータに言及する	幻覚	エージェントへの指示を厳密にし、hallucinations_v1 メトリクスを追加する
「Session not found」エラー	アプリ名の不一致	App の name がディレクトリ名と一致していることを確認する
実行ごとにスコアが変動する	非決定的なモデル	temperature=0 を設定するか、ルーブリックベースの評価を使用する
tool_trajectory_avg_score が常に 0	エージェントが google_search（モデル内部）を使用している	軌跡メトリクスを削除する。references/builtin-tools-eval.md を参照
軌跡の評価に失敗するが、ツールは正しい	余分なツールが呼び出されている	IN_ORDER／ANY_ORDER のマッチタイプに切り替える
LLM 評価者が評価時に画像／音声を無視する	get_text_from_content() がテキスト以外の部分をスキップする	ビジョン対応の評価者を使うカスタムメトリクスを使用する（references/multimodal-eval.md を参照）

---

詳細：ADK ドキュメント

公式の評価ドキュメントについては、次のページを取得してください。

• 評価の概要：https://adk.dev/evaluate/index.md
• 基準リファレンス：https://adk.dev/evaluate/criteria/index.md
• ユーザーシミュレーション：https://adk.dev/evaluate/user-sim/index.md

---

デバッグ例

ユーザーの質問：「tool_trajectory_avg_score が 0 です。何が問題ですか？」

1. エージェントが google_search を使用しているか確認する — 使用している場合は、references/builtin-tools-eval.md を参照
2. EXACT マッチを使用していて、エージェントが余分なツールを呼び出しているか確認する — IN_ORDER を試す
3. 評価セット内の期待される tool_uses と、実際のエージェントの動作を比較する
4. 不一致を修正する（評価セットまたはエージェントへの指示を更新する）