agent-platform-eval-flywheel

Agent Platform Eval Flywheel Skill

協助使用者運用 Agent Platform GenAI Evaluation SDK (google.genai / agentplatform)，評估並疊代提升 GenAI 模型與 Agent 的品質。

何時使用此 Skill

• 使用 Agent Platform GenAI Evaluation SDK (client.evals.evaluate()) 評估 GenAI Agent 或模型。
• 從對話軌跡（session traces）、pandas DataFrame 或合成資料生成（synthetic generation）建立評估資料集。
• 挑選、設定或撰寫自訂的評估指標（evaluation metrics）。
• 分析評分標準判決（rubric verdicts）、損失模式（loss patterns）與失敗分類聚類（clustering failures）。
• 根據評估結果提出具體的程式碼或 Prompt 改善建議。
• 透過 ID 評估託管於 Agent Platform 端點 (BYOM) 或 模型即服務 (MaaS) 上的模型——包含必要時先部署該模型。此情境請參考 references/deployment.md 並使用 endpoint_evaluation.py / maas_evaluation.py 腳本。

安全與確認分級 (CRITICAL)

在代表使用者執行任何命令或腳本之前，您必須根據請求的操作遵守以下安全分級：

1. Tier R：唯讀 (inspect_results.py, compare_results.py, validate_dataset.py, parse_adk_traces.py, render_html_report.py)
   • 規則：無需確認。您可以立即執行這些輔助腳本來檢視資料、驗證 Schema、解析 Trace 或比較評估結果。
2. Tier M：具算力成本的唯讀 (client.evals.run_inference, client.evals.evaluate, client.evals.generate_user_scenarios, client.evals.generate_loss_clusters)
   • 規則：這些操作會呼叫 LLM 或遠端評估服務，消耗運算資源並產生費用。執行前需要透過 'Yes'/'No' 選項進行互動式確認。一旦獲得授權一次，後續的評估操作無需重複詢問。

環境設定

這些腳本需要 vertexai (來自 google-cloud-aiplatform[evaluation])、google-genai、pandas 和 requests。請勿建立虛擬環境——虛擬環境初始狀態為空，會隱藏系統環境已提供的套件，導致不必要的重複安裝。請先檢測，僅安裝缺失的套件：

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

版本指定字串必須保持加引號：若未加引號，bash 會將 >=1.154.0 解釋為重導向（redirect），進而默默寫入一個空檔案，而非限制安裝版本。

需要 GOOGLE_CLOUD_PROJECT 與 GOOGLE_CLOUD_LOCATION。請先檢查環境變數；若缺失，請詢問使用者。較新的 Gemini 模型通常需要設定 location="global"。

品質飛輪 (The Quality Flywheel)

包含五個階段。首次執行時請依序推進，之後重複循環階段 2 → 5，直到達到品質目標。

浪費時間的捷徑 (Shortcuts that waste time)

捷徑	為何失敗
「我把指標門檻調低一點，這樣就能過了。」	這只會掩蓋真正的問題。請修復 Agent，而不是降低標準。
「這個測試案例很不穩定（flaky），我先跳過。」	不穩定性反映出 Agent 的非確定性（non-determinism）。請透過 temperature=0 或更嚴格的指令來修復。
「我只需要修改評估資料集，不用動 Agent。」	如果期望的輸出不斷變動，說明 Agent 本身存在行為問題。
「從 Trace 就看得出來沒問題了——跳過階段 3。」	自我評分無法泛化。請務必執行 evaluate() 並檢視分數。
「疊代一次就夠了。」	請預期需要進行 5–10+ 次疊代。過早停止會讓其他指標的迴歸問題（regressions）無法被察覺。

1. 準備資料 (Prepare Data)

建立 EvaluationDataset。共有三種輸入形式，請選擇最符合使用者現有資料的一種：

• EvalCase 列表（單輪或多輪）：

  from agentplatform import types
  dataset = types.EvaluationDataset(eval_cases=[
      types.EvalCase(prompt="What is 2+2?", response="4", reference="4"),
      # 若為多輪 Agent trace，請設定 agent_data 而非 prompt/response。
  ])
  

  多輪 Agent trace 會將每次對話包裝在 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_user_scenarios(...) 搭配 UserScenarioGenerationConfig（包含 user_scenario_count、simulation_instruction、environment_data）在伺服器端合成情境，並交由階段 2 進行模擬演練。

若是 ADK session dump，請直接使用 scripts/parse_adk_traces.py，無需手動撰寫轉換程式。

2. 執行推論 (Run Inference)

在資料集中填入回應/對話軌跡（responses/traces）。若對話軌跡已完整（例如正式環境日誌或重放資料），請跳過此階段。

# Agent 評估——傳入包裝使用者 ADK Agent/App 的可呼叫物件 (callable)
client.evals.run_inference(model=agent_callable, src=dataset)

# 模型評估——直接傳入模型 ID
client.evals.run_inference(model="gemini-2.5-flash", src=dataset)

# 合成情境——讓模擬器自行驅動
client.evals.run_inference(
    model=agent_callable,
    src=dataset,
    user_simulator_config=UserSimulatorConfig(max_turn=10),
)

# 亦可將 DataFrame 作為 src= 傳入——無需包裝成 EvalCase
client.evals.run_inference(model="gemini-2.5-flash", src=df)

3. 評分（務必執行）

result = client.evals.evaluate(dataset=dataset, metrics=[...])

依據您想測量的目標選擇指標。 完整目錄請參閱 references/metric_registry.md。

Agent 指標（多輪、自適應評分標準）——Agent 評估由此開始。

目標	指標
Agent 是否達成使用者的目標？	multi_turn_task_success
推理路徑是否合乎邏輯且有效率？	multi_turn_trajectory_quality
跨輪次的 Tool/Function 呼叫品質	multi_turn_tool_use_quality
整體對話品質	multi_turn_general_quality
最終回應品質（無需參考答案）	final_response_quality
最終回應 vs. 黃金參考答案（golden reference）	final_response_match
單輪 Tool 使用品質	tool_use_quality

一般品質指標（單輪、自適應評分標準）——用於模型評估。

目標	指標
整體回應品質（推薦作為起手式）	general_quality
語言品質（流暢度、連貫性、語法）	text_quality
對特定約束/指令的遵從度	instruction_following

靜態評分標準指標（固定基準）——與上述指標搭配使用。

目標	指標
捕捉幻覺主張（RAG、事實性回答）	hallucination
相較於所提供上下文的事實性 / 一致性	grounding
安全政策合規性	safety

內建指標未涵蓋的特定領域檢查： 撰寫自訂指標。

• 預定義（Predefined）： types.RubricMetric.<NAME>——伺服器端 AutoRater，不需要裁判模型。
• 自訂 LLM-as-a-judge： 搭配 prompt_template 的 types.LLMMetric，或是用於結構化 Rubric 的 types.MetricPromptBuilder。
• 自訂程式碼： 帶有包含 def evaluate(instance: dict) 之 custom_function 字串的 types.CodeExecutionMetric（用於遠端沙盒執行）；或是 custom_function=<callable> 的 types.Metric（用於本地執行）。

務必持久化儲存評估結果，以供階段 4 和階段 5 讀取。請同時儲存 JSON（機器可讀、可比較 diff）與 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")

result_json = result.model_dump_json()
(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. 分析失敗案例 (Analyze Failures)

閱讀 summary_metrics 與 eval_case_results——絕不捏造分數。使用 scripts/inspect_results.py --failing-only 來篩選出失敗案例。

針對每個未達標的指標，請參閱 references/failure_patterns.md 以進行更深入的診斷。簡要對應表如下：

未達標指標	應調整的項目
multi_turn_task_success 過低	Agent 未能完成目標——修復編排流程（orchestration）、補足缺失的 Tool 呼叫、防止過早終止或選錯 Tool。
multi_turn_trajectory_quality 過低	Agent 完成目標的效率低落——精煉規劃 Prompt、移除冗餘的 Tool 呼叫。
multi_turn_tool_use_quality 過低	修復 Tool 描述、參數 Docstring 或 Tool 選擇相關的 Agent 指令。
final_response_quality 過低	檢視自動生成的 Rubric 判決；針對得分最差的判準精煉指令。
final_response_match 過低	Agent 的最終答案與黃金參考答案不符——調整回應格式或更新參考答案。
hallucination 過低	加強指令約束以確保嚴格基於事實（grounded）。

<!-- truncated for translation batch; full body continues in source -->