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 评估服务，以获得更好的质量和规模。

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 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")

# 错误——导致 "Session not found" 错误
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 端点——它们不继承清单中的 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}...",
)

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

启用了“思考”的模型可能会跳过工具调用。使用带有 mode="ANY" 的 tool_config 强制使用工具，或切换到非思考模型以获得可预测的工具调用。

---

常见评估失败原因

症状	原因	修复
智能体提及工具输出中不存在的数据	幻觉	收紧智能体指令；添加 hallucination 指标
“Session not found” 错误	应用名称不匹配	确保 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、日志记录和监控