Agent Evals / Harness 模板
学完 Evals 和 Harness 之后，很多人会点头觉得都对，但一到自己动手时又会卡住：
那我到底应该从什么模板开始？
因为概念知道了，并不等于工程上能马上落地。
这篇文档的目标，就是把最常用、最适合起步的一批 Agent Evals / Harness 模板整理出来，让你能直接套用。
1. 为什么需要模板
原因很简单：
- 很多团队不是不知道要评估
- 而是不知道第一版应该怎么组织
结果就会变成：
- 每次改 prompt 都靠感觉
- 失败案例没有沉淀
- 日志很多但不成体系
- 版本之间没法稳定比较
模板的价值就在于：
- 降低启动成本
- 统一记录方式
- 帮你从“知道应该做”走到“真的做起来”
2. 先看最小闭环
一个最小的 Agent Evals / Harness 闭环，通常至少包含：
- 任务集模板
- 单次运行记录模板
- 评估维度模板
- 版本对比模板
- 回归检查模板
如果这 5 块都具备，你就已经不再只是“主观觉得系统变好了”。
2.1 一份最小可复制清单
如果想直接照着开始，可以先用这份最小 checklist：
[ ] 我有一组固定任务样本
[ ] 我能记录单次运行的关键轨迹
[ ] 我有明确的评估维度
[ ] 我能比较两个版本的差异
[ ] 我能把失败案例沉淀成回归样本
如果这 5 条都还没有，可以先把它们补起来。
3. 模板一：任务集模板
先从一组稳定任务开始。
建议每条任务至少包含下面这些字段：
Task ID:
Task Title:
User Goal:
Task Type:
Expected Outcome:
Key Constraints:
Relevant Knowledge Source:
Risk Level:
Notes:
3.1 字段解释
Task ID：唯一标识User Goal：用户真正想完成什么Task Type：检索型、工具型、调研型、写作型等Expected Outcome：什么算基本成功Key Constraints：哪些条件不能违反Risk Level：低、中、高
3.2 为什么它重要
因为任务集是后面所有评估的基础。
没有稳定任务集，你每次都像在打移动靶。
3.3 可复制表格版本
| 字段 | 含义 | 示例 |
|---|---|---|
Task ID | 任务唯一标识 | rag-001 |
Task Title | 任务标题 | 调研框架适用性 |
User Goal | 用户真正目标 | 判断框架是否适合内部知识助手 |
Task Type | 任务类型 | research-agent |
Expected Outcome | 成功标准 | 给出结论、风险、依据 |
Key Constraints | 关键约束 | 不能脱离给定文档回答 |
Risk Level | 风险等级 | medium |
Notes | 备注 | 历史上容易漏风险项 |
4. 模板二：单次运行记录模板
每次运行都建议记录一份统一结构。
Run ID:
Task ID:
Model Version:
Prompt Version:
Tool Set Version:
Start Time:
End Time:
Total Steps:
Final Status:
Stop Reason:
Final Answer:
如果是 Agent，最好再补一块步骤轨迹：
Step 1:
Goal:
Action:
Tool:
Observation:
State Update:
Step 2:
Goal:
Action:
Tool:
Observation:
State Update:
4.1 为什么它重要
因为 Agent 问题往往不在最终答案，而在过程。
没有统一的 run 记录，后面几乎无法系统复盘。
4.2 可复制表格版本
| 字段 | 含义 | 示例 |
|---|---|---|
Run ID | 单次运行标识 | run-2026-04-29-01 |
Task ID | 对应任务 | rag-001 |
Model Version | 模型版本 | gpt-x |
Prompt Version | prompt 版本 | prompt-v3 |
Tool Set Version | 工具版本 | tools-v2 |
Total Steps | 总步数 | 6 |
Final Status | 最终状态 | success |
Stop Reason | 结束原因 | enough-evidence |
Final Answer | 最终输出摘要 | 适合，但需注意集成成本 |
5. 模板三：评估维度模板
评估最好分层，而不是只给一个总分。
可以先用下面这个模板：
Result Quality:
- Correctness:
- Completeness:
- Relevance:
Process Quality:
- Tool Selection:
- Tool Arguments:
- Evidence Usage:
- Step Efficiency:
System Quality:
- Latency:
- Cost:
- Stability:
- Risk Compliance:
5.1 为什么分层
因为 Agent 的退化方式很多：
- 最终结果不错，但过程很低效
- 工具调对了，但答案没整合好
- 结果看起来行，但成本已经过高
只看一个总分，很难定位问题。
5.2 可复制评分表
| 维度 | 问题 | 评分方式 |
|---|---|---|
Correctness | 最终结论对不对 | 0/1/2 |
Completeness | 有没有漏关键点 | 0/1/2 |
Tool Selection | 工具选得对不对 | 0/1/2 |
Evidence Usage | 是否正确用了证据 | 0/1/2 |
Step Efficiency | 是否步骤过多 | 0/1/2 |
Latency | 是否在可接受范围 | pass/fail |
Cost | 是否超预算 | pass/fail |
6. 模板四：版本对比模板
每次系统改动后，最好都留下一张简洁对比表。
可 以用下面这个结构：
Version A:
Version B:
Change Summary:
Overall Completion Rate:
Overall Tool Success Rate:
Average Steps:
Average Cost:
Average Latency:
Improved Tasks:
- ...
Regressed Tasks:
- ...
Open Questions:
- ...
6.1 为什么它重要
因为真实问题往往不是“新版本是不是更强”，而是：
- 哪些地方变好了
- 哪些地方变差了
6.2 可复制对比表
| 指标 | Version A | Version B | 变化 |
|---|---|---|---|
| Completion Rate | |||
| Tool Success Rate | |||
| Avg Steps | |||
| Avg Cost | |||
| Avg Latency | |||
| Key Gains | |||
| Key Regressions |
7. 模板五：失败案例模板
失败案例最好不要只留一条“这次不行”。
建议结构化保存：
Failure ID:
Task ID:
Failure Type:
Observed Behavior:
Expected Behavior:
Root Cause Hypothesis:
Trace Snippet:
Fix Attempt:
Regression Added:
7.1 常见 Failure Type
比如：
- Wrong Tool
- Wrong Argument
- Missing Evidence
- Looping
- Premature Stop
- Ungrounded Output
7.2 可复制失败记录表
| 字段 | 含义 |
|---|---|
Failure ID | 失败案例标识 |
Task ID | 对应任务 |
Failure Type | 失败类型 |
Observed Behavior | 实际表现 |
Expected Behavior | 期望表现 |
Root Cause Hypothesis | 根因假设 |
Fix Attempt | 修复尝试 |
Regression Added | 是否加入回归集 |
8. 模板六：回归检查模板
每次重要改动之后，至少做一次最小回归检查。
Regression Run Date:
Compared Versions:
Task Set Size:
Pass Count:
Fail Count:
New Failures:
Recovered Failures:
Blocked Items:
Release Decision:
8.1 Release Decision 可以怎么写
例如：
- Safe to Release
- Release with Known Risk
- Hold Release
8.2 回归 checklist 版本
[ ] 关键任务是否全部重跑
[ ] 历史失败案例是否覆盖
[ ] 是否出现新失败
[ ] 是否有旧失败被修复
[ ] 是否出现成本或时延明显恶化
[ ] 是否满足发布条件
这样迭代会更稳定，也更接近正常的工程节奏。
9. 模板七：上线前检查模板
如果系统开始接近生产，可以再加一层上线前检查。
Goal Clearly Defined:
Task Set Ready:
Trace Logging Enabled:
Eval Dimensions Defined:
Regression Baseline Available:
High-risk Tools Guarded:
Fallback Path Ready:
Human Escalation Ready:
这个模板本质上是在把 Production Checklist 和 Harness 接起来。
9.1 上线前表格版本
| 检查项 | 状态 | 备注 |
|---|---|---|
| Goal Clearly Defined | ||
| Task Set Ready | ||
| Trace Logging Enabled | ||
| Eval Dimensions Defined | ||
| Regression Baseline Available | ||
| High-risk Tools Guarded | ||
| Fallback Path Ready | ||
| Human Escalation Ready |
10. 怎么把这些模板用起来
最实用的顺序通常是：
10.1 先上任务集模板
先准备一批真实问题。
10.2 再上单次运行模板
先把轨迹留住。
10.3 再补评估维度
让“好坏”有标准。
10.4 最后上版本对比和回归模板
让优化开始真正可比较。
11. 最小可用组合
如果现在不想做得太重，我建议至少从这 3 个模板开始：
- 任务集模板
- 单次运行记录模板
- 评估维度模板
这已经足够让很多系统摆脱“只靠感觉优化”的阶段。
12. 常见误区
12.1 一上来就设计超级复杂的评估体系
这会让团队很快失去执行动力。
12.2 模板很多，但没人真正填
模板的目标不是好看，而是提高可执行性。
12.3 只记录结果，不记录过程
对 Agent 来说，这几乎等于放弃调试能力。
12.4 只记录失败，不做回归
没有回归，失败案例就很难真正形成持续收益。
13. 一句话总结
Evals 和 Harness 真正难的地方，往往不是理念，而是第一版怎么开始。
而模板的价值就在于：
把原本抽象的评估与运行闭环，压缩成一套团队可以直接拿来用、不断复用和逐步升级的工程骨架。