google-agents-cli-eval

Agent 评测指南

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

使用脚手架创建的项目？ 如果你使用了 /google-agents-cli-scaffold，数据集和自定义指标已在 tests/eval/（Python 项目）或 eval/（Go 项目）中创建。为简单起见，本技能及其参考资料使用 Python 目录布局；如果你为 Go Agent 创建了脚手架，请相应调整。 你已经有 agents-cli eval run（串联 generate + grade）、tests/eval/datasets/ 和 tests/eval/eval_config.yaml。先执行 eval run，然后再逐步迭代。

参考文件

文件	内容
references/dataset_schema.md	标准 EvaluationDataset 架构——所有字段类型、单轮／多轮／多 Agent 的 JSON 示例、常见错误
references/metrics-guide.md	完整的指标参考——所有内置指标、匹配类型、自定义指标、评判模型配置
references/user-simulation.md	动态对话测试——eval dataset synthesize 标志、场景说明、兼容的指标
references/builtin-tools-eval.md	google_search 和模型内部工具——轨迹行为、指标兼容性
references/advanced-commands.md	可选命令：eval analyze、eval optimize、eval submit / eval results
references/multimodal-eval.md	多模态输入——评测数据集架构、内置指标的限制、自定义评测器模式
references/live-eval.md	实时和语音 Agent——--mode adk_live、评分内容、仅限用户轮次的编写、Live 模型和区域的常见问题

---

质量飞轮

提升 Agent 质量是一个迭代过程。以下 4 个阶段描述了这一循环。每个阶段都有一条默认路径（由你，即编码 Agent，直接完成工作）和一条可选 CLI 命令（将工作委托给 Gemini 平台中的 Eval Service，以获得更高质量和更大规模）。

1. 准备数据

默认： 使用或编辑脚手架创建的 tests/eval/datasets/basic-dataset.json，定义单轮评测输入。从 1–2 个用例开始。

可选（ADK 项目）： 使用 agents-cli eval dataset synthesize：在缺少数据时，通过模拟用户生成多轮数据集；其输出已包含轨迹，因此第 2 阶段可简化为仅运行 agents-cli eval grade。参见 评测命令 和 references/user-simulation.md。

2. 运行评测（始终运行）

默认： agents-cli eval run 会在数据集上运行 Agent 并为轨迹评分，将 results_<ts>.{json,html} 写入 artifacts/grade_results/。

解耦形式： 先运行 eval generate，再运行 eval grade，适用于自定义轨迹位置、无需重新运行 Agent 即可重新评分，或使用 synthesize 生成的轨迹（单独运行 eval grade）。

3. 分析失败案例

默认： 打开最新的 artifacts/grade_results/results_<ts>.html（或 .json），找出未通过的指标——修复方法请参见下文的 分数未通过时的修复方法。

可选： 使用 agents-cli eval analyze 进行基于 LLM 的失败聚类；当你有 10 个以上失败用例并希望对失败模式进行分类时，建议使用。参见 references/advanced-commands.md。

4. 优化与修复代码

默认做法： 编辑 Agent——根据失败分析调整提示词、工具描述、指令或评测数据集。失败原因与修复方法的对应关系，请参见下文的 评分失败时应修复什么。

可选（ADK 项目）： agents-cli eval optimize 会针对目标指标运行 ADK GEPA 提示词优化（参见 references/advanced-commands.md）。适用于仅由提示词导致的失败。优化后的提示词会显示在命令输出中；请将其复制并应用到 Agent。若要查看每次迭代的完整记录，请在优化配置文件中设置 print_detailed_results: true。

运行时间长且成本高。 GEPA 优化会调用大模型很多次，可能耗时很久。除非用户明确要求优化提示词，否则不要运行。运行时，先尽可能通过手动修复进行迭代，然后只运行一次最终的 eval optimize——切勿反复运行此命令。

运行迭代循环

按阶段 2 → 3 → 4 → 2 进行迭代（使用 synthesize，每轮都重新运行阶段 1，然后运行 eval grade）。每次修复后，运行 agents-cli eval compare <prev_results>.json <new_results>.json，确认目标指标有所改善，且其他指标没有退步。每个用例通常需要迭代 5–10 次甚至更多才能通过，这是正常的。只有用例通过后，才应通过更多评测用例扩大覆盖范围。

迭代 5 次或更多时，请维护任务列表，记录哪些用例已修复、哪些仍未通过，以及尝试过哪些修复方法。这样可以避免重复尝试相同的修复方法。

预留一部分用例。 将一部分用例留在迭代循环之外，等你认为已经完成时再对它们评分——否则，你无法判断某项修复是普遍有效，还是仅适用于你反复迭代的那些用例。

浪费时间的捷径

识别并反驳以下这些说辞——它们总是得不偿失：

捷径	失败原因
“我降低标准让它通过就行了”	降低标准会掩盖实际问题。如果 Agent 达不到标准，就修复 Agent，而不是降低标准。
“这个评测用例不稳定，我跳过它好了”	不稳定的评测反映了 Agent 的行为具有非确定性。请通过设置 temperature=0、使用基于评分标准的指标或编写更具体的指令来修复——不要删除这项信号。
“我只需要修复评测数据集，不用改 Agent”	如果你总是在调整预期输出，说明 Agent 存在行为问题。请先修复指令或工具逻辑。
“我会一直迭代，直到手头的每个用例都通过”	这样就没有用例可以检测是否对自己的用例过拟合了。参见上文的 预留一部分用例。

选择合适的指标

根据你想衡量的内容选择内置指标。只有 multi_turn_task_success、multi_turn_trajectory_quality 和 multi_turn_tool_use_quality 接受多轮轨迹；其他所有内置指标遇到多轮轨迹时都会返回 400。没有合适的内置指标时，请编写自定义指标（见下文的 评估配置架构）。

目标	推荐的内置指标
Agent 是否达成了用户的目标？（适用于多轮 Agent 的通用指标）	multi_turn_task_success
Agent 的推理路径是否合乎逻辑且高效？	multi_turn_trajectory_quality
跨轮次的工具 / 函数调用质量	multi_turn_tool_use_quality
最终响应质量（无需真实答案作为参考）	final_response_quality
事实依据（检测编造的声明，例如 RAG Agent）	hallucination；如果案例包含 context 字段，则使用 grounding
是否遵守安全策略	safety
是否与标准答案匹配	final_response_match（案例需要包含 reference）
每个案例的通过 / 失败标准不同	将标准作为 rubric_groups 添加到案例中，并使用托管评分标准指标进行评估。参见 references/dataset_schema.md（每个案例的评分标准）。
没有内置指标涵盖的领域专属检查	编写自定义 LLMMetric（LLM 评审）或 CodeExecutionMetric（确定性 Python）。参见下文的 评估配置架构。

运行 agents-cli eval metric list 查看所有可用的内置指标。有关完整的指标定义和评分标准详情，请参见 Gemini 平台指标文档 和 references/metrics-guide.md。

---

分数不理想时的修正方法

agents-cli eval run 完成后，请检查最新的 artifacts/grade_results/results_<timestamp>.json（或打开 .html 文件），查看每个案例的分数和评审理由；以下每项修正决策都应以此为依据。

失败情况	修改方法
multi_turn_task_success 分数低	Agent 未能完成用户的目标——修正编排、缺失的工具调用、过早终止或错误的工具选择
multi_turn_trajectory_quality 分数低	Agent 低效地达成目标或采取了错误步骤——改进规划提示词、调整指令顺序，或移除多余的工具调用
multi_turn_tool_use_quality 分数低	修正工具描述、参数文档字符串或 Agent 关于工具选择的指令
final_response_quality 分数低	阅读自动生成的评分标准判定；改进 Agent 指令以解决得分最低的标准（通常是清晰度、完整性或指令遵循情况）
hallucination 分数低	收紧 Agent 指令，要求其以工具输出为依据；确认工具确实返回了 Agent 声称的数据
safety 分数低	在指令中添加安全防护措施；查看评分标准判定中违反的内容类别
Agent 调用了错误的工具	修正工具描述、Agent 指令或模型的工具选择配置（ADK： tool_config）
Agent 调用了多余的工具	添加严格的停止指令，或改用 multi_turn_tool_use_quality

应用修正后，重新运行 agents-cli eval run，并使用 agents-cli eval compare <prev_results>.json <new_results>.json 确认目标指标得到改善，且其他指标没有退步。

---

评估命令

agents-cli eval <subcommand> --help 是权威的标志列表；以下示例展示了常见的调用方式。

eval run（默认）

在数据集上运行 Agent，并通过一条命令对轨迹进行评分。

# Basic: dataset from tests/eval/datasets/, results to artifacts/grade_results/,
# metrics from tests/eval/eval_config.yaml
agents-cli eval run

# Advanced: pick the dataset, metrics, and output dir
agents-cli eval run --dataset tests/eval/datasets/custom.json --metrics final_response_quality,safety --output ./out/

eval generate

在评测数据集上运行 Agent，并将轨迹写入磁盘。

默认情况下，会在本地运行 Agent，并为每个评测用例记录一条轨迹。也可以将 Agent 的 HTTP 端点和应用名称传给 --url 和 --app-name，从正在运行的 Agent 生成轨迹。

ADK 项目。 内置生成器会通过 HTTP 提供 Agent，并通过 ADK 的 /apps/... 和 /run_sse 路由驱动它——这与 --url / --app-name 所需的格式相同。启动方式取决于项目所用的语言：Python 会使用项目中的 fast_api_app.py（如果存在），否则运行 adk api_server；Go 会运行 go run ...。其他框架的扩展会用自己的生成器替换 eval generate，该生成器可能不提供 HTTP 服务；此时不支持 --url 和 --app-name。

# Basic — uses tests/eval/datasets/, writes to artifacts/traces/
agents-cli eval generate

# Advanced — custom dataset and output dir
agents-cli eval generate --dataset tests/eval/datasets/custom.json -o ./custom_traces/

# Against a deployed agent (or one you started manually)
agents-cli eval generate --url https://my-agent.run.app --app-name app

# Live agent — stream each case over ADK's /run_live WebSocket
agents-cli eval generate --mode adk_live

评测实时 Agent

实时 Agent 通过 WebSocket 运行，而不是 /run_sse：在 generate 或 run 中添加 --mode adk_live。数据集、轨迹和评分方式均不变；音频回复会被转录，因此评分依据是转录文本。有两项条件必须事先满足，否则套接字会先连接，然后在会话中途失败：Agent 使用的是 Live 模型（脚手架的默认模型不是 Live 模型）；在 Gemini 平台上，区域必须固定在模型上，而不能留给 GOOGLE_CLOUD_LOCATION。这两项条件以及数据集编写规则见：references/live-eval.md。

eval grade

根据内置或自定义指标对轨迹（来自 eval generate、eval dataset synthesize 或手动编写）评分。会在输出目录中写入带时间戳的 results_<YYYYMMDD_HHMMSS>.json（供 eval compare 使用）和 .html（可在浏览器中打开），并在控制台打印汇总表。

# Basic — defaults: traces from artifacts/traces/, results to artifacts/grade_results/,
# metrics from tests/eval/eval_config.yaml's metrics_to_run
agents-cli eval grade

# Advanced 1 — grade traces from a non-default location (the canonical
# pairing for `eval generate --output custom_traces/`)
agents-cli eval grade --traces custom_traces/

# Advanced 2: load metrics to run from a config file (YAML or JSON) on a specified trace file.
agents-cli eval grade --traces ./artifacts/traces/trace_1.json --config tests/eval/eval_config.yaml

# Advanced 3: dispatch rate, 15 metric computations per second by default. Lower it when the
# judge model or the eval service rate-limits you, raise it when they have headroom.
agents-cli eval grade --qps 5

配置文件格式请参阅下方的 评测配置架构。

eval compare

对比某次评测运行中的两个 results_*.json 文件。修复问题后运行此命令，确认目标指标有所提升，且其他指标没有退步。

agents-cli eval compare baseline.json candidate.json

eval dataset synthesize

ADK 项目。 此命令通过 ADK 加载并运行 Agent，因此不适用于其他框架。

根据 Agent 的工具和指令生成用户场景，使用由大模型驱动的用户模拟器逐一运行这些场景，并将可直接用于评分的轨迹写入 artifacts/traces/（可直接传给 eval grade，无需运行 eval generate）。调用方式、标志和兼容的指标见：references/user-simulation.md。

高级命令

eval analyze（聚类分析失败模式）、eval optimize（GEPA 提示词调优）以及 eval submit / eval results（用于 CI 或大型数据集的托管式云端运行）的文档见 references/advanced-commands.md。

---

评测数据集格式

EvaluationDataset 是包含 eval_cases 数组的 JSON 文件。用例根据用途分为两种形式：

• 推理输入（传给 eval generate 的内容）——单条用户提示词，或多轮的用户轮次（用于 Live），或以用户轮次结尾的续接内容（用于 SSE）。Agent 会运行并生成轨迹。对于 Live 推理，不要预先编写 Agent 回复。
• 评分输入（传给 eval grade 的内容）——包含 Agent 回复和工具调用的完整轨迹。通常由 eval generate 或 eval dataset synthesize 生成；不需要手动编写。

完整的规范架构、所有字段类型和常见错误，请参阅 references/dataset_schema.md。

推理输入格式

支持两种形式。

(a) 简单的单轮提示词——脚手架生成的 tests/eval/datasets/basic-dataset.json 使用此格式。Agent 从头开始运行。

{
  "eval_cases": [
    {
      "eval_case_id": "greeting",
      "prompt": {
        "role": "user",
        "parts": [{"text": "Hello, what can you help me with?"}]
      }
    }
  ]
}

(b) 通过 agent_data 实现多轮对话——格式取决于传输方式：

• Live（--mode adk_live）： 仅编写用户轮次；Agent 会在同一个实时会话中生成所有回复（编写的 Agent 轮次会被忽略，并发出警告）。
• SSE： 续接形式——之前的轮次会作为历史记录传入，只有最后一条用户轮次会得到回复。

JSON 格式请参阅 references/dataset_schema.md（多轮 / 多 Agent 数据集）。

评分输入格式（轨迹）

完整轨迹——包含 Agent 响应以及 function_call / function_response 部分——通常由 eval generate / eval dataset synthesize 生成（无需手动编写）。作者可以是 "user"、agents 映射中的 Agent ID，或 "tool"。有关轨迹结构、多 Agent 示例和完整类型参考，请参阅 references/dataset_schema.md。

---

评估配置架构

agents-cli eval run --config <path>（以及 eval grade --config <path>）接受一个 YAML（.yaml / .yml）或 JSON（.json）格式的配置文件。文件包含两个部分：

• metrics_to_run：本次运行要执行的指标名称选择列表。如果某个名称与 custom_metrics 条目匹配，则解析为该条目；否则解析为同名内置指标。
• custom_metrics — 此项目可用的自定义指标定义池。在这里定义指标不会运行它；还必须将其加入 metrics_to_run（或在命令行中通过 --metrics name1,name2 传入，这相当于为此次调用覆盖 metrics_to_run）。

最简示例（优先使用 YAML——易于阅读，无需对提示词和 Python 内容进行 JSON 转义）：

metrics_to_run:
  - multi_turn_task_success     # built-in
  - example_llm_metric          # selected from custom_metrics pool below
  - agent_turn_count            # selected from custom_metrics pool below

custom_metrics:
  - name: example_llm_metric
    prompt_template: |
      Rate the agent's response 1-5 for helpfulness and accuracy.
      Prompt: {prompt}
      Final response: {response}
      Full trace (for tool-call and reasoning context): {agent_data}
      Return JSON: {"score": <1|2|3|4|5>, "explanation": "<reason>"}

  - 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_function → Python 指标；prompt_template → LLMMetric（LLM-as-judge）；两者都没有且名称为内置指标 → 为该内置指标设置参数（例如 metric_spec_parameters.rubric_group_key）。字段参考请参阅 references/metrics-guide.md。

Agent 轨迹字段模型。 对于由 agents-cli eval generate（或 eval dataset synthesize）生成的数据集，每个评估用例都会向指标公开三个标准字段：

• {prompt} — 用户消息（或第一轮用户消息）。
• {response} — Agent 的最终文本响应，从最后一个包含文本的事件中提取。在 custom_function 回调中，该字段为 instance['response']，其结构为 {"role": "model", "parts": [{"text": "..."}]}。
• {agent_data} — 完整的结构化 turns/events 轨迹，适用于需要根据工具调用或中间推理进行判断的评审模型。

reference、context 和 rubric_groups 需要由你在用例中编写：eval generate 会将它们带入轨迹，但不会自行生成，因此只有在你填写的位置，{reference} / {context} 才能解析到值。rubric_groups 并非占位符：托管的评分标准指标会从用例中读取它，而 custom_function 可通过 instance['rubric_groups'] 获取它。请参阅 references/dataset_schema.md（每个用例的评分标准）。

基于代码的指标默认在本地进程内执行（无需 GCP 项目或区域，但 evaluate(instance) 函数会以 CLI 的权限运行）。在指标上设置 execution: "remote"，即可改为在 Gemini 平台的 CodeExecutionMetric 沙盒中于服务端运行——此方式需要配置 GCP 项目和区域。

---

常见注意事项

使用基于评分标准的工具评估，而不是硬编码序列

使用严格的序列匹配来评估 Agent 的工具使用情况很脆弱，因为 Agent 可能会以不同顺序调用辅助工具（例如搜索或地理编码工具），或主动执行额外步骤。

建议改用 multi_turn_tool_use_quality / `multi_turn_trajectory_quality``。这些指标会自动生成基于内容和意图的自适应评分标准，使用 LLM 评审模型从语义层面评估技术正确性和技术序列逻辑，而不是强制进行僵化匹配。

应用名称必须与目录名称一致

ADK 项目。

App 对象的 name 参数必须与包含你的 Agent 的目录名称一致：

# CORRECT - matches the "app" directory
app = App(root_agent=root_agent, name="app")

# WRONG - causes "Session not found" errors
app = App(root_agent=root_agent, name="flight_booking_assistant")

Gemini 平台评测区域

eval run、eval grade 和 eval submit 默认使用 global 端点。它们不会继承清单中的 region（评测服务仅支持部分区域），而 eval analyze 只能使用 global。可通过 --region <REGION>（例如，为满足数据驻留要求）为单次运行指定区域；如果区域不受支持，服务会拒绝：

400 FAILED_PRECONDITION: Unsupported region for Vertex Evaluation Service: <region>

eval generate（不带 --url 标志）和 eval dataset synthesize 会在本地运行你的 Agent，因此会遵循 Agent 自身的 .env——尤其是 GOOGLE_CLOUD_LOCATION，它会在 Agent 使用 Gemini 平台时选择模型端点（GOOGLE_GENAI_USE_ENTERPRISE=true）；使用 GEMINI_API_KEY（AI Studio）时则不会用到它。这些命令不接受 --region，也不会用清单中的 region 覆盖你的 .env；要更改模型区域，请编辑 .env——或者，更好的做法是仅针对单个 Agent，在代码中通过 Gemini(model=…, client_kwargs={"location": …}) 固定区域。它的优先级高于环境变量，也让环境变量可继续用于其他用途。需要注意的是，对于 synthesize，其场景生成步骤会在 GOOGLE_CLOUD_LOCATION 指定的区域调用服务端评测，因此即使 Agent 本身可以在其他区域运行，也应将此区域设为评测支持的区域（默认为 global）。

没有符合数据驻留规则的评测区域？ 可改用本地自定义指标——custom_metrics 条目中的 custom_function（execution: local 为默认值）会在进程内评分，不需要 GCP 区域。你会失去托管的内置指标，但 custom_function 仍可自行在符合要求的区域调用 LLM 评审，因此在任何区域都能进行 LLM 评审评分。

before_agent_callback 模式（状态初始化）

ADK 项目。

始终使用回调初始化指令模板中使用的会话状态变量。这样可避免首轮运行时发生 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="Based on preferences: {user_preferences}...",
)

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

启用“思考”模式的模型可能会跳过工具调用。可通过模型的工具选择配置强制使用工具（ADK： 使用 tool_config 并设置 mode="ANY"），或切换到非思考模型，以确保工具调用行为可预测。

---

常见评测失败原因

现象	原因	修复方法
不同运行的分数波动	模型具有非确定性	设置 temperature=0，或使用基于评分标准的评测并采用多个样本
LLM 评审在评测中忽略图像/音频	get_text_from_content() 会跳过非文本部分	使用支持视觉能力的评审模型自定义指标（参见 references/multimodal-eval.md）

---

证明你的工作

不要只声称评测通过了——要展示证据。具体输出能避免盲目自信，并及早发现问题。

• 运行评测后： 粘贴分数表输出，让用户准确了解哪些用例通过、哪些失败。
• 修复失败后： 展示你修复的特定用例的修复前后分数，并确认其他用例均未退化。
• 部署前： 重新运行 agents-cli eval run，展示每个用例的分数，而不只是你修复的用例。无论分数如何，eval run 都会以 0 退出，因此你粘贴的分数才是判断标准，而不是退出代码。

---

相关技能

• /google-agents-cli-workflow — 开发工作流，以及由规范驱动的构建、评测和部署生命周期
• /google-agents-cli-adk-code — 编写 Agent 代码的 ADK API 速查（仅限 ADK 项目）
• /google-agents-cli-scaffold — 使用 agents-cli scaffold create / scaffold enhance 创建和增强项目
• /google-agents-cli-deploy — 部署目标、CI/CD 流水线和生产工作流
• /google-agents-cli-observability — 用于调试 Agent 行为的 Cloud Trace、日志记录和监控