google-agents-cli-eval について
agents-cli ユーザー向けのエージェント評価ガイドです。データセット、指標、トレースを用い、評価、失敗分析、修正のサイクルでエージェントの改善を支援します。
主な機能
- 01エージェント実行とトレース採点
- 02組み込み指標やカスタム指標の設定
- 03評価データセットの生成と合成
- 04結果比較と失敗分析
- 05マルチターンと Live エージェントの評価
活用シーン
- 01エージェントの目標達成を確認する
- 02ツール利用と最終回答を評価する
- 03失敗に応じて指示やツールを調整する
- 04変更前後の評価結果を比較する
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/ / github.com/ google/ agents-cli --skill google-agents-cli-evalインストール後、Claude Code で/google-agents-cli-evalを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
references/advanced-commands.mdbuiltin-tools-eval.mddataset_schema.mdlive-eval.mdmetrics-guide.mdmultimodal-eval.mduser-simulation.md詳細
エージェント評価ガイド
必要条件:
agents-cli(uv tool install google-agents-cli)— 必要に応じて、まず uv をインストールしてください。
プロジェクトをスキャフォールド済みですか?
/google-agents-cli-scaffoldを使用した場合、データセットとカスタムメトリクスはすでにtests/eval/(Python プロジェクト)またはeval/(Go プロジェクト)にスキャフォールドされています。簡潔にするため、このスキルとそのリファレンスでは Python のディレクトリ構成を使用しています。Go エージェントをスキャフォールドした場合は、適宜読み替えてください。 すでにagents-cli eval run(generate+gradeを連続実行)、tests/eval/datasets/、tests/eval/eval_config.yamlがあります。まずeval runを実行し、そこから反復して改善してください。
リファレンスファイル
| ファイル | 内容 |
|---|---|
references/dataset_schema.md | 正式な EvaluationDataset スキーマ — すべてのフィールド型、単一ターン/複数ターン/複数エージェントの JSON 例、よくある間違い |
references/metrics-guide.md | メトリクスの完全なリファレンス — すべての組み込みメトリクス、マッチタイプ、カスタムメトリクス、評価モデルの設定 |
references/user-simulation.md | 動的な会話テスト — eval dataset synthesize のフラグ、シナリオとは何か、互換性のあるメトリクス |
references/builtin-tools-eval.md | google_search とモデル内部ツール — 軌跡の挙動、メトリクスとの互換性 |
references/advanced-commands.md | オプトインのコマンド:eval analyze、eval optimize、eval submit / eval results |
references/multimodal-eval.md | マルチモーダル入力 — eval データセットのスキーマ、組み込みメトリクスの制限、カスタム評価器のパターン |
references/live-eval.md | ライブエージェントと音声エージェント — --mode adk_live、評価対象、ユーザーのみのターン作成、Live モデルとリージョンに関する落とし穴 |
品質向上のサイクル
エージェントの品質向上は反復的なプロセスです。以下の 4 つのステージで、そのサイクルを説明します。各ステージにはデフォルトの方法(コーディングエージェントであるあなたが直接作業する方法)と、Gemini プラットフォームの Eval Service に処理を委任し、品質と規模を向上させるオプトインの CLI コマンドがあります。
1. データを準備する
デフォルト: スキャフォールド済みの tests/eval/datasets/basic-dataset.json を使用または編集して、単一ターンの評価入力を定義します。まず 1~2 件から始めてください。
オプトイン(ADK プロジェクト): agents-cli eval dataset synthesize:データが不足している場合に、ユーザーをシミュレートして複数ターンのデータセットを作成します。出力にはトレースがすでに含まれるため、ステージ 2 は agents-cli eval grade のみで完了します。評価コマンド と references/user-simulation.md を参照してください。
2. 評価を実行する(必ず実行)
デフォルト: agents-cli eval run はデータセットに対してエージェントを実行し、トレースを評価して、artifacts/grade_results/ に results_<ts>.{json,html} を書き込みます。
分離して実行する方法: カスタムのトレース保存先を指定する場合、エージェントを再実行せずに再評価する場合、または synthesize のトレースを使用する場合は、eval generate の後に eval grade を実行します(eval grade のみ)。
3. 失敗を分析する
デフォルト: 最新の artifacts/grade_results/results_<ts>.html(または .json)を開き、失敗したメトリクスを特定します。修正方法については、以下のスコアが失敗した場合の修正内容の修正表を参照してください。
オプトイン: agents-cli eval analyze は、LLM に基づいて失敗をクラスタリングします。失敗ケースが 10 件以上あり、失敗の種類ごとに分類したい場合に適しています。references/advanced-commands.md を参照してください。
4. 最適化とコードの修正
デフォルト: エージェントを編集します。失敗分析に基づいて、プロンプト、ツールの説明、指示、または評価データセットを調整してください。失敗から修正への対応については、以下の「スコアが失敗した場合の修正内容」を参照してください。
オプトイン(ADK プロジェクト): agents-cli eval optimize は、ターゲット指標に対して ADK GEPA によるプロンプト最適化を実行します(references/advanced-commands.md を参照)。プロンプトのみの失敗に適しています。最適化されたプロンプトはコマンド出力に表示されるので、コピーしてエージェントに適用してください。イテレーションごとの詳細なトレースを表示するには、最適化設定ファイルで print_detailed_results: true を設定してください。
長時間かつ高コストです。 GEPA 最適化では LLM が何度も呼び出され、完了までに長い時間がかかることがあります。ユーザーからプロンプト最適化を明示的に依頼されていない限り、実行しないでください。実行する場合は、まず手動修正をできる限り繰り返してから、最後に
eval optimizeを1 回だけ実行してください。このコマンドを繰り返し実行してはいけません。
ループの実行
ステージ 2 → 3 → 4 → 2 の順に繰り返します(synthesize を使い、毎回ステージ 1 を再実行してから eval grade を実行します)。修正のたびに、agents-cli eval compare <prev_results>.json <new_results>.json を実行して、他の指標を悪化させずにターゲット指標が改善したことを確認してください。ケースに合格するまでに 5~10 回以上のイテレーションが必要になることもありますが、これは通常です。ケースに合格してから、評価ケースを追加してカバレッジを広げてください。
5 回以上のイテレーションを行う場合は、修正済みのケース、まだ失敗しているケース、試した修正内容をまとめたタスクリストを維持してください。同じ修正を再度試すことを防げます。
ケースを保留にする。 ケースの一部をループから外し、完了したと思った段階でのみ評価してください。そうしないと、汎用性のある修正と、イテレーション中に使用したケースに過剰適合した修正を見分けられません。
時間を無駄にする近道
こうした自己正当化に気づいたら、思いとどまらせてください。いずれも、節約できる時間より多くの時間がかかります。
| 近道 | 失敗する理由 |
|---|---|
| 「合格するように基準を下げよう」 | 基準を下げると、本当の失敗が隠れてしまいます。エージェントが基準を満たせない場合は、基準を動かすのではなく、エージェントを修正してください。 |
| 「この評価ケースは不安定だから、スキップしよう」 | 不安定な評価は、エージェントの非決定性を明らかにします。temperature=0、ルーブリックベースの指標、またはより具体的な指示で修正し、シグナルを削除しないでください。 |
| 「エージェントではなく、評価データセットだけを修正すればいい」 | 期待される出力をいつも調整しているなら、エージェントに動作上の問題があります。まず指示またはツールのロジックを修正してください。 |
| 「手元にあるすべてのケースに合格するまで、イテレーションを続けよう」 | 自分のケースへの過剰適合を検出できなくなります。上記の「ケースを保留にする」を参照してください。 |
適切なメトリクスの選択
測定したい内容に応じて、組み込みメトリクスを選んでください。複数ターンのトレースを受け付けるのは、multi_turn_task_success、multi_turn_trajectory_quality、multi_turn_tool_use_quality のみです。それ以外の組み込みメトリクスでは、複数ターンのトレースを指定すると 400 エラーになります。適切な組み込みメトリクスがない場合は、カスタムメトリクスを作成してください(下記の 評価設定スキーマ を参照)。
| 目標 | 推奨される組み込みメトリクス |
|---|---|
| エージェントはユーザーの目標を達成しましたか?(複数ターンのエージェント全般に対応) | multi_turn_task_success |
| エージェントの推論経路は論理的かつ効率的でしたか? | multi_turn_trajectory_quality |
| 複数ターンにわたるツール/関数呼び出しの品質 | multi_turn_tool_use_quality |
| 最終応答の品質(正解データの参照は不要) | final_response_quality |
| 事実に基づいているか(例:RAG エージェントの幻覚的な主張を検出) | hallucination、またはケースに context フィールドがある場合は grounding |
| 安全ポリシーへの準拠 | safety |
| 模範解答との一致 | final_response_match(ケースに reference が必要です) |
| ケースごとに異なる合否基準 | ケースに rubric_groups として設定し、管理対象のルーブリックメトリクスで評価します。references/dataset_schema.md(ケースごとのルーブリック)を参照してください。 |
| 組み込みメトリクスでは対応できない、ドメイン固有のチェック | カスタムの LLMMetric(LLM による評価)または CodeExecutionMetric(決定論的な Python)を作成します。下記の 評価設定スキーマ を参照してください。 |
agents-cli eval metric list を実行すると、利用可能な組み込みメトリクスをすべて確認できます。メトリクスの定義とルーブリックの詳細については、Gemini プラットフォームのメトリクスに関するドキュメントおよび references/metrics-guide.md を参照してください。
スコアが低い場合に修正する内容
agents-cli eval run の完了後、最新の artifacts/grade_results/results_<timestamp>.json を確認するか、.html ファイルを開いてください。そこにはケースごとのスコアと評価理由が記載されています。これらを、以下の修正内容を判断する際の情報として使用します。
| 問題 | 変更内容 |
|---|---|
multi_turn_task_success が低い | エージェントがユーザーの目標を達成できていません。オーケストレーション、不足しているツール呼び出し、早すぎる終了、誤ったツール選択を修正します |
multi_turn_trajectory_quality が低い | エージェントが非効率な方法で目標に到達しているか、誤った手順を踏んでいます。計画プロンプトを改善し、指示の順序を明確にするか、冗長なツール呼び出しを削除します |
multi_turn_tool_use_quality が低い | ツールの説明、パラメーターの docstring、またはツール選択に関するエージェントの指示を修正します |
final_response_quality が低い | 自動生成されたルーブリックの評価結果を読み、最もスコアの低い基準(多くの場合、明確さ、完全性、指示への準拠)に対処するよう、エージェントの指示を改善します |
hallucination が低い | ツールの出力に基づくようエージェントの指示を強化し、エージェントが主張したデータをツールが実際に返したことを確認します |
safety が低い | 指示に安全対策のガードレールを追加し、ルーブリックの評価結果で違反しているコンテンツのカテゴリを確認します |
| エージェントが誤ったツールを呼び出す | ツールの説明、エージェントの指示、またはモデルのツール選択設定(ADK: tool_config)を修正します |
| エージェントが余分なツールを呼び出す | 停止指示を厳格にするか、multi_turn_tool_use_quality に切り替えます |
修正を適用した後、agents-cli eval run を再実行し、agents-cli eval compare <prev_results>.json <new_results>.json を使って、他のメトリクスを悪化させずに対象のメトリクスが改善したことを確認してください。
評価コマンド
agents-cli eval <subcommand> --help に記載されているフラグ一覧が正確な情報です。以下は一般的な使用例です。
eval run(デフォルト)
1 つのコマンドで、データセットを使ってエージェントを実行し、トレースを評価します。
# Basic: dataset from tests/eval/datasets/, results to artifacts/grade_results/,
# metrics from tests/eval/eval_config.yaml
agents-cli eval run
# Advanced: pick the dataset, metrics, and output dir
agents-cli eval run --dataset tests/eval/datasets/custom.json --metrics final_response_quality,safety --output ./out/
eval generate
評価データセットに対してエージェントを実行し、トレースをディスクに書き込みます。
デフォルトでは、エージェントをローカルで実行し、評価ケースごとにトレースを記録します。--url と --app-name に HTTP エンドポイントとアプリ名を指定すると、すでに実行中のエージェントからトレースを生成できます。
ADK プロジェクト。 組み込みのジェネレーターはエージェントを HTTP 経由で提供し、ADK の
/apps/...および/run_sseルートを使用して実行します。これは--urlと--app-nameが想定する形式と同じです。起動するものはプロジェクトの言語によって異なります。Python では、プロジェクトにfast_api_app.pyがあればそれを使用し、なければadk api_serverを実行します。Go ではgo run ...を実行します。他のフレームワーク向けの拡張機能は、eval generateを独自のジェネレーターに置き換えます。独自のジェネレーターは HTTP を提供しない場合があります。その場合、--urlと--app-nameはサポートされません。
# Basic — uses tests/eval/datasets/, writes to artifacts/traces/
agents-cli eval generate
# Advanced — custom dataset and output dir
agents-cli eval generate --dataset tests/eval/datasets/custom.json -o ./custom_traces/
# Against a deployed agent (or one you started manually)
agents-cli eval generate --url https://my-agent.run.app --app-name app
# Live agent — stream each case over ADK's /run_live WebSocket
agents-cli eval generate --mode adk_live
ライブエージェントの評価
ライブエージェントは /run_sse ではなく WebSocket 経由で実行されます。generate または run に --mode adk_live を追加してください。データセット、トレース、採点方法は変わらず、音声の応答は文字起こしされ、その文字起こしが採点対象になります。ソケットへの接続後、セッションの途中で失敗しないよう、事前に満たしておくべき条件が2つあります。エージェントが Live モデルを使用していること(スキャフォールドのデフォルトは Live モデルではありません)、Gemini プラットフォームでは、リージョンが GOOGLE_CLOUD_LOCATION に委ねられず、モデルに固定されていることです。両方の条件とデータセット作成ルールについては、references/live-eval.md を参照してください。
eval grade
トレース(eval generate、eval dataset synthesize、または手動作成のもの)を、組み込みまたはカスタムのメトリクスで採点します。タイムスタンプ付きの results_<YYYYMMDD_HHMMSS>.json(eval compare で使用)と .html(ブラウザーで開きます)を出力ディレクトリに書き込み、概要表をコンソールに表示します。
# Basic — defaults: traces from artifacts/traces/, results to artifacts/grade_results/,
# metrics from tests/eval/eval_config.yaml's metrics_to_run
agents-cli eval grade
# Advanced 1 — grade traces from a non-default location (the canonical
# pairing for `eval generate --output custom_traces/`)
agents-cli eval grade --traces custom_traces/
# Advanced 2: load metrics to run from a config file (YAML or JSON) on a specified trace file.
agents-cli eval grade --traces ./artifacts/traces/trace_1.json --config tests/eval/eval_config.yaml
# Advanced 3: dispatch rate, 15 metric computations per second by default. Lower it when the
# judge model or the eval service rate-limits you, raise it when they have headroom.
agents-cli eval grade --qps 5
設定ファイルの形式については、下記の「Evaluation Configuration Schema」を参照してください。
eval compare
評価実行から得られた2つの results_*.json ファイルを比較します。修正後に実行して、ほかのメトリクスを悪化させることなく、対象のメトリクスが改善したことを確認してください。
agents-cli eval compare baseline.json candidate.json
eval dataset synthesize
ADK プロジェクト。 エージェントの読み込みと実行に ADK を使用するため、他のフレームワークでは利用できません。
エージェントのツールと指示からユーザーシナリオを生成し、それぞれのシナリオを LLM ベースのユーザーシミュレーターで実行して、採点可能なトレースを artifacts/traces/ に書き込みます(そのまま eval grade に渡せるため、eval generate は不要です)。呼び出し方法、フラグ、互換性のあるメトリクスについては、references/user-simulation.md を参照してください。
高度なコマンド
eval analyze(失敗パターンのクラスタリング)、eval optimize(GEPA によるプロンプト調整)、eval submit / eval results(CI または大規模データセット向けのマネージドなクラウド側実行)については、references/advanced-commands.md に記載されています。
評価データセットの形式
EvaluationDataset は eval_cases 配列を含む JSON ファイルです。ケースは用途に応じて次の2つの形式に分かれます。
- 推論入力(
eval generateに渡すもの) — 単一のユーザープロンプト、または複数ターンのユーザーターン(Live の場合)/ユーザーターンで終わる継続データ(SSE の場合)です。エージェントが実行され、トレースが生成されます。Live 推論では、エージェントの応答を事前に作成しないでください。 - 採点入力(
eval gradeに渡すもの) — エージェントの応答とツール呼び出しを含む完全なトレースです。通常はeval generateまたはeval dataset synthesizeで生成されます。手動で作成するものではありません。
正式なスキーマ、すべてのフィールド型、よくある間違いについては、references/dataset_schema.md を参照してください。
推論入力の形式
2つの形式をサポートしています。
(a)単純な単一ターンのプロンプト — スキャフォールドが作成する tests/eval/datasets/basic-dataset.json で使用される形式です。エージェントは最初から実行されます。
{
"eval_cases": [
{
"eval_case_id": "greeting",
"prompt": {
"role": "user",
"parts": [{"text": "Hello, what can you help me with?"}]
}
}
]
}
(b)agent_data を使った複数ターン — 形式はトランスポートによって異なります。
- Live(
--mode adk_live): ユーザーのみのターンを作成します。1つのライブセッションを通して、エージェントがすべての応答を生成します(作成済みのエージェントターンは無視され、警告が表示されます)。 - SSE: 継続形式です。以前のターンは履歴としてシードされ、最後のユーザーターンにのみ応答します。
JSON 形式については、references/dataset_schema.md の「Multi-Turn / Multi-Agent Dataset」を参照してください。
採点入力形式(トレース)
完全なトレース(エージェントの応答と function_call / function_response パーツ)は、通常 eval generate / eval dataset synthesize によって生成されます(手作業で作成するものではありません)。作成者は "user"、agents マップのエージェント ID、または "tool" です。トレースの形式、複数エージェントの例、完全な型リファレンスについては、references/dataset_schema.md を参照してください。
評価設定スキーマ
agents-cli eval run --config <path>(および eval grade --config <path>)では、YAML(.yaml / .yml)または JSON(.json)のいずれかの単一設定ファイルを指定できます。このファイルでは、次の2つの部分を宣言します。
metrics_to_run:この実行で実行するメトリクス名の選択リストです。名前と一致するcustom_metricsエントリがある場合はそのエントリに解決され、ない場合は同名の組み込みメトリクスに解決されます。custom_metrics— このプロジェクトで使用できるカスタムメトリクスの定義プールです。ここでメトリクスを定義しても実行はされません。metrics_to_runにも含めるか、CLI で--metrics name1,name2を渡す必要があります。後者は、その呼び出しに限りmetrics_to_runを上書きするのと同じです。
最小限の例(YAML 推奨 — 人が読みやすく、プロンプトや Python の JSON エスケープが不要です):
metrics_to_run:
- multi_turn_task_success # built-in
- example_llm_metric # selected from custom_metrics pool below
- agent_turn_count # selected from custom_metrics pool below
custom_metrics:
- name: example_llm_metric
prompt_template: |
Rate the agent's response 1-5 for helpfulness and accuracy.
Prompt: {prompt}
Final response: {response}
Full trace (for tool-call and reasoning context): {agent_data}
Return JSON: {"score": <1|2|3|4|5>, "explanation": "<reason>"}
- name: agent_turn_count
custom_function: |
def evaluate(instance):
turns = (instance.get("agent_data") or {}).get("turns", [])
return {'score': len(turns)}
JSON も使用できます(同じフィールド名を使い、prompt_template と custom_function はエスケープ済みの文字列にします)が、人が読みやすい設定には常に YAML を優先してください。
フィールドに応じて振り分けられます。custom_function → Python メトリクス、prompt_template → LLMMetric(LLM を用いた評価)。どちらもなく、組み込みメトリクス名の場合は、その組み込みメトリクスをパラメーター化します(例:metric_spec_parameters.rubric_group_key)。フィールドのリファレンスについては、references/metrics-guide.md を参照してください。
エージェントトレースのフィールドモデル。 agents-cli eval generate(または eval dataset synthesize)で作成されたデータセットでは、各評価ケースがメトリクスに次の3つの標準フィールドを公開します。
{prompt}— ユーザーメッセージ(または最初のユーザーターン)。{response}— テキストを含む最後のイベントから抽出された、エージェントの最終テキスト応答。custom_functionコールバックでは、これは{"role": "model", "parts": [{"text": "..."}]}という形式のinstance['response']です。{agent_data}—turns/eventsの完全な構造化トレースです。ツール呼び出しや中間推論について評価者が判断する際に役立ちます。
reference、context、rubric_groups は、ケースごとに独自に作成するフィールドです。eval generate はこれらをトレースに引き継ぎますが、生成はしないため、{reference} / {context} は記述した場合にのみ解決されます。rubric_groups はプレースホルダーではありません。管理対象のルーブリックメトリクスはケースから読み取り、custom_function では instance['rubric_groups'] として参照できます。references/dataset_schema.md の「ケースごとのルーブリック」を参照してください。
コードベースのメトリクスは、デフォルトでローカルのインプロセス実行になります(GCP プロジェクトやリージョンは不要ですが、evaluate(instance) 関数は CLI の権限で実行されます)。メトリクスに execution: "remote" を設定すると、Gemini プラットフォームの CodeExecutionMetric サンドボックスでサーバー側実行に切り替わります。この方法では、GCP プロジェクトとリージョンの設定が必要です。
よくある注意点
固定されたシーケンスではなく、ルーブリックベースのツール評価を使用する
厳密なシーケンス照合でエージェントのツール使用を評価するのは脆弱です。エージェントによっては、ヘルパーツール(検索やジオコーディングなど)を異なる順序で呼び出したり、追加の先回りした手順を実行したりする場合があるためです。
代わりに、multi_turn_tool_use_quality / multi_turn_trajectory_quality を使用してください。これらのメトリクスは、内容と意図に基づく適応型ルーブリックを自動生成し、固定的な一致を強制するのではなく、LLM 評価者を使って技術的な正確性と技術的なシーケンスの妥当性を意味的に評価します。
アプリ名はディレクトリ名と一致させる
ADK プロジェクト。
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")
Gemini platform の評価リージョン
eval run、eval grade、eval submit は、デフォルトで global エンドポイントを使用します。マニフェストの region は継承されません(評価サービスが対応しているのは一部のリージョンのみです)。また、eval analyze は global のみで実行できます。実行ごとに --region <REGION> で指定を変更できます(例:データレジデンシー)。対応していないリージョンを指定すると、サービスによって拒否されます。
400 FAILED_PRECONDITION: Unsupported region for Vertex Evaluation Service: <region>
eval generate(--url フラグなし)と eval dataset synthesize はエージェントをローカルで実行するため、エージェント自身の .env を使用します。特に GOOGLE_CLOUD_LOCATION は、エージェントが Gemini platform を使用する場合(GOOGLE_GENAI_USE_ENTERPRISE=true)にモデルのエンドポイントを選択します。GEMINI_API_KEY(AI Studio)を使用する場合、この変数は使われません。これらのコマンドには --region がなく、マニフェストの region で .env が上書きされることもありません。モデルのリージョンを変更するには .env を編集してください。または、単一のエージェントであれば、コード内で Gemini(model=…, client_kwargs={"location": …}) を指定するのがおすすめです。これは環境変数より優先され、環境変数をほかの用途に使える状態に保てます。ただし、synthesize ではシナリオ生成のステップが GOOGLE_CLOUD_LOCATION でサーバーサイドの評価呼び出しを行うため、エージェント自体を別の場所で実行できる場合でも、評価に対応したリージョン(デフォルトは global)を指定してください。
データレジデンシーの要件に合う評価リージョンがありませんか? その場合は、ローカルのカスタムメトリクスに切り替えてください。custom_function を含む custom_metrics エントリー(デフォルトの execution: local)は、GCP リージョンを指定せずにプロセス内で評価します。マネージドの組み込みメトリクスは使えなくなりますが、custom_function から準拠したリージョンの LLM ジャッジを呼び出すことはできるため、どこでも LLM-as-judge による評価を利用できます。
before_agent_callback パターン(状態の初期化)
ADK プロジェクト。
指示テンプレートで使用するセッション状態変数は、必ずコールバックで初期化してください。これにより、最初のターンで 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}...",
)
モデルの思考モードによってツールが呼び出されないことがあります
「思考」が有効なモデルは、ツール呼び出しをスキップすることがあります。モデルのツール選択設定でツールの使用を強制する(ADK: mode="ANY" を指定した tool_config)か、安定したツール呼び出しのために思考モードのないモデルに切り替えてください。
評価でよくある失敗の原因
| 症状 | 原因 | 対処法 |
|---|---|---|
| 実行ごとにスコアが変動する | 非決定的なモデル | temperature=0 を設定するか、複数サンプルを使ったルーブリックベースの評価を使用します |
| LLM ジャッジが評価で画像/音声を無視する | get_text_from_content() がテキスト以外の部分をスキップする | 視覚機能に対応したジャッジを使うカスタムメトリクスを使用します(references/multimodal-eval.md を参照) |
作業の証拠を提示する
評価に合格したと主張するだけではなく、証拠を示してください。具体的な出力を提示することで、根拠のない確信を防ぎ、問題を早期に発見できます。
- 評価の実行後: スコアテーブルの出力を貼り付け、何が合格し、何が不合格だったのかをユーザーが正確に確認できるようにします。
- 失敗の修正後: 修正したケースの修正前後のスコアを示し、ほかのケースに悪影響が出ていないことを確認します。
- デプロイ前:
agents-cli eval runを再実行し、修正したケースだけでなく、すべてのケースのスコアを示します。eval runはスコアにかかわらず終了コード 0 を返すため、合否の判断基準となるのは終了コードではなく、提示した数値です。
関連スキル
/google-agents-cli-workflow— 開発ワークフローと、仕様主導のビルド・評価・デプロイのライフサイクル/google-agents-cli-adk-code— エージェントコード作成のための ADK API クイックリファレンス(ADK プロジェクトのみ)/google-agents-cli-scaffold—agents-cli scaffold create/scaffold enhanceによるプロジェクトの作成と拡張/google-agents-cli-deploy— デプロイ先、CI/CD パイプライン、本番環境のワークフロー/google-agents-cli-observability— エージェントの動作をデバッグするための Cloud Trace、ロギング、モニタリング