ADK评估指南

要求：
agents-cli
（
uv tool install google-agents-cli
）——如果需要，请先安装uv。

是否使用脚手架项目？ 如果你使用了
/google-agents-cli-scaffold
，那么你已经拥有
agents-cli eval run
、
tests/eval/evalsets/
和
tests/eval/eval_config.json
。从
agents-cli eval run
开始，逐步迭代即可。

参考文件

文件	内容
`references/criteria-guide.md`	完整指标参考——包含全部8项评估标准、匹配类型、自定义指标、评判模型配置
`references/user-simulation.md`	动态对话测试——ConversationScenario、用户模拟器配置、兼容指标
`references/builtin-tools-eval.md`	google_search和模型内置工具——轨迹行为、指标兼容性
`references/multimodal-eval.md`	多模态输入——评估集schema、内置指标局限性、自定义评估器模式

评估-修复循环

评估是一个迭代过程。当分数低于阈值时，要诊断原因、修复问题、重新运行——不要只报告失败结果。

迭代步骤

从小规模开始：先从1-2个评估用例入手，不要直接使用完整套件
运行评估：
```
agents-cli eval run
```
查看分数——确定哪些部分失败以及失败原因
修复代码——调整提示词、工具逻辑、指令或评估集
重新运行评估——验证修复是否有效
重复步骤3-5，直到用例通过
之后再添加更多评估用例，扩大覆盖范围

预计需要5-10+次迭代。这是正常情况——每次迭代都会让Agent变得更完善。

任务跟踪：当进行5次以上评估-修复迭代时，使用任务列表跟踪已修复的用例、仍失败的用例以及已尝试的方案。这可以避免重复尝试相同的修复，或在迭代过程中遗漏回归问题。

浪费时间的捷径

识别这些不合理的做法并避免——它们最终花费的时间比节省的更多：

捷径	失败原因
"我会调低评估阈值让它通过"	降低阈值会掩盖真实的失败。如果Agent达不到标准，就修复Agent——不要降低标准。
"这个评估用例不稳定，我跳过它"	不稳定的评估会暴露Agent的非确定性问题。通过设置 `temperature=0` 、基于评分标准的指标或更明确的指令来修复——不要删除有效信号。
"我只需要修复评估集，不需要修改Agent"	如果你总是调整预期输出，说明Agent存在行为问题。先修复指令或工具逻辑。

分数失败时的修复方向

失败类型	调整内容
`tool_trajectory_avg_score` 分数低	修复Agent指令（工具调用顺序）、更新评估集 `tool_uses` ，或切换为 `IN_ORDER` / `ANY_ORDER` 匹配类型
`response_match_score` 分数低	调整Agent指令措辞，或放宽预期响应要求
`final_response_match_v2` 分数低	优化Agent指令，或调整预期响应——这是语义层面的匹配，而非词汇层面
`rubric_based` 分数低	优化Agent指令，解决未通过的特定评分标准问题
`hallucinations_v1` 分数低	收紧Agent指令，确保基于工具输出生成内容
Agent调用错误工具	修复工具描述、Agent指令或tool_config
Agent调用额外工具	使用 `IN_ORDER` / `ANY_ORDER` 匹配类型、添加严格停止指令，或切换为 `rubric_based_tool_use_quality_v1`

选择合适的评估标准

目标	推荐指标
回归测试/CI/CD（快速、确定性）	`tool_trajectory_avg_score` + `response_match_score`
语义响应正确性（允许灵活表述）	`final_response_match_v2`
无参考答案时的响应质量	`rubric_based_final_response_quality_v1`
验证工具调用推理逻辑	`rubric_based_tool_use_quality_v1`
检测幻觉内容	`hallucinations_v1`
安全合规性	`safety_v1`
动态多轮对话	用户模拟 + `hallucinations_v1` / `safety_v1` （详见 `references/user-simulation.md` ）
多模态输入（图片、音频、文件）	`tool_trajectory_avg_score` + 自定义响应质量指标（详见 `references/multimodal-eval.md` ）

如需包含配置示例、匹配类型和自定义指标的完整指标参考，请查看

references/criteria-guide.md

。

运行评估

bash

# 脚手架项目——使用agents-cli:
agents-cli eval run --evalset tests/eval/evalsets/my_evalset.json

# 指定配置文件:
agents-cli eval run --evalset tests/eval/evalsets/my_evalset.json --config tests/eval/eval_config.json

# 运行tests/eval/evalsets/下的所有评估集:
agents-cli eval run --all

agents-cli eval run
选项:

--evalset PATH

--config PATH

--all

比较两个结果文件:

bash

agents-cli eval compare baseline.json candidate.json

配置Schema (

eval_config.json

)

支持camelCase和snake_case字段名（Pydantic别名）。以下示例使用snake_case，与官方ADK文档保持一致。

完整示例

json

{
  "criteria": {
    "tool_trajectory_avg_score": {
      "threshold": 1.0,
      "match_type": "IN_ORDER"
    },
    "final_response_match_v2": {
      "threshold": 0.8,
      "judge_model_options": {
        "judge_model": "gemini-flash-latest",
        "num_samples": 5
      }
    },
    "rubric_based_final_response_quality_v1": {
      "threshold": 0.8,
      "rubrics": [
        {
          "rubric_id": "professionalism",
          "rubric_content": { "text_property": "The response must be professional and helpful." }
        },
        {
          "rubric_id": "safety",
          "rubric_content": { "text_property": "The agent must NEVER book without asking for confirmation." }
        }
      ]
    }
  }
}

也支持简单的阈值简写：

"response_match_score": 0.8

如需自定义指标、

judge_model_options

详情和

user_simulator_config

，请查看

references/criteria-guide.md

。

评估集Schema (

evalset.json

)

json

{
  "eval_set_id": "my_eval_set",
  "name": "My Eval Set",
  "description": "Tests core capabilities",
  "eval_cases": [
    {
      "eval_id": "search_test",
      "conversation": [
        {
          "invocation_id": "inv_1",
          "user_content": { "parts": [{ "text": "Find a flight to NYC" }] },
          "final_response": {
            "role": "model",
            "parts": [{ "text": "I found a flight for $500. Want to book?" }]
          },
          "intermediate_data": {
            "tool_uses": [
              { "name": "search_flights", "args": { "destination": "NYC" } }
            ],
            "intermediate_responses": [
              ["sub_agent_name", [{ "text": "Found 3 flights to NYC." }]]
            ]
          }
        }
      ],
      "session_input": { "app_name": "my_app", "user_id": "user_1", "state": {} }
    }
  ]
}

关键字段:

```
intermediate_data.tool_uses
```
— 预期的工具调用轨迹（按时间顺序）
```
intermediate_data.intermediate_responses
```
— 预期的子Agent响应（适用于多Agent系统）
```
session_input.state
```
— 初始会话状态（覆盖Python层面的初始化）

conversation_scenario

— 替代

conversation

的用户模拟模式（详见

references/user-simulation.md

）

常见陷阱

主动性轨迹偏差

LLM经常执行未被要求的额外操作（例如，在

save_preferences

之后调用

google_search

）。这会导致使用

EXACT

匹配时

tool_trajectory_avg_score

失败。解决方案：

使用
IN_ORDER
或
ANY_ORDER
匹配类型——允许在预期工具调用之间存在额外的工具调用
在预期轨迹中包含Agent可能调用的所有工具
使用
```
rubric_based_tool_use_quality_v1
```
替代轨迹匹配
添加严格的停止指令："调用save_preferences后停止。请勿进行搜索。"

多轮对话需要为所有轮次指定tool_uses

tool_trajectory_avg_score

会评估每一次调用。如果不为中间轮次指定预期工具调用，即使Agent调用了正确的工具，评估也会失败。

json

{
  "conversation": [
    {
      "invocation_id": "inv_1",
      "user_content": { "parts": [{"text": "Find me a flight from NYC to London"}] },
      "intermediate_data": {
        "tool_uses": [
          { "name": "search_flights", "args": {"origin": "NYC", "destination": "LON"} }
        ]
      }
    },
    {
      "invocation_id": "inv_2",
      "user_content": { "parts": [{"text": "Book the first option"}] },
      "final_response": { "role": "model", "parts": [{"text": "Booking confirmed!"}] },
      "intermediate_data": {
        "tool_uses": [
          { "name": "book_flight", "args": {"flight_id": "1"} }
        ]
      }
    }
  ]
}

App名称必须与目录名称匹配

App

对象的

name

参数必须与包含Agent的目录名称一致：

python

# 正确 - 与"app"目录匹配
app = App(root_agent=root_agent, name="app")

# 错误 - 会导致"Session not found"错误
app = App(root_agent=root_agent, name="flight_booking_assistant")

before_agent_callback

模式（状态初始化）

始终使用回调函数初始化指令模板中用到的会话状态变量。这可以防止第一轮出现

KeyError

崩溃：

python

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="Based on preferences: {user_preferences}...",
)

评估状态覆盖（类型不匹配风险）

在评估集中使用

session_input.state

时要谨慎。它会覆盖Python层面的初始化：

错误示例——将feedback_history初始化为字符串，会破坏

.append()

方法：

json

"state": { "feedback_history": "" }

正确示例——与Python类型（列表）匹配：

json

"state": { "feedback_history": [] }

模型思考模式可能绕过工具调用

启用“思考”模式的模型可能会跳过工具调用。使用

tool_config

并设置

mode="ANY"

强制工具调用，或切换为非思考模式的模型以确保可预测的工具调用行为。

常见评估失败原因

症状	原因	修复方案
中间轮次缺少 `tool_uses`	轨迹要求每次调用都匹配	为所有轮次添加预期工具调用
Agent提及工具输出中不存在的数据	幻觉问题	收紧Agent指令；添加 `hallucinations_v1` 指标
"Session not found"错误	App名称不匹配	确保App的 `name` 与目录名称一致
分数在多次运行之间波动	模型非确定性	设置 `temperature=0` 或使用基于评分标准的评估
`tool_trajectory_avg_score` 始终为0	Agent使用了 `google_search` （模型内置工具）	删除轨迹指标；详见 `references/builtin-tools-eval.md`
轨迹失败但工具调用正确	调用了额外工具	切换为 `IN_ORDER` / `ANY_ORDER` 匹配类型
LLM评判忽略评估中的图片/音频	`get_text_from_content()` 跳过了非文本部分	使用支持视觉的评判模型自定义指标（详见 `references/multimodal-eval.md` ）

深入学习：ADK文档

如需官方评估文档，请访问以下页面：

评估概述:
```
https://adk.dev/evaluate/index.md
```

评估标准参考:

https://adk.dev/evaluate/criteria/index.md

用户模拟:

https://adk.dev/evaluate/user-sim/index.md

调试示例

用户反馈："tool_trajectory_avg_score为0，出了什么问题？"

检查Agent是否使用了
```
google_search
```
——如果是，查看
```
references/builtin-tools-eval.md
```
检查是否使用了
```
EXACT
```
匹配且Agent调用了额外工具——尝试
```
IN_ORDER
```
匹配类型
比较评估集中的预期
```
tool_uses
```
与Agent的实际行为
修复不匹配问题（更新评估集或Agent指令）

证明你的工作成果

不要断言评估通过——要展示证据。具体的输出可以防止错误的自信，并尽早发现问题。

运行评估后: 粘贴分数表输出，让用户清楚看到哪些部分通过、哪些失败。
修复失败后: 展示你修复的特定用例的前后分数，并确认其他用例没有出现回归问题。
声明“评估通过”前: 确认所有用例都通过，而不仅仅是你正在处理的那个。最后再运行一次
```
agents-cli eval run
```
（或
```
agents-cli eval run --all
```
）。
部署前: 展示最终的
```
agents-cli eval run
```
输出，确认所有用例都高于阈值。这是必经的检查环节——没有例外。

google-agents-cli-eval

NPX安装

标签

SKILL.md 内容（中文）

ADK评估指南

参考文件

评估-修复循环

迭代步骤

浪费时间的捷径

分数失败时的修复方向

选择合适的评估标准

运行评估

配置Schema (
`eval_config.json`
)

完整示例

评估集Schema (
`evalset.json`
)

常见陷阱

主动性轨迹偏差

多轮对话需要为所有轮次指定tool_uses

App名称必须与目录名称匹配

`before_agent_callback`
模式（状态初始化）

评估状态覆盖（类型不匹配风险）

模型思考模式可能绕过工具调用

常见评估失败原因

深入学习：ADK文档

调试示例

证明你的工作成果

相关技能

google-agents-cli-eval

NPX安装

标签

SKILL.md 内容（中文）

ADK评估指南

参考文件

评估-修复循环

迭代步骤

浪费时间的捷径

分数失败时的修复方向

选择合适的评估标准

运行评估

配置Schema (eval_config.json)

完整示例

评估集Schema (evalset.json)

常见陷阱

主动性轨迹偏差

多轮对话需要为所有轮次指定tool_uses

App名称必须与目录名称匹配

before_agent_callback模式（状态初始化）

评估状态覆盖（类型不匹配风险）

模型思考模式可能绕过工具调用

常见评估失败原因

深入学习：ADK文档

调试示例

证明你的工作成果

相关技能

配置Schema (
`eval_config.json`
)

评估集Schema (
`evalset.json`
)

`before_agent_callback`
模式（状态初始化）