Google ADK Python 2.14 升級與多次評估：用通過率抓出偶發失敗

把工具呼叫和輸出品質分開訂門檻#

如果「一定得先查訂單」是上線條件，可以給工具軌跡單獨的通過門檻。以下設定把每個案例跑五次，工具軌跡每次都要符合預期，文字相符分數則採各次分數中的最低值。先放進測試環境的 test_config.json，讓評估資料記錄預期的工具呼叫與回應。文字分數門檻 0.8 是示意值，應用自己的既有案例校準。

1
{
2
  "criteria": {
3
    "tool_trajectory_avg_score": 1.0,
4
    "response_match_score": 0.8
5
  },
6
  "multi_run_config": {
7
    "num_runs": 5,
8
    "max_crashed_runs": 0,
9
    "cross_run_scoring_by_metric": {
10
      "tool_trajectory_avg_score": {"method": "pass_rate", "threshold": 1.0},
11
      "response_match_score": "min_over_runs"
12
    }
13
  }
14
}

每次工具軌跡先用 criteria 中的 1.0 決定有沒有通過，接著才用 pass_rate 算通過比例。四次通過、一次完成但未通過，結果是 4/5，會被上面的 1.0 門檻擋下。min_over_runs 則把最差的文字分數和 0.8 比較。若改用預設的 mean_over_invocations，多步案例裡各次 invocation 會進入同一個平均，得分較好的步驟可以拉高結果。 v2.14.0 EvalConfig 原始碼

完全沒有產生評估指標的崩潰會另外計數，排除在 pass rate 分母外。保留 max_crashed_runs: 0 時，任何一次這類崩潰都會使案例失敗。比較升級前後時，應同時記下「嘗試次數、有效評分次數、通過次數、崩潰次數」，避免只看有效樣本的高通過率。五次適合抓重現頻率高的問題，若要估長期失敗率，仍需更大的樣本。

如果驗收要問「同一次執行是否通過所有指標」，可在 multi_run_config 另加 cross_run_criteria。例如工具與文字各自通過 4/5，但它們分別在不同次失敗，整個案例同時通過兩個指標的次數只有 3/5。這項門檻適合用來檢查單次交付是否完整，原有的個別指標門檻仍會一起判定。 v2.14.0 跨次評估設定

升級時先跑少量案例#

在隔離的 Python 環境安裝 google-adk[eval]==2.14.0。從 agent 資料夾的上一層執行下面的命令，把兩個路徑換成你的 agent 套件和評估集。先用 --parallelism 1 跑單一小型評估集，避免把模型配額、外部工具限流和 agent 的失敗混在一起。

1
adk eval ./order_agent ./order-agent.evalset.json \
2
  --config_file_path ./test_config.json --parallelism 1 --print_detailed_results

CLI 的 --num_runs 會覆蓋設定中的次數。比對報表前先核對啟動命令。如果是透過 AgentEvaluator 或 adk web 啟動，這個版本的設定檔多次聚合欄位適用於 adk eval，AgentEvaluator 另有自己的 num_runs 參數。本文的 JSON 可由該版本 EvalConfig 驗證，實際模型、工具呼叫及費用請在測試環境確認。

升級原本依賴實驗功能的 agent 時，把 Python 匯入檢查和行為檢查分開。2.14.0 的發行說明列出執行環境、A2A、評估與核心執行模組有項目轉為 stable，也列出 FunctionTool 的 Enum 行為變更。對 plain Enum，工具函式可能收到 Enum 成員，原本用 arg == "value" 或用字串鍵查表的分支要重測。檢查工具本體的分支以及對外回傳的值，再看評估是否抓得到差異。 ADK Python 2.14.0 相容性變更

評估資料中若有需要人工核准的工具，可先用隔離的假工具收集軌跡。正式環境的核准設定可以另外驗收，參考 Claude Code 的自動化權限清單 中以假資料檢查實際工具入口的方法。

參考資料：

Google ADK Python v2.14.0 release

v2.14.0 EvalConfig 與 MultiRunConfig

PyPI：google-adk 2.14.0