企业官网建设流程全解析

agents-cli eval generate + grade 两步走：自定义 trace 路径高级用法指南

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli

本文带你掌握agents-cli 评估命令的核心进阶玩法：用eval generate生成 Agent 执行 trace（完整轨迹），再用eval grade对 trace 打分。相比一条命令跑完的eval run，两步走模式让你可以把 trace 写到自定义路径、复用已有 trace 反复重新评分，是 AI Agent 评测调试中非常实用的高级用法，新手也能快速上手。

为什么要把评估拆成两步走？

在脚手架生成的 Agent 项目里，通常推荐先跑一键式的agents-cli eval run——它会在内部串联generate（跑推理）+ grade（打分）两步，一步出分。

但以下场景就需要把两步拆开：

• 📂 希望把 trace 文件保存到自己指定的目录（比如纳入版本管理）；
• 🔁 修改了评分指标（metrics）后，不想重新跑一遍 Agent，只想用旧 trace 重新打分；
• 🔌 你的 trace 不是eval generate生成的（例如来自eval dataset synthesize或手工整理），只需单独评分。

两步走模式的本质：generate 只负责"跑 Agent 拿轨迹"，grade 只负责"拿轨迹打分"，两者通过 trace 文件解耦。相关设计可以在 docs/src/guide/evaluation.md 中找到官方说明。

三步走：先理解项目的默认 trace 路径

agents-cli的评估产物遵循一套固定的目录约定（定义在 src/google/agents/cli/eval/_paths.py）：

其中阶段 2 的 trace 文件就是本次主角：它是一个 JSON 文件，包含每个评估用例（eval case）里 Agent 的完整响应与function_call/function_response事件。

第一步：用 eval generate 生成自定义路径的 trace

eval generate会读取数据集，逐条把用例发给 Agent（默认在本地起 HTTP 服务，或用--url指向已部署的 Agent），并行执行后把填充好的 trace 写到--output指定的位置：

# 把 trace 写到自定义目录 custom_traces/ agents-cli eval generate \ --dataset tests/eval/datasets/custom-dataset.json \ --output custom_traces/

两个实用细节：

• --output传入目录时，会自动在里面生成带时间戳的traces_<时间戳>.json，多次运行互不覆盖；
• 不传--dataset时，默认使用项目自带的 tests/eval/datasets/basic-dataset.json 示例数据集。

参数细节可查阅 src/google/agents/cli/eval/cmd_generate.py。

第二步：用 eval grade 对 trace 重新评分

eval grade接受单个 trace 文件或一个目录（目录下所有*.json会被合并评分），再按内置指标或自定义指标打分：

# 从自定义目录读 trace，指定指标评分 agents-cli eval grade --metrics general_quality --traces custom_traces/

几个常用选项（完整定义见 src/google/agents/cli/eval/cmd_grade.py）：

• --traces：trace 文件或目录，省略时默认扫描artifacts/traces/；
• --metrics：逗号分隔的内置指标，如final_response_quality,grounding；
• --config：指定tests/eval/eval_config.yaml之类的指标配置文件（默认路径即此处）；
• --output：评分结果目录，默认写入artifacts/grade_results/。

评分结果会同时输出带时间戳的results_<时间戳>.json和可直接在浏览器打开的.html报告，并支持后续用agents-cli eval compare对比两次结果，验证改动是否真的有效。

三大典型场景：自定义 trace 路径的用武之地

🎯场景一：trace 入库管理把 trace 输出到--output my_traces/这类可提交的目录，团队可以共享同一批 trace、统一评分口径。

🎯场景二：改指标，不重跑换了一版 LLM-judge 提示词或自定义custom_function后，直接对旧 trace 目录重新eval grade即可，省去重复调用 Agent 的时间和费用。这正是两步走最大的省钱点。

🎯场景三：接入 CI 流水线trace 文件可作为流水线的中间产物存档，评分步骤与推理步骤分离触发，失败时也能只重放评分环节快速定位问题：

小结：两步走的核心价值

• eval generate= 跑 Agent，产出填充好的 trace；eval grade= 读 trace，产出评分结果；
• 两者靠--output/--traces参数解耦，trace 可存任意路径、可反复复用；
• 日常快速验证仍推荐agents-cli eval run，需要自定义 trace 路径或重新评分时再切换到两步走模式。

更多评估技巧（数据集合成、多轮指标选择、eval-fix 循环）可参考 skills/google-agents-cli-eval/SKILL.md 与 docs/src/guide/evaluation.md。

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli