agent-platform-autorater-customization

Agent Platform の自動評価器のカスタマイズ

このスキルは、ユーザー独自の判断基準に従ってエージェントを評価する採点器の作成を支援します。読み取り、作成、テストはあなたが行い、判断が必要な箇所はユーザーが決定します。その結果、ユーザーが重視する各基準について1つ以上のメトリクスが作成され、Agent Platform の評価サービスに登録されます。

以下の手順を順番に実行してください。ユーザーに要約しないでください。

使用状況のアトリビューション

必ずお読みください：gcloud、REST API、または MCP のコマンドを実行する前に、必ず 使用状況のアトリビューションを読み、その指示に従ってください。

セットアップ

最初の評価呼び出しの前に各項目を確認し、不足しているものがあればユーザーに対応を依頼してください。ユーザーの環境が変更されるため、何かをインストールする前に確認してください。

1. Python SDK。 評価用の追加機能を含めて、Agent Platform SDK をインストールまたはアップグレードします。

   pip install --upgrade 'google-cloud-aiplatform[evaluation]>=2.8.0,<3'
   

   引用符はそのままにしてください。引用符を付けないと、シェルは >= をリダイレクトとして解釈します。認証には gcloud CLI も必要です。見つからない場合は、インストールせずに https://cloud.google.com/sdk/docs/install を案内してください。

2. プロジェクトと課金。 ユーザーが指定したプロジェクトを使うか、プロジェクトを尋ねてください（gcloud config set project {project_id}）。プロジェクトには有効な課金アカウントが必要です。評価呼び出しはモデルの使用量として課金されます。現在の料金については https://cloud.google.com/pricing を参照してください。金額は伝えないでください。

3. API。 Agent Platform API を有効にします。 gcloud services enable aiplatform.googleapis.com。

4. 認証。 CLI には gcloud auth login、SDK とスクリプトには gcloud auth application-default login を実行するか、GOOGLE_APPLICATION_CREDENTIALS にサービスアカウントのキーファイルを設定します。

5. IAM。 評価の実行とメトリクスの登録には、ユーザーまたはサービスアカウントに roles/aiplatform.user が必要です。roles/aiplatform.admin など、より広範なロールは付与しないでください。不足している場合は、ユーザーに、より限定的なロールを申請するよう依頼してください。

6. リージョン。 ユーザーが別のリージョンを必要としない限り、us-central1 を使用してください（https://cloud.google.com/about/locations を参照）。

ユーザーとの作業

• 承認の各時点で、提案を提示し、「この内容を変更しますか、それともこのバージョンで進めますか？」と尋ねてください。明確な「はい」を待ってください。返答がないことは承認ではありません。
• セットアップの選択肢（プロジェクト、リージョン、ストレージ）については、デフォルトを提案してください。
• ユーザーが確認するすべての内容（ケース、評価結果、メトリクス定義）はチャットではなく、レビュー用ページに記載してください。チャットでの進捗報告では、実施したこと、数値、必要な対応を伝えてください。
• チャットで軌跡について尋ねるときは、関連する行を引用してください。

入力

ユーザーは、問題があったと考える軌跡と、良好な軌跡をいくつか含むフォルダーを用意します。任意で、各軌跡のメモや評価（サムズアップ／ダウン、人によるスコア、以前の自動評価器による判定）、既存の評価基準、または参照回答を用意できます。

• 評価サービスでの採点に時間や費用がかかりすぎない限り、すべて使用してください。その場合は、失敗例と良好なケースをいくつか網羅するサンプルについてユーザーと合意し、除外した内容を伝えてください。
• AgentData JSONL が最適です。軌跡の変換を参照してください。形式を確信を持って AgentData に対応付けられない場合は、推測しないでください。AgentData に変換する必要があると伝え、スキーマ、変換ツール、または手作業で対応付けた例を1つユーザーに求めてください。その後、変換した各ケースを確認してください。
• データセットの作成は、このスキルの役割ではありません。ユーザーにフォルダーがまだない場合は、軌跡の選定と変換を支援してから、続行してください。

用語

• 評価基準： エージェントの動作についてユーザーが重視する項目です。回答が正しいこと、適切なツールが呼び出されること、システム指示が一貫して守られることなどが該当します。評価基準はデータセット全体に適用され、すべての軌跡またはすべてのターンがその基準で評価されます。一部では N/A とすることもできます。
• ルーブリック： はい／いいえで判定するチェック項目です。
• メトリクス： 評価サービスで評価基準を採点する方法です。コード、1 つのルーブリック、または複数の重み付きルーブリックがあります。評価基準には必要な数のメトリクスを設定できます。たとえば、ツール呼び出しをコードでチェックし、回答をジャッジで評価できます。

事前定義済みの複数ターン用メトリクスも、インテントを重要度付きのルーブリックに変換しますが、合格したルーブリックの比率を重み付けせずに採点します。カスタムメトリクスでは、ユーザーのエージェント用に作成したルーブリック、重み、必須合格ルーブリック、および合格しきい値を追加できます。

手順

1. 入力を確認する

フォルダーの場所と、軌跡にメモや評価が付いているかを尋ねます。

2. 評価基準を提案する（承認）

軌跡とユーザーのメモを読み、データで裏付けられる範囲で、ユーザーが重視する問題をカバーできる最小限の評価基準を提案します。評価基準は、軌跡のどの部分でも対象にできます。最終回答、ツール呼び出しと引数、システム指示への準拠、エラーや確認への対応などです。マルチエージェントシステムでは、システム全体（ルーティング、最終回答）またはサブエージェントのどちらを対象にする評価基準なのかを明示します。それぞれについて、次の情報を提示します。

• 1 行でまとめた説明と、このエージェントにとって重要な理由。
• 問題が見られるケースの数と、引用した例を 1 つ。
• その評価基準用に作成するメトリクス（手順 4 を参照）と、その理由を 1 行で説明したもの。

データまたはユーザーのメモを根拠として示せない評価基準は提案しないでください。確信の持てない評価基準は、その理由（たとえば、ツールの結果が削除されているため採点できないなど）とともに明記します。また、既存の評価に問題があれば記録します。たとえば、エージェントが利用したデータをジャッジが参照できなかった、軌跡から証拠が削除されていた、正解データが実行されていなかった、といった問題です。

この手順では評価サービスへの呼び出しは行いません。失敗したケースが 10 件以上あり、パターンの特定をユーザーが希望する場合は、MULTI_TURN_TASK_SUCCESS で評価し、手順 3 の後に client.evals.generate_loss_clusters を実行できます。Loss clusters は global リージョンでのみ動作し、multi_turn_task_success と multi_turn_tool_use_quality の場合に限られます。カスタムメトリクスでは使用できません。

承認された評価基準を criteria.md として保存します。

3. データのルールと費用に合意する（承認）

軌跡を評価サービスに送信してよいか、課金対象のプロジェクト、および出力の保存先を尋ねます。呼び出し回数（ケース数 × メトリクス数 × サンプル数 × ラウンド数。ステップベースのメトリクスでは、ステップごとに 1 回呼び出し）を示し、費用については https://cloud.google.com/pricing を案内します。それを超える実行を行う前に、必ず再度確認してください。

4. メトリクスを構築する

基準の評価には、最もシンプルな形式を使います。シンプルな形式ほどコストが低く、毎回同じ結果になり、信頼しやすくなります。

評価する基準	形式	SDK
出力または軌跡に対する厳密なルール（ツール名、形式、数値など）	コード	types.CodeExecutionMetric（サービス内で実行され、登録可能）
すべてのケースに共通する単一の判定	LLM、単一のルーブリック	types.LLMMetric（はい／いいえの判定と参照を使用）
重要度が異なる複数のチェック	LLM、重み付きルーブリック	types.StepBasedLLMMetric（判定ステップは1つで、コードが重み付きスコアを計算）
ケースごとに異なり、適切な参照がないチェック	生成されたチェックリスト	types.StepBasedLLMMetric（1つのステップで会話からチェック項目を作成し、もう1つのステップで評価）
長いトレースや複数ターンのトレース、ターンごとの判定、または複数の判定段階	ステップベース、複数段階	types.StepBasedLLMMetric
マルチエージェントシステムの単一のサブエージェント	ステップベース、単一エージェント	そのエージェントのイベントを保持するコード前処理器を備えた types.StepBasedLLMMetric

各メトリクスは、メトリクステンプレートにあるテンプレートから始めます。各テンプレートには、評価できない項目が記載されています。重み付きルーブリックを使う場合は、ルーブリック、各ルーブリックの重み、必須合格ルーブリック、合格しきい値を提案し、判定側が各ルーブリックを個別に評価できるよう、重みはパーサーコードに記述します。LLM チェックの作成の説明に従ってチェック項目を作成します。複数ターンの会話では、基準ごとに各ターンを評価するか、会話全体を評価するかを決めます。複数ターンの会話を参照してください。

5. 評価して結果を表示する

scripts/run_metrics.py を使って評価サービス経由でケースを評価し、次に scripts/build_review_page.py を使ってレビュー用ページを作成します。ページ上の PASS と FAIL がメトリクスと一致するよう、各メトリクスの合格しきい値を --threshold として渡します。

任意：ユーザーが既存の自動評価器を持っている場合、または MULTI_TURN_TASK_SUCCESS などの組み込みメトリクスとの比較を希望する場合は、それも使って評価し、ベースラインとして表示します。呼び出し回数は増えます。また、組み込みメトリクスはユーザーの基準ではなく、タスク全体の成功を評価します。

6. 任意：ユーザーの評価に合わせてメトリクスを調整する

ユーザーに評価結果にラベルを付けてもらい、その結果を使ってメトリクスを改善するかどうかを尋ねます。1ケースあたり約1分かかります。希望しない場合は、ステップ7に進みます。

1. ケースの約20%を保留用として取り分けます。保留したケースを含めずにレビュー用ページを作成します。
2. ユーザーはレビュー用ページで各判定に「Agree」または「Disagree」のラベルを付け、同意しない場合は理由を記入し、labels.json を渡します。ユーザーがすでに人手による評価を持っている場合はそれを使い、メトリクスの判定と食い違うケースについてのみ尋ねます。
3. scripts/agreement.py を使って、メトリクスごと、ルーブリックごとに一致度を計算します。変更を信頼する前に判定のノイズを測定します。ノイズと一致度を参照してください。
4. メトリクスを自分で改訂し（ルーブリックの文言、重み、必須合格ルーブリック、しきい値、参照、コード）、各ラウンドを新しいバージョンとして保存して再評価し、変更点と新しい一致度をユーザーに示します。ラベルが軌跡と矛盾する場合は、該当する行を引用してユーザーに尋ねます。
5. 一致度がノイズを超えて改善しなくなるか、ユーザーが納得するまで続けます。保留用のケースは1回だけ評価します。それらを使って改訂してはいけません。保留用ケースで問題が見つかった場合は、過剰適合を報告し、ラベル付きケースの追加を提案します。

7. レビューと登録（承認）

メトリクスの登録がこのスキルの目的です。レビュー用ページに、各メトリクスの基準、最終定義（ルーブリック、重み、必須合格ルーブリック、しきい値、判定モデル、サンプル数）、評価結果、ステップ 6 を実施した場合はラベル付け済みケースと保留ケースでの一致度、未解決の質問を追加します。承認後、create_evaluation_metric で各メトリクスを登録します。登録すると共有リソースが作成されます。

以下を含む出力フォルダーを引き渡します。

• criteria.md：承認済みの基準。それぞれに、その基準を評価するメトリクスを記載します。
• metrics/：すべてのメトリクスの最終定義。評価サービスが実行したファイル（scripts/run_metrics.py に渡したメトリクスファイル）を、登録名とともに格納します。
• metrics.md：メトリクスごとに 1 項目を記載し、基準、形式、ルーブリック、重み、必須合格ルーブリック、しきい値、判定モデル、サンプル数、および登録名で実行するコードスニペットを含めます。
• ステップ 6 を実施した場合は、labels.json と以前のバージョン。
• report.md：数値と未解決の質問。

メトリクスをデータセット全体で実行するには、agent-platform-eval-flywheel を指定します。

レビューページ

各ラウンドにつき、scripts/build_review_page.py で自己完結型の HTML ページを 1 つ作成し、そのパスをユーザーに伝えます（または、ユーザーのブラウザーからアクセスできる場所で配信します）。各ケースには、ユーザーのメモまたは評価、各メトリクスの PASS/FAIL、スコア、説明、ルーブリックの判定、実行した場合はベースライン、およびツールの結果を折りたたんだ軌跡が表示されます。ユーザーは各判定について理由を添えて Agree または Disagree を選択します。マークはブラウザーに保存され、「Download labels.json」で scripts/agreement.py が読み込む形式でエクスポートされます。チャットでユーザーにラベルの入力を求めないでください。

ルール

• すべての評価は評価サービスを通じて行います。ラベルはユーザーからのみ取得します。軌跡を評価したり、自分のモデル呼び出しやサブエージェントでラベル案を作成したりしないでください。別のモデルのラベルに合わせてメトリクスを調整すると、モデル同士を同意させることしか学習できないためです。
• 作成中はフォルダー内のケースのみを評価します。データセット全体を使うのは登録後です。
• 報告する数値はすべて、結果ファイルから取得します。実行結果に差がある場合は範囲を報告します。
• レビューページを含め、独自の軌跡や出力は、ユーザーが指定した場所に保管します。共有ドキュメント、バグ報告、チャットに貼り付けないでください。
• 名前を使う前に、インストール済み SDK のソースを確認してください。バージョンによって異なります。

クリーンアップ

登録済みのメトリクスは、削除されるまでプロジェクトに残ります。ユーザーが使用しなくなったメトリクス、または誤って登録したメトリクスの削除を希望する場合は、名前を確認してから、client.evals.delete_evaluation_metric(metric_resource_name={name}) を実行します。client.evals.list_evaluation_metrics() で一覧を取得できます。ローカル出力（結果、レビューページ、ラベル）はユーザーが選んだ場所に残ります。最後に削除するかどうかを確認してください。

スクリプト

いずれも --help を指定できます。

• scripts/render_agent_data.py：軌跡を読みやすいテキストに変換します。
• scripts/run_metrics.py：client.evals.evaluate() で SDK メトリクスを実行します。
• scripts/build_review_page.py：レビューページとラベルのエクスポートを行います。
• scripts/agreement.py：メトリクスごと、ルーブリックごと、またはターンごとの一致度、Cohen のカッパ係数、不一致を算出します。

参考資料

• 軌跡の変換
• メトリクスのテンプレート
• LLM チェックの作成
• 複数ターンの会話
• ノイズと一致度
• SDK での注意点