agent-platform-eval-flywheel

エージェントプラットフォーム評価フライホイールスキル

Agent Platform GenAI Evaluation SDK（google.genai／agentplatform）を使用して、GenAI モデルとエージェントの評価および継続的な改善を支援します。

このスキルを使用する場面

• Agent Platform GenAI Evaluation SDK（client.evals.evaluate()）を使用して、GenAI エージェントまたはモデルを評価する場合。
• セッショントレース、pandas DataFrame、または合成データ生成から評価データセットを作成する場合。
• 評価指標を選択、設定、またはカスタム作成する場合。
• ルーブリックの判定、損失パターン、失敗のクラスタリングを分析する場合。
• 評価結果に基づいて、具体的なコードやプロンプトの改善案を提案する場合。
• Agent Platform のエンドポイント（BYOM）で提供されるモデル、または ID で指定する**Model-as-a-Service（MaaS）**モデルを評価する場合。必要であれば、モデルのデプロイも含みます。この場合は、references/deployment.mdに従い、endpoint_evaluation.py／maas_evaluation.pyスクリプトを使用してください。

安全性と確認のティア（重要）

ユーザーに代わってコマンドやスクリプトを実行する前に、要求された操作に応じた以下の安全性ティアに必ず従ってください。

1. ティア R：読み取り専用（inspect_results.py、compare_results.py、validate_dataset.py、parse_adk_traces.py、render_html_report.py）
   • ルール：確認は不要です。データの確認、スキーマの検証、トレースの解析、評価結果の比較のために、これらのヘルパースクリプトをすぐに実行できます。
2. ティア M：コンピューティングコストが発生する読み取り専用操作（client.evals.run_inference、client.evals.evaluate、client.evals.generate_conversation_scenarios、client.evals.generate_loss_clusters）
   • ルール：これらの操作は、コンピューティングリソースを消費してコストが発生する LLM またはリモート評価サービスを呼び出します。そのため、［はい］／［いいえ］の選択肢を含む対話型の確認が必要です。
   • 評価を実行するたびに確認：評価、再評価、評価指標の更新、パラメーターの変更、合成シナリオの生成には、それぞれ独自のドライランプレビューと対話型の確認が必要です。新たな確認プレビューを提示してユーザーの承認を得ずに、2回目の評価、比較処理、または変更後の評価を実行してはいけません。
   • 同一ターンでの実行禁止：確認を求めるプロンプトを提示したターンと同じターン内で評価を実行してはいけません。質問した後はターンを終了し、ユーザーの返信を待ってください。明示的な［はい］／承認を得てから実行してください。プレビューを表示してからユーザーが回答できる前にツールを呼び出しても、確認を得たことにはなりません。
   • リモート評価の事前実行禁止：ユーザーの確認を得る前に、client.evals.evaluate()、client.evals.run_inference()、client.evals.generate_conversation_scenarios()を実行したり、これらのリモート操作を呼び出すスクリプトを実行したりしてはいけません。最初のターンでは、ローカルのデータ構造を準備してスクリプトを作成してもかまいませんが、リモート評価またはシナリオ生成の呼び出しを実行する前に、必ずドライランプレビューカードを提示し、ユーザーから明示的な確認を得てください。
   • 承認後はただちに実行：ユーザーが明示的に承認したら（例：「はい」「承認しました」「進めてください」「実行してください」）、run_commandを使用してプレビュー済みの評価スクリプトをただちに実行し、結果を報告してください。承認された操作を実行せずにターンを終了してはいけません。

セットアップ

スクリプトには vertexai（google-cloud-aiplatform[evaluation] に含まれます）、 google-genai、pandas、requests が必要です。仮想 環境は作成しないでください。空の状態で始まり、環境にすでに用意されている パッケージが見えなくなるため、不要なインストールを強いられます。まず確認し、不足しているものだけをインストールしてください。

python3 -c "import vertexai, google.genai, pandas, requests" \
  || pip install 'google-cloud-aiplatform[evaluation]>=1.163.0' 'google-genai>=1.0.0'

バージョン指定子は引用符で囲む必要があります。引用符がないと、bash は >=1.154.0 を リダイレクトとして読み取り、インストールを制限する代わりに空のファイルを黙って書き込みます。

GOOGLE_CLOUD_PROJECT と GOOGLE_CLOUD_LOCATION が必要です。

• ユーザーのプロジェクトとロケーションを維持する：ユーザーが 明示したプロジェクトとロケーション（例：project='<PROJECT_NUMBER>'、 location='us-central1'）を常に優先してください。ユーザーが明示的に 'global' を指定していない限り、指定されたロケーションを 'global' に変更したり上書きしたりしないでください。
• パラメーターが不足している場合：ユーザーのリクエストにプロジェクトまたはロケーションが含まれていない場合、評価の準備または実行を行う前に、応答を一時停止して不足しているロケーションまたはプロジェクトをユーザーに尋ねる必要があります。

正しい SDK エントリーポイント

import agentplatform
client = agentplatform.Client(project=PROJECT, location=LOCATION)

client.evals.run_inference(model=..., src=...)
client.evals.evaluate(dataset=..., metrics=...)
client.evals.generate_conversation_scenarios(...)

一見正しそうですが、実際には使えないインポートが 2 つあります。

• from agentplatform.types import evals -- ModuleNotFoundError が発生します。types はパッケージではなくモジュールです。from agentplatform import types を使用してください。
• from vertexai.evaluation import PointwiseMetric, EvalTask -- これは旧 SDK です。クラスに異なる引数が必要です（PointwiseMetric に system_instruction はありません）。そのため、この SDK に基づいて書かれたコードはインポートエラーではなく TypeError で失敗します。全体を通して agentplatform を使用してください。

品質向上サイクル

5 つのステージを初回は順番に実行し、その後、品質目標を達成するまで 2 → 5 を繰り返します。

時間を無駄にする近道

近道	うまくいかない理由
"メトリックのしきい値を下げて通るようにしよう	実際の失敗が隠れてしまいます。基準では
: 。" : なく、エージェントを修正してください。
"このケースは不安定だから、飛ばそう。"	不安定さはエージェントの非決定性を示し
: : ています。temperature=0 または、より厳
: : 密な指示で修正してください。
"エージェントではなく、評価用	期待される出力が変わり続けるなら、
: データセットを直せばいい。" : エージェントに動作上の問題があります。
"トレースを見れば動作しているとわかる	自己評価は一般化できません。常に
: から、ステージ 3 は飛ばそう。" : evaluate() を実行し、スコアを確認して
: : ください。
"1 回反復すれば十分です。"	5～10 回以上の反復を想定してください。早
: : くやめると、他のメトリックに対する回帰を
: : 検出できないままになります。

1. データを準備する

EvaluationDataset を作成します。入力形式は 3 種類あります。ユーザーがすでに持っているデータに合うものを選んでください。

• EvalCase リスト（単一ターンまたは複数ターン）：

  from agentplatform import types
  from google.genai import types as genai_types
  
  # prompt/reference/response の値は str ではなく Content です。UserContent と
  # ModelContent はプレーンな文字列をラップし、適切なロールを設定します。
  dataset = types.EvaluationDataset(eval_cases=[
      types.EvalCase(
          prompt=genai_types.UserContent("What is 2+2?"),
          responses=[types.ResponseCandidate(
              response=genai_types.ModelContent("4"))],
          reference=types.ResponseCandidate(
              response=genai_types.ModelContent("4")),
      ),
      # 複数ターンのエージェントトレースでは、prompt/responses の代わりに agent_data を設定します。
  ])
  

  マルチターンのエージェントトレースでは、各会話を AgentData → ConversationTurn → AgentEvent の順にラップします。型階層の全体については、 references/dataset_schema.md を参照してください。

• Pandas DataFrame（表形式のソース — CSV、BigQuery、Sheets）：

  import pandas as pd
  from agentplatform import types
  
  df = pd.DataFrame({
      "prompt":    ["What is 2+2?", "Capital of France?"],
      "response":  ["4",            "Paris"],
      "reference": ["4",            "Paris"],
  })
  dataset = types.EvaluationDataset(eval_dataset_df=df)
  

  列名は、選択したメトリクスが想定するフィールドと一致している必要があります（メトリクスごとの要件表については references/dataset_schema.md を参照してください）。

• コールドスタート（データがまったくない場合）： client.evals.generate_conversation_scenarios(agent=..., config=...) を使って、サーバー側でシナリオを合成します。パラメーターは agents ではなく agent または agent_info であり、config は必須です。設定クラスは types.UserScenarioGenerationConfig ではなく types.evals.UserScenarioGenerationConfig です。その user_scenario_count（1～100）を設定してください。デフォルトは None で、クライアントはその値を受け付けますが、サーバーは呼び出しを 400 INVALID_ARGUMENT で拒否します。count は別のフィールドであり、 その代わりにはなりません。ステージ 2 でシナリオを実行します。

  • 重要 — マルチターンのユーザーシミュレーションシナリオには、この API を使用する必要があります： ユーザーから、エージェントとやり取りする顧客をシミュレートするマルチターンのユーザーシナリオの合成を求められた場合（サンドボックス内でローカルなシングルターンのテストデータセットを作成する場合を除く）、会話シナリオを文章や手書きのファイルで自作してはいけません。 client.evals.generate_conversation_scenarios の呼び出しは、ユーザーのプロジェクト、ロケーション、モデル、環境データを使用するサーバー側の Tier M API 呼び出しであり、確認カードが必要です。Agent Platform API を呼び出さずにサンドボックス内で作成するローカルなシングルターンのデータセットファイルは Tier R です。
  • 重要 — 指定が不十分なリクエスト：シナリオの合成を依頼されたとき、リクエストに必須パラメーター（location、environment_data、simulation_instruction、model_name など）が欠けている場合、デフォルトを想定したり、値を推測したりしてはいけません。最初のターンで必ず一時停止し、不足している情報を明示的にユーザーに尋ねてください（例：「不足しているシミュレーション指示、環境データ、モデル名、ロケーションを指定してください」）。ユーザーが情報を提供してから、ドライランのプレビューに進んでください。location に安全なデフォルトはありません。us-central1 も、別の呼び出しで独自に想定したロケーションも、ユーザーが指定していないロケーションの代わりにはなりません。
  • 確認とパラメーターの変更：合成ユーザーシナリオの生成を依頼されたとき、ユーザーが要求したパラメーター（シナリオ数、モデル、指示など）を変更した場合、または異議を唱えた場合は、更新されたパラメーターを記載した修正版のドライラン確認カードを必ず提示し、run_command で生成コードを実行する前に、ユーザーから明示的な承認を得てください。

• マネージドエージェント（Gemini Agents API）： Managed Agents API で作成されたエージェントを評価します。 generate_conversation_scenarios でエージェントの設定からテストシナリオを作成し、run_inference でエージェントを実行し、evaluate でトレースをスコアリングします。これらの関数は現在、マネージドエージェントとインタラクション ID を入力として受け付けます。また、InteractionsDataSource を使って、Interactions API 経由で記録された既存のインタラクションを評価することもできます。コードパターンの全体については、references/sdk_patterns.md のパターン 8 を参照してください。 ADK セッションダンプには、変換を手作業で記述する代わりに scripts/parse_adk_traces.py を使用してください。

2. 推論を実行する

データセットにレスポンス／トレースを追加します。トレースがすでに揃っている場合（本番環境のログやリプレイなど）は、このステージをスキップしてください。

# Agent eval — pass a callable wrapping the user's ADK Agent/App.
client.evals.run_inference(model=agent_callable, src=dataset)

# Model eval — pass a model ID directly.
client.evals.run_inference(model="gemini-2.5-flash", src=dataset)

# Synthesized scenarios — let the simulator drive.
client.evals.run_inference(
    model=agent_callable,
    src=dataset,
    user_simulator_config=UserSimulatorConfig(max_turn=10),
)

# DataFrame also works as src= — no EvalCase wrapping needed.
client.evals.run_inference(model="gemini-2.5-flash", src=df)

# Managed Agent — pass an agent resource name.
AGENT_RESOURCE = f"projects/{PROJECT_ID}/locations/global/agents/{AGENT_ID}"
client.evals.run_inference(
    agent=AGENT_RESOURCE,
    src=scenarios,
    config={"user_simulator_config": {"max_turn": 3}},
)

3. 評価する（必ず実行）

result = client.evals.evaluate(dataset=dataset, metrics=[...])
result.show()  # Interactive HTML report with scores, rubrics, and traces.

測定したい内容に応じてメトリクスを選んでください。 全メトリクスの一覧は references/metric_registry.md を参照してください。

ユーザーがメトリクスを指定した場合は、それをそのまま使用してください。 以下の表にあるすべての識別子 （general_quality、text_quality、instruction_following、 hallucination、grounding、safety、multi_turn_*、final_response_*、 tool_use_quality）は types.RubricMetric.<UPPERCASE_NAME> アクセサーです。 metrics=[types.RubricMetric.GENERAL_QUALITY, ...] にそのまま渡してください。 ここにある名前に対してカスタムの LLMMetric を作成しないでください。また、 vertexai.evaluation.EvalTask／PointwiseMetric／ MetricPromptTemplateExamples に頼らないでください。この SDK は後継に置き換えられています（「セットアップ」を参照）。

judge_model の形式と、ユーザーが指定したモデルの扱い：

• judge_model には完全なリソース名が必要です：LLMMetric と RubricMetric のどちらも、judge_model を autorater_config.autorater_model として バックエンドに送信します（agentplatform が RubricMetric に対してクライアント側で「ignored」 警告をログに記録する場合でも同様です）。"gemini-2.5-flash" や "gemini-2.5-pro" のような短い名前は、 400 INVALID_ARGUMENT ("Invalid autorater model resource name") で失敗します。必ず完全なパブリッシャーモデルのリソース名を渡してください： f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_NAME}" （オートレイターには gemini-2.5-flash を推奨します。gemini-2.5-pro はサーバー側で "Rubric results could not be reliably computed" が断続的に発生する場合があります）。
• レスポンスがないデータセットと、レスポンスがあるデータセット：
  • データセットに プロンプトのみ が含まれる場合（response 列がない場合）は、 まず run_inference(model="<the named model>", src=dataset) を呼び出して 候補モデルのレスポンスを生成し、その後 evaluate() で評価してください。
  • ユーザーがデータセットで response をすでに指定している場合は、run_inference を呼び出さないでください。 run_inference は既存の response 列をモデルが生成した出力で上書きし、ユーザーのレスポンスを破棄します。 代わりに、evaluate(dataset=dataset, ...) でユーザーが指定した response を直接評価し、 指定されたモデルを judge_model に完全なリソースパスで渡してください （または、定義済みの RubricMetric がそのオートレイターモデルでルーブリックの結果を確実に計算できない場合は、 デフォルトのオートレイターに切り替え、その理由を説明してください）。

エージェントのメトリクス（複数ターン、適応型ルーブリック） — エージェント評価はここから始めます。

目標	メトリクス
エージェントはユーザーの目標を達成しましたか？	multi_turn_task_success
推論経路は論理的かつ効率的でしたか？	multi_turn_trajectory_quality
ターンをまたいだツール／関数呼び出しの品質	multi_turn_tool_use_quality
会話全体の品質	multi_turn_general_quality
最終レスポンスの品質（参照不要）	final_response_quality
最終レスポンスとゴールデンリファレンスの比較	final_response_match
単一ターンのツール使用	tool_use_quality

一般的な品質メトリクス（単一ターン、適応型ルーブリック） — モデル評価に使用します。

目標	メトリクス
レスポンス全体の品質（推奨される開始点）	general_quality
言語面の品質（流暢さ、一貫性、文法）	text_quality
特定の制約／指示への準拠	instruction_following

静的ルーブリックメトリクス（固定基準） — 上記と併用します。

目標	メトリクス
幻覚のある主張を検出する（RAG、事実に基づく回答）	hallucination
提供されたコンテキストに対する事実性／一貫性	grounding
安全性ポリシーへの準拠	safety

組み込みのメトリクスでは対応できないドメイン固有のチェック: カスタムメトリクスを作成します。

• 定義済み: types.RubricMetric.<NAME> — サーバー側の AutoRater を使うため、評価モデルは不要です。
• カスタムの LLM-as-a-judge: prompt_template を指定した types.LLMMetric、または構造化ルーブリック用の types.MetricPromptBuilder を使います。必ず judge_model を設定してください。デフォルトは None であり、設定しない場合はすべてのケースで 400 INVALID_ARGUMENT: Error parsing JSON が発生します。
  • 評価モデルの選択: ユーザーが評価モデル（例: gemini-2.5-pro）を指定した場合は、それを使います。ユーザーが評価モデルを指定しない場合、または評価モデルに関する情報や希望がないと述べた場合は、ドライランのプレビューカードで gemini-2.5-flash を評価モデルのデフォルトとして提示し、評価を実行する前に確認を求めます。ユーザーが評価モデルを指定していないからといって、評価を中止したり拒否したりしないでください。
• カスタムコード: リモートのサンドボックス実行には、def evaluate(instance: dict) を含む custom_function 文字列を指定した types.CodeExecutionMetric を使います。ローカル実行には、custom_function=<callable> を指定した types.Metric を使います。instance dict の prompt / response / reference は文字列ではなく Content dict です。評価を実行して形式を確認するのではなく、関数本体を作成する前に references/metric_registry.md の「関数が受け取るもの」を読んでください。

Stage 4 と 5 で結果を読み取れるよう、必ず結果を保存してください。 JSON（機械可読で差分確認可能）と HTML（人が読めてリンク可能）の両方を保存します。

import datetime
from pathlib import Path

from agentplatform._genai import _evals_visualization

out_dir = Path("artifacts/grade_results")
out_dir.mkdir(parents=True, exist_ok=True)
ts = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")

# fallback=str, or a DataFrame-backed dataset raises PydanticSerializationError.
result_json = result.model_dump_json(fallback=str)
(out_dir / f"results_{ts}.json").write_text(result_json)

html = _evals_visualization.get_evaluation_html(result_json)
(out_dir / f"results_{ts}.html").write_text(str(html))

事後に実行する場合: scripts/render_html_report.py --type evaluation または scripts/inspect_results.py --save-html。

4. 失敗を分析する

summary_metrics と eval_case_results を読みます。スコアを決して捏造しないでください。失敗だけに絞り込むには、 scripts/inspect_results.py --failing-only を使用します。

失敗した各指標について、詳しい診断は references/failure_patterns.md を参照してください。簡潔な対応表を以下に示します。

失敗した指標	変更する内容
multi_turn_task_success が低い	エージェントが目標を達成できていません —
: : オーケストレーション、ツール呼び出しの欠落、 :
: : 早すぎる終了、誤ったツールの選択を修正します。 :
multi_turn_trajectory_quality が低い	エージェントは目標に到達しますが
: : 効率が悪いため、計画のプロンプトを改善し、 :
: : 冗長なツール呼び出しを削除します。 :
multi_turn_tool_use_quality が低い	ツールの説明、パラメーターの
: : docstring、またはツール選択に関する :
: : エージェントの指示を修正します。 :
final_response_quality が低い	自動生成されたルーブリックの判定を読み、
: : 最も低いスコアの基準に対応するように :
: : 指示を改善します。 :
final_response_match が低い	エージェントの最終回答が正解の参照と一致しません
: : — 回答の形式を調整するか、参照を更新します。 :
hallucination が低い	ツールの出力に基づくよう指示を徹底し、
: : ツールが主張されているデータを実際に返したかを確認します。 :
grounding が低い	回答が提供されたコンテキストと矛盾しています
: : — 「コンテキストの情報のみを引用する」という明示的な指示を追加します。 :
safety が低い	安全対策のガードレールを追加し、
: : ルーブリックの判定で違反とされたコンテンツのカテゴリを確認します。 :
general_quality / text_quality	システム指示の表現を調整します。モデルの
: low : デフォルトの表現がタスクに対して汎用的すぎます。 :
instruction_following が低い	エージェントが制約を無視しています —
: : システム指示で制約を再提示するか、より厳格な表現を使います。 :
エージェントが誤ったツールを呼び出す	ツールの説明、エージェントの
: : 指示、または tool_config を修正します。 :
エージェントが余分なツールを呼び出す	明示的な停止指示を追加するか、
: : multi_turn_tool_use_quality に切り替えて、 :
: : 余分な呼び出しがルーブリックに表示されるようにします。 :

同じ指標で10件以上の失敗がある場合は、すべてのトレースを読む代わりに、Error Analysis service を使用して、失敗をテーマ（L1/L2分類のカテゴリ）ごとにクラスタリングします。

# Only supports multi_turn_task_success and multi_turn_tool_use_quality.
# Service runs in the global region.
analysis_client = agentplatform.Client(project="PROJECT_ID", location="global")
response = analysis_client.evals.generate_loss_clusters(
    eval_result=result,
    metric="multi_turn_task_success",
    config={"max_top_cluster_count": 5},
)
for r in response.results:
    for cluster in r.clusters:
        print(
            f"[{cluster.taxonomy_entry.l1_category}/"
            f"{cluster.taxonomy_entry.l2_category}] "
            f"{cluster.item_count} cases — {cluster.taxonomy_entry.description}"
        )

response.model_dump_json() を保存し、scripts/render_html_report.py --type loss-analysis を使ってレンダリングします。

5. 最適化と反復

失敗している指標を対象とした修正を適用します。ステージ 3 を再実行します。 scripts/compare_results.py --baseline <prev> --candidate <new> を使用して比較し、 対象の指標が改善し、ほかの指標が悪化していないことを確認します。

反復ごとの進捗を記録します。

Iteration	Metric A	Metric B	Change made
ベースライン	0.62	0.55	—
v2	0.78	0.68	グラウンディングプロンプトを追加
v3	0.81	0.72	ツール選択を修正

失敗したケースごとに、5～10 回以上の反復を想定してください。ケースに合格してからのみ、 評価ケースを増やして対象範囲を拡大してください。

作業の証明

実際の result オブジェクトから読み取っていない評価結果を、決して主張しないでください。

• 評価を実行した後、summary_metrics テーブルを出力します （scripts/inspect_results.py）。
• 修正後、scripts/compare_results.py で修正前と修正後を示します。
• 成功を宣言する前に、作業対象のケースだけでなく、すべてのケースに合格していることを確認します。

証拠を提示できない場合（SDK 呼び出しの失敗、結果の切り捨て、未対応の指標など）は、その旨を明確に伝えてください。不足を取り繕わないでください。

実行ルール

1. 必ず最初に計画する： スクリプトを書く前に、実行する手順を詳しく記した <plan> ブロックを出力します。
2. ステップごとに実行する： データと評価スクリプトを準備し、全パラメーターを含むドライラン確認カードを提示して、ユーザーの承認を待ちます。明示的な確認を得てから実行し、その後に結果を調査して分析します。ユーザーの確認前に評価呼び出しを実行してはいけません。
3. 標準の Python を使用する： 標準的な Python インポート（import agentplatform、 from google.genai import types）を使用します。内部インポートパスは使用しないでください。
4. 推測する前に確認する： SDK の型や指標に確信が持てない場合は、推測したり、事実でないことを作り出したりせず、SDK のソースコードを確認します。
5. 何も伝えずにターンを終えない： 毎回のターンで、実行した操作の概要または次のステップを示す、空でない有益なテキストをユーザーに返します。ツールが何を実行していても、何も返さないと失敗と見なされます。

SDK クイックリファレンス

import agentplatform
from agentplatform import types
from google.genai import types as genai_types
import pandas as pd

# Initialize client
client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

# --- SINGLE-TURN EVAL (pandas DataFrame) -- RECOMMENDED ---
# The converter wraps plain strings for you.
df = pd.DataFrame({
    "prompt":   ["Q1", "Q2"],
    "response": ["A1", "A2"],
})
dataset = types.EvaluationDataset(eval_dataset_df=df)

# --- SINGLE-TURN EVAL (direct EvalCase) ---
# Verbose and easy to get wrong; see references/dataset_schema.md for the
# exact types before using this form.
dataset = types.EvaluationDataset(eval_cases=[
    types.EvalCase(
        prompt=genai_types.UserContent("Query here"),
        responses=[types.ResponseCandidate(
            response=genai_types.ModelContent("Model response here"))],
        reference=types.ResponseCandidate(
            response=genai_types.ModelContent("Ground truth here")),
    ),
])

# --- MULTI-TURN AGENT EVAL ---
agent_data = types.evals.AgentData(
    agents={"my_agent": types.evals.AgentConfig(
        agent_id="my_agent", instruction="You are helpful.")},
    turns=[types.evals.ConversationTurn(turn_index=0, events=[
        types.evals.AgentEvent(author="user",
            content=genai_types.Content(role="user",
                parts=[genai_types.Part(text="Hello")])),
        types.evals.AgentEvent(author="my_agent",
            content=genai_types.Content(role="model",
                parts=[genai_types.Part(text="Hi! How can I help?")])),
    ])],
)
dataset = types.EvaluationDataset(
    eval_cases=[types.EvalCase(agent_data=agent_data)])

# --- METRICS ---
predefined = types.RubricMetric.MULTI_TURN_TRAJECTORY_QUALITY
custom_llm = types.LLMMetric(name="tone",
    prompt_template="Is this polite? Response: {response}")
custom_code = types.CodeExecutionMetric(name="check",
    custom_function='def evaluate(instance): return {"score": 1.0}')

# --- EVALUATE ---
result = client.evals.evaluate(dataset=dataset, metrics=[predefined])

# --- RESULTS ---
for s in result.summary_metrics:
    print(f"{s.metric_name}: mean={s.mean_score}, pass_rate={s.pass_rate}")
for case in result.eval_case_results:
    for cand in case.response_candidate_results:
        for name, r in cand.metric_results.items():
            print(f"  {name}: score={r.score}, explanation={r.explanation}")

高度なパターン（合成データの生成、ペアワイズ比較、MetricPromptBuilder、 マルチエージェント評価）については、references/sdk_patterns.md を参照してください。

同梱スクリプト

Script	When to use
validate_dataset.py	ステージ 3 の前に、形式が不正な EvaluationDataset JSON を検出します。
parse_adk_traces.py	ステージ 1 で、ADK セッションダンプを標準データセット形式に変換します。
inspect_results.py	ステージ 3／4 で、概要とケースごとのスコアを表示します。--save-html を指定すると、ブラウザーで閲覧できるレポートを保存します。
compare_results.py	ステージ 5 で、ベースラインと候補を比較し、リグレッションを検出します。
render_html_report.py	保存済みの結果 JSON または損失クラスタ JSON から HTML を生成します。
endpoint_evaluation.py	デプロイ済みの Agent Platform エンドポイント（BYOM）に対して、ステージ 2／3 を実行します。references/deployment.md を参照してください。
maas_evaluation.py	ID で指定した Model-as-a-Service モデルに対して、ステージ 2／3 を実行します。references/deployment.md を参照してください。