google-agents-cli-eval

代理評估指南

需求： agents-cli（uv tool install google-agents-cli）— 如有需要，請先安裝 uv。

已建立專案？ 如果您使用了 /google-agents-cli-scaffold，您已經擁有 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/multimodal-eval.md	多模態輸入 — 評估資料集結構、內建指標限制、自訂評估器模式

---

品質飛輪

提升代理品質是迭代的過程。以下 5 個階段描述了這個循環。每個階段都有預設路徑（由您，也就是程式設計代理，直接執行工作）和可選的 CLI 指令（將工作委派給 Agent Platform Eval Service，以獲得更好的品質和規模）。

1. 準備資料

預設： 使用或編輯已建立的 tests/eval/datasets/basic-dataset.json 來定義單輪評估輸入。從 1-2 個案例開始。

可選： agents-cli eval dataset synthesize — 針對您的即時代理執行端到端的使用者模擬，以合成多輪評估資料集。適合在測試多輪對話但缺乏資料時使用。輸出包含軌跡，因此您可以跳過第 2 階段，直接進行 eval grade。

2. 執行推論

agents-cli eval generate — 在資料集上執行代理，並將軌跡寫入 artifacts/traces/。當您在第 1 階段手動編寫資料集時執行此指令（預設路徑）。如果您使用了 eval dataset synthesize，請跳過此階段 — 該指令已產生軌跡。

3. 評分軌跡（務必執行）

agents-cli eval grade — 對軌跡進行評分，並將 results_<ts>.{json,html} 寫入 artifacts/grade_results/。沒有可選的替代方案；這是核心步驟。無論第 1 和第 2 階段如何產生軌跡，都務必執行。

捷徑： agents-cli eval run 將第 2 和第 3 階段串聯成一個指令，並使用兩者之間的預設 artifacts/traces/ 目錄。在常見路徑中使用此指令；當需要自訂軌跡位置或想對現有軌跡檔案進行評分時，再回到兩步驟形式。

4. 分析失敗原因

預設： 開啟最新的 artifacts/grade_results/results_<ts>.html（或 .json），找出失敗的指標 — 請參閱下方「分數失敗時該修正什麼」的修正對照表。

可選： agents-cli eval analyze — 對評分結果執行基於 LLM 的失敗分群與根本原因分析。當您有 10 個以上的失敗案例，且希望獲得分類後的失敗模式，而非逐個案例閱讀時，建議使用此指令。

5. 優化與程式碼修正

預設： 根據失敗分析編輯代理 — 調整提示、工具描述、指令或評估資料集。請參閱下方「分數失敗時該修正什麼」的失敗與修正對應表。

可選： agents-cli eval optimize — 針對目標指標執行 ADK GEPA 提示優化。適用於僅因提示造成的失敗。優化後的提示會顯示在指令輸出中；請擷取並套用到代理上。如需每次迭代的完整軌跡，請在優化設定檔中設定 print_detailed_results: true。

耗時且昂貴。 GEPA 優化會進行大量 LLM 呼叫，可能需要很長時間。除非使用者明確要求提示優化，否則請勿執行。當您執行時，請先盡可能透過手動修正進行迭代，然後執行一次最終的 eval optimize — 切勿對此指令進行迴圈。

執行循環

迭代階段 2 → 3 → 4 → 5 → 2（如果使用 synthesize，則為 1 → 3 → 4 → 5 → 1）。每次修正後，執行 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
最終回應品質（無需真實參考答案）	final_response_quality
事實根據（捕捉幻覺陳述，例如 RAG 代理）	hallucination
安全政策遵循	safety
內建指標未涵蓋的領域特定檢查	撰寫自訂 LLMMetric（LLM 評審）或 CodeExecutionMetric（確定性 Python）。請參閱下方「評估設定結構」。

執行 agents-cli eval metric list 以查看所有可用的內建指標。如需完整的指標定義和評分標準詳細資訊，請參閱 Agent Platform 指標文件 和 references/metrics-guide.md。

---

分數失敗時該修正什麼

在 agents-cli eval grade 完成後，檢查最新的 artifacts/grade_results/results_<timestamp>.json（或開啟 .html 檔案）以查看每個案例的分數和評審理由 — 這是下方所有修正決策的依據。

失敗	應修改的項目
multi_turn_task_success 分數低	代理未完成使用者的目標 — 修正編排、缺少的工具呼叫、過早終止或錯誤的工具選擇
multi_turn_trajectory_quality 分數低	代理效率低下或採取錯誤步驟 — 改善規劃提示、調整指令順序，或移除多餘的工具呼叫
multi_turn_tool_use_quality 分數低	修正工具描述、參數文件字串，或代理的工具選擇指令
final_response_quality 分數低	閱讀自動產生的評分標準判決；改善代理指令以解決評分最低的標準（通常是清晰度、完整性或指令遵循）
hallucination 分數低	加強代理指令，使其緊扣工具輸出；確認工具確實傳回了代理所聲稱的資料
safety 分數低	在指令中加入安全護欄；檢視評分標準判決中的違規內容類別
代理呼叫錯誤的工具	修正工具描述、代理指令或 tool_config
代理呼叫多餘的工具	加入嚴格的停止指令，或改用 multi_turn_tool_use_quality

套用修正後，重新執行 agents-cli eval generate && agents-cli eval grade，並使用 agents-cli eval compare <prev_results>.json <new_results>.json 確認修正改善了目標指標，且未導致其他指標退步。

---

評估指令

所有 agents-cli eval 子指令都支援 --help 以取得權威的旗標清單和預設值 — 如有疑問，請執行 agents-cli eval <subcommand> --help（或 agents-cli eval dataset <subcommand> --help）。以下範例顯示最常見的呼叫方式；旗標可能隨版本變更。

eval generate

在評估資料集上執行代理，並將軌跡寫入磁碟。

# 基本 — 使用 tests/eval/datasets/，寫入 artifacts/traces/
agents-cli eval generate

# 進階 — 自訂資料集和輸出目錄
agents-cli eval generate --dataset tests/eval/datasets/custom.json -o ./custom_traces/

eval grade

根據內建或自訂指標對產生的軌跡進行評分。將帶有時間戳記的 results_<YYYYMMDD_HHMMSS>.json（供 eval compare 使用）和 .html（可在瀏覽器中開啟）寫入輸出目錄，並在控制台列印摘要表格。

# 基本 — 預設：軌跡來自 artifacts/traces/，結果輸出至 artifacts/grade_results/，
# 指標來自 tests/eval/eval_config.yaml 的 metrics_to_run
agents-cli eval grade

# 進階 1 — 對非預設位置的軌跡進行評分（與 `eval generate --output custom_traces/` 搭配使用）
agents-cli eval grade --traces custom_traces/

# 進階 2 — 選擇內建指標，自訂輸出目錄
agents-cli eval grade --metrics tool_use_quality,safety --output ./out/

# 進階 3 — 從設定檔（YAML 或 JSON）載入要執行的指標，並指定軌跡檔案
agents-cli eval grade --traces ./artifacts/traces/trace_1.json --config tests/eval/eval_config.yaml

請參閱下方「評估設定結構」以了解設定檔格式。

eval compare

比較兩個由 eval grade 產生的 results_*.json 檔案。在修正後執行，以確認目標指標改善且其他指標未退步。

agents-cli eval compare baseline.json candidate.json

eval metric list

列出可與 eval grade --metrics 搭配使用的內建指標名稱。

agents-cli eval metric list

eval analyze

對 eval grade 產生的 results_*.json 執行基於 LLM 的失敗分群與根本原因分析。當您有 10 個以上的失敗案例，且希望獲得分類後的失敗模式，而非逐個閱讀 HTML 時使用。支援的 --metric 值：multi_turn_task_success、multi_turn_tool_use_quality。

# 基本 — 使用預設設定分析結果檔案
agents-cli eval analyze --eval-result artifacts/grade_results/results_<ts>.json

# 進階 — 限制特定指標並設定損失叢集上限
agents-cli eval analyze \
  --eval-result artifacts/grade_results/results_<ts>.json \
  --metric multi_turn_tool_use_quality \
  --top-k 5 \
  --output artifacts/analysis_<ts>.json

eval dataset synthesize

根據代理的工具和指令，在伺服器端產生使用者情境，然後針對每個情境與 LLM 驅動的使用者模擬器進行互動。輸出是一個可直接用於評分的軌跡檔案，其中包含完整的 agent_data.turns — 可直接提供給 eval grade（跳過 eval generate）。

# 基本 — 產生 3 個預設情境（每個最多 5 輪）到 artifacts/traces/
#（這是 eval grade 預設讀取的位置，因此 synthesize → grade 無需旗標即可運作）
agents-cli eval dataset synthesize

# 進階 — 透過可選的指令和環境上下文引導情境產生
agents-cli eval dataset synthesize \
  -n 5 \
  --instruction "客戶詢問退款事宜" \
  --environment-context "電子商務客服" \
  --max-turns 8 \
  -o tests/eval/datasets/refund_scenarios.json

有關情境語義、完整的 eval dataset synthesize 旗標表格，以及哪些模擬器內部設定不可由使用者設定，請參閱 references/user-simulation.md。

eval optimize

針對目標指標執行 ADK GEPA 提示優化。適用於 eval grade 識別出僅因提示造成的失敗（措辭問題，而非工具或編排邏輯）。當同時傳入 --dataset 和 --target-metric 時，它們會覆蓋 --config 中的值。耗時且昂貴 — 請參閱品質飛輪第 5 階段以了解使用指引。

# 基本 — 針對資料集上的單一指標進行優化
agents-cli eval optimize --dataset tests/eval/datasets/basic-dataset.json --target-metric final_response_quality

# 進階 — 從設定檔驅動多指標/多資料集優化
agents-cli eval optimize --config tests/eval/optimization_config.json

eval submit / eval results（雲端端）

這是本地路徑的受管理非同步對應方案，適用於大型或 CI 驅動的執行：eval submit 將資料集和指標提交給 Agent Platform Eval Service，而 eval results 則輪詢並下載分數。傳入 --resource-name <agent> 也會在伺服器端執行推論（受管理的 generate + grade）；省略則僅對現有軌跡進行評分（受管理的 grade）。

# 在伺服器端對現有軌跡進行評分；傳回一個執行資源名稱以供輪詢
agents-cli eval submit --dataset tests/eval/datasets/basic-dataset.json --dest gs://my-bucket
# 加上 --resource-name projects/<p>/locations/<l>/reasoningEngines/<id> 也會執行推論

agents-cli eval results --run-id <run-resource-name>

---

評估資料集格式

EvaluationDataset 是一個包含 eval_cases 陣列的 JSON 檔案。案例根據使用方式有兩種形式：

• 推論輸入（提供給 eval generate 的內容）— 一個使用者提示或一個以使用者提示結尾的部分對話。代理會執行並產生軌跡。
• 評分輸入（提供給 eval grade 的內容）— 一個完整的軌跡，包含代理的回應和工具呼叫。通常由 eval generate 或 eval dataset synthesize 產生；您不需要手動編寫這些內容。

請參閱 references/dataset_schema.md 以了解完整的標準結構、所有欄位類型和常見錯誤。

推論輸入格式

支援兩種形式。

(a) 簡單的單輪提示 — 這是已建立的 tests/eval/datasets/basic-dataset.json 所使用的格式。代理會從頭開始執行。

{
  "eval_cases": [
    {
      "eval_case_id": "greeting",
      "prompt": {
        "role": "user",
        "parts": [{"text": "你好，有什麼我可以幫你的嗎？"}]
      }
    },
    {
      "eval_case_id": "weather_query",
      "prompt": {
        "role": "user",
        "parts": [{"text": "舊金山的天气如何？"}]
      }
    }
  ]
}

(b) 透過 agent_data 進行多輪延續 — 部分對話，最後一輪以使用者訊息結尾。用於延續現有對話；代理的下一個回應將被評估。

{
  "eval_cases": [
    {
      "eval_case_id": "booking_followup",
      "agent_data": {
        "agents": {
          "flight_booking_agent": {
            "agent_id": "flight_booking_agent",
            "instruction": "你是一個有用的航班預訂助理。"
          }
        },
        "turns": [
          {
            "turn_index": 0,
            "events": [
              {"author": "user", "content": {"parts": [{"text": "我想預訂一張去巴黎的機票。"}]}},
              {"author": "flight_booking_agent", "content": {"parts": [{"text": "我找到一張 800 美元的機票。你想預訂嗎？"}]}}
            ]
          },
          {
            "turn_index": 1,
            "events": [
              {"author": "user", "content": {"parts": [{"text": "是的，請幫我預訂。"}]}}
            ]
          }
        ]
      }
    }
  ]
}

評分輸入格式（軌跡）

完整的軌跡 — 包含代理回應、工具呼叫和工具回應。通常由 eval generate 或 eval dataset synthesize 產生；此處展示以便您在除錯時能辨識其結構。

{
  "eval_cases": [
    {
      "eval_case_id": "weather_query",
      "agent_data": {
        "agents": {
          "weather_agent": {
            "agent_id": "weather_agent",
            "instruction": "你是一個有用的天气助理。"
          }
        },
        "turns": [
          {
            "turn_index": 0,
            "events": [
              {"author": "user", "content": {"parts": [{"text": "舊金山的天气如何？"}]}},
              {"author": "weather_agent", "content": {"parts": [{"function_call": {"name": "get_weather", "args": {"city": "San Francisco"}}}]}},
              {"author": "weather_agent", "content": {"parts": [{"function_response": {"name": "get_weather", "response": {"temp_f": 62, "conditions": "foggy"}}}]}},
              {"author": "weather_agent", "content": {"parts": [{"text": "舊金山目前 62°F，有霧。"}]}}
            ]
          }
        ]
      }
    }
  ]
}

關鍵慣例： 作者為 "user"、來自 agents 對應表的代理 ID，或 "tool"；工具呼叫使用 function_call 部分，工具結果使用 function_response 部分。請參閱 references/dataset_schema.md 以了解多代理範例和完整的類型參考。

---

評估設定結構

agents-cli eval grade --config <path> 接受一個設定檔，可以是 YAML（.yaml / .yml）或 JSON（.json）。該檔案宣告兩個部分：

• 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     # 內建
  - example_llm_metric          # 從下方的 custom_metrics 池中選取
  - agent_turn_count            # 從下方的 custom_metrics 池中選取

custom_metrics:
  - name: example_llm_metric
    prompt_template: |
      請對代理的回應在幫助性和準確性方面評分 1-5 分。
      提示：{prompt}
      最終回應：{response}
      完整軌跡（用於工具呼叫和推理上下文）：{agent_data}
      回傳 JSON：{"score": <1|2|3|4|5>, "explanation": "<原因>"}

  - 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_metrics 中的每個項目根據欄位進行分派：存在 custom_function 則為 CodeExecutionMetric（確定性 Python）；否則為 LLMMetric（LLM 作為評審，使用 prompt_template）。執行 agents-cli eval metric list 以查看可用的內建指標。如需完整的自訂指標欄位參考（評審模型選項、抽樣次數），請參閱 references/metrics-guide.md。

代理軌跡欄位模型。 對於由 agents-cli eval generate（或 eval dataset synthesize）產生的資料集，每個評估案例會向指標公開三個標準欄位：

• {prompt} — 使用者訊息（或第一個使用者輪次）。
• {response} — 代理的最終文字回應，從最後一個包含文字的事件中提取。在 custom_function 回呼中，這是 instance['response']，其結構為 {"role": "model", "parts": [{"text": "..."}]}。
• {agent_data} — 完整的結構化 turns/events 軌跡，當評審需要推理工具呼叫或中間推理時很有用。

{reference} 和 {context} 僅在評估案例具有 reference / context 欄位時才會解析（例如，黃金答案資料集）；它們不會由 eval generate / eval dataset synthesize 填入。

基於程式碼的指標預設為本地程序內執行（無需 GCP 專案或區域，但 evaluate(instance) 函式會以 CLI 的權限執行）。在指標上設定 execution: "remote" 可改為在 Vertex AI 的 CodeExecutionMetric 沙箱中伺服器端執行 — 該路徑需要已設定的 GCP 專案和區域。

---

常見陷阱

使用基於評分標準的工具評估，而非硬編碼的順序

使用嚴格的順序比對來評估代理工具使用情況是脆弱的，因為代理可能以不同順序呼叫輔助工具（例如搜尋或地理編碼），或執行額外的主動步驟。

相反地，請使用 multi_turn_tool_use_quality / multi_turn_trajectory_quality。這些指標會自動產生基於內容和意圖的自適應評分標準，使用 LLM 評審從語義上評估技術正確性和技術順序邏輯，而非強制進行嚴格比對。

應用程式名稱必須與目錄名稱相符

App 物件的 name 參數必須與包含代理的目錄名稱相符：

# 正確 — 與 "app" 目錄相符
app = App(root_agent=root_agent, name="app")

# 錯誤 — 導致「找不到工作階段」錯誤
app = App(root_agent=root_agent, name="flight_booking_assistant")

跨工作階段的記憶體無法在評估中測試

每個評估案例都在自己全新的記憶體工作階段中執行（eval generate 會為每個案例建立一個新的 InMemorySessionService 和工作階段 ID）。案例內的多輪互動可透過 agent_data.turns 運作，但依賴於獨立先前工作階段的行為（例如跨工作階段的記憶庫回顧）無法透過評估來測試。請改用 pytest 整合測試來驗證跨工作階段的連續性。

Vertex 評估區域

eval grade、eval submit 和 eval dataset synthesize 預設使用 global 端點 — 它們不會繼承 manifest 中的 region（評估服務僅支援部分區域）。eval analyze 僅限 global；eval generate 在本地執行，並遵循專案區域。因此，您通常不需要為評估設定任何內容。

每次執行時可使用 --region <REGION> 覆蓋（例如資料駐留）；服務會拒絕不支援的區域：

400 FAILED_PRECONDITION: 不支援 Vertex Evaluation Service 的區域：<region>

沒有評估區域符合您的資料駐留規則？ 請退回使用本地自訂指標 — 一個帶有 custom_function（execution: local，預設值）的 custom_metrics 項目會在程序內進行評分，無需 GCP 區域。您會失去受管理的內建指標，但您的 custom_function 仍然可以在合規區域中自行呼叫 LLM 評審 — 因此 LLM 作為評審的評分方式在任何地方都可使用。

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="根據偏好設定：{user_preferences}...",
)

模型思考模式可能繞過工具

啟用「思考」功能的模型可能會跳過工具呼叫。請使用 tool_config 搭配 mode="ANY" 來強制使用工具，或改用非思考模型以獲得可預測的工具呼叫行為。

---

常見評估失敗原因

症狀	原因	修正
代理提及工具輸出中沒有的資料	幻覺	加強代理指令；加入 hallucination 指標
「找不到工作階段」錯誤	應用程式名稱不符	確保 App name 與目錄名稱相符
分數在不同執行之間波動	非確定性模型	設定 temperature=0 或使用基於評分標準的評估並搭配多個樣本
tool_use_quality 分數低	選擇了錯誤的工具或傳入了無效的引數	改善工具描述、指令或參數文件
LLM 評審忽略評估中的圖片/音訊	get_text_from_content() 跳過非文字部分	使用具有視覺能力的自訂指標評審（請參閱 references/multimodal-eval.md）

---

除錯範例

使用者說：「tool_use_quality 分數很低，出了什麼問題？」

1. 開啟最新的 artifacts/grade_results/results_<timestamp>.html（或讀取 .json），找出自適應指標為失敗案例產生的評分標準判決。
2. 確認代理是選擇了錯誤的工具，還是使用了錯誤的引數呼叫 — 軌跡位於 artifacts/traces/。
3. 改善工具的參數、Python 文件字串描述，或代理的工具選擇指令，以更好地引導模型。
4. 重新執行 agents-cli eval generate && agents-cli eval grade。
5. 使用 agents-cli eval compare <prev>.json <new>.json 確認分數有所改善。

---

證明您的工作成果

不要斷言評估通過 — 請展示證據。具體的輸出可以防止虛假的信心，並及早發現問題。

• 執行評估後： 貼上分數表格輸出，讓使用者清楚看到哪些通過、哪些失敗。
• 修正失敗後： 顯示您修正的特定案例在修正前後的分數，並確認沒有其他案例退步。
• 在宣布「評估通過」之前： 確認所有案例都通過，而不僅僅是您正在處理的那個。最後再執行一次 agents-cli eval generate 和 agents-cli eval grade。
• 在進入部署階段之前： 顯示最終的 agents-cli eval grade 輸出，其中所有案例都高於門檻。這是關卡 — 沒有例外。

---

相關技能

• /google-agents-cli-workflow — 開發工作流程與規格驅動的建置-評估-部署生命週期
• /google-agents-cli-adk-code — 用於編寫代理程式碼的 ADK Python API 快速參考
• /google-agents-cli-scaffold — 使用 agents-cli scaffold create / scaffold enhance 進行專案建立與增強
• /google-agents-cli-deploy — 部署目標、CI/CD 管道與生產工作流程
• /google-agents-cli-observability — 用於除錯代理行為的 Cloud Trace、日誌記錄與監控