内容
本清单是文章《代理可观测性驱动代理评估》的实用补充，该文阐述了代理评估与传统软件测试的区别、介绍了核心可观测性原语（运行记录 runs、追踪 traces、对话线程 threads）及其与评估层级的映射关系。若您是代理评估的新手，请先阅读该文。
本文聚焦于“如何做”，提供了一套构建、运行和发布代理评估的分步检查清单。
从能给出有效信号的简单评估开始。 即使您的架构仍在演进，几个端到端的评估也能立即为您提供基准。仅在有证据表明简单方法无法发现真实缺陷时，才增加复杂度。
构建评估前的准备工作
☑️ 在构建任何评估基础设施前，手动审查 20–50 条真实的代理执行轨迹
☑️ 为单个任务定义明确的成功标准
☑️ 将能力评估与回归评估区分开
☑️ 确保能够识别并解释每次失败的原因
☑️ 指定一名领域专家负责评估工作
☑️ 排除基础设施和数据管道问题后再归咎于代理
深度解析
在构建任何评估基础设施前，手动审查 20–50 条真实的代理执行轨迹
利用 LangSmith 将追踪数据转化为标注队列、数据集及实验。
在投入开发基础设施前，花 30 分钟通读真实代理的执行轨迹。相比任何自动化系统，这种方式能让您更深入地理解失败模式。LangSmith 的 追踪 和 标注队列 对此非常有效。
为单个任务定义明确的成功标准
如果两位专家对通过/失败无法达成一致，说明任务需要细化：
- 模糊的成功标准：“请总结这份文档。”
- 清晰的成功标准：“从本次会议记录中提取三项主要行动项。每项应……”
回归评估回答的是“它还能正常工作吗？”，其通过率应接近 100%，并能及时发现性能回退。
确保能够识别并解释每次失败的原因
若您无法解释某次失败的原因，应在构建自动化评估前进行更深入的分析。这正是您应将 60–80% 的评估精力 投入的地方。遵循以下流程：
- 收集轨迹：从生产环境或测试中获取代表性失败的案例
- 开放编码：由领域专家审阅轨迹，不加预设分类地记录所有问题（或使用我们的 标注队列，让相关专家独立审阅轨迹）
- 归类：将问题归纳为失败分类体系（提示词问题、工具设计问题、模型局限、工具故障、数据缺失等）
- 迭代：持续审阅直至不再发现新的失败类别
完成归类后，解决方案取决于根本原因：
- 提示词问题：代理因指令不清而误解 → 修改提示词
- 工具设计问题：工具接口易导致代理出错 → 重新设计参数、添加示例、明确边界
- 模型局限：指令清晰但大语言模型无法泛化到边缘情况 → 添加示例、尝试不同架构，或使用其他模型
- 尚不明确：尚未分析足够多的失败案例以发现规律 → 先进行更多错误分析
指定一名领域专家负责评估工作
必须有人负责评估流程：维护数据集、校准评判标准、处理新出现的失败模式，并界定何为“足够好”。理想情况下，应由一位领域专家担任质量仲裁者，而非委员会式决策。
排除基础设施和数据管道问题后再归咎于代理
Witan Labs 团队 发现，一个简单的提取错误竟使其基准分数从 50% 跃升至 73%。基础设施问题（超时、格式错误的 API 响应、缓存过期）常伪装成推理失败。务必先检查数据管道。
选择评估层级
单步 vs. 全回合 vs. 多回合评估
并非所有评估都测试相同内容。请将评估与代理行为的适当层级相匹配。如需深入了解每个层级，请参见《代理可观测性驱动代理评估》。
单步 vs. 全回合 vs. 多回合评估
☑️ 理解三种评估层级：单步（run）、全回合（trace）和多回合（thread）
☑️ 从 trace 层级（全回合）评估入手，再根据需要叠加 run 层级和 thread 层级
深度解析
单步评估
此类评估回答：“代理是否选择了正确的工具？”“是否生成了有效的 API 调用？”它们最容易自动化，但要求代理架构稳定；若您仍在频繁更改工具定义，则 run 层级评估可能失效。
全回合评估
大多数团队应从此类评估起步。从三个维度对完整轨迹进行评分：
- 最终响应：输出是否正确且有用？
- 执行路径：代理是否采取了合理路径？（不一定是您预期的确切路径，只要有效即可）
- 状态变更：代理是否创建了正确的成果？（如文件写入、数据库更新、会议安排等）
状态变更评估常被忽视，但对那些“做事”而非仅“说话”的代理至关重要。例如，若您的代理负责安排会议，不仅应验证其是否说了“会议已安排！”，还需确认日历事件真实存在，且时间、参与者和描述均无误。若其编写代码，则需运行代码；若更新数据库，则需查询对应行。最终响应可能显示“已完成！”，但实际状态可能是错的。
多回合评估
这是最难实现的层级，应在 trace 层级评估稳固后再引入。
💡
实用技巧：使用 N-1 测试法。 从生产环境中提取真实对话前缀（前 N-1 轮），仅让代理生成最后一轮回复。这可避免完全合成多轮模拟中的复合误差累积问题。
从 trace 层级（全回合）评估入手，再根据需要叠加 run 层级和 thread 层级
Trace 层级提供的信号密度最高。Run 层级适用于调试特定步骤，而 thread 层级则在代理进行多轮对话时尤为重要。
数据集构建
☑️ 确保每项任务都无歧义，并提供参考解法以证明其可解
☑️ 同时测试正例（行为应发生）和反例（行为不应发生）
☑️ 确保数据集结构与所选评估层级匹配
☑️ 根据代理类型定制数据集（编程、对话、研究）
☑️ 若无生产数据，则生成种子示例
☑️ 来源包括内部试用错误、改编外部基准及手工编写的行为测试
☑️ 建立追踪到数据集的飞轮机制以实现持续改进
深度解析
确保每项任务都无歧义，并提供参考解法以证明其可解
- 模糊任务：“帮我找去纽约的好航班。”
- 明确任务：“查找从 SFO 到 JFK 的往返航班，出发时间为 12 月 15–17 日，返程为 12 月 22 日，票价低于 400 美元，经济舱。”
若代理无论如何都无法成功（信息缺失、约束条件不可能达成），则问题出在任务本身，而非代理。为每项任务提供参考解法，既可证明其可解性，又可作为评分基准。
同时测试正例（行为应发生）和反例（行为不应发生）
若仅测试“是否应在需要时搜索？”，您将优化出一个“处处搜索”的代理。务必也测试反例。包含旨在证伪假设而非仅确认预期行为的示例。
确保数据集结构与所选评估层级匹配
- Run 层级（单步）评估需有参考工具调用或决策
- Trace 层级（全回合）评估需有期望的最终输出和/或状态变更
- Thread 层级（多回合）评估需有多轮对话序列及期望的上下文保持能力
根据代理类型定制数据集（编程、对话、研究）
- 编程代理：除质量评分表外，还应包含确定性测试套件（通过/失败的单元测试）
- 对话代理：包含多维标准，如任务完成度与交互质量（同理心、清晰度）
- 研究代理：包含事实核查（主张是否有来源支持？）和覆盖度检查（关键事实是否齐全？）
若无生产数据，则生成种子示例
定义任务的关键变化维度（查询复杂度、主题、边缘情况类型）。手工创建约 20 个覆盖这些维度的示例输入，将其送入现有代理运行，审阅并修改后作为可靠 ground truth 存储。
💡
实用技巧： 20–50 个经人工审核且您确信的示例，其效果优于数百个未经核验的合成示例。此处质量胜于数量！
来源包括内部试用错误、改编外部基准及手工编写的行为测试
度过冷启动阶段后，您需要一个持续发现新评估的机制。以下三种策略协同效果最佳：
- 每日内部试用代理，并将每次错误转化为评估。这与生产监控不同，而是团队有意对代理进行跨真实工作流的压力测试。
- 从 Terminal Bench 或 BFCL 等外部基准中提取并适配任务。不建议整体运行基准测试，而应挑选您关心的能力相关任务，并为其定制适配。
- 针对特定重要行为手工编写聚焦测试，例如“代理是否并行调用工具？”或“是否会对模糊请求提出澄清问题？”
参见《我们如何为 Deep Agents 构建评估》，了解该方法的实际应用案例。
评分器设计
☑️ 按评估维度选择专用评分器：默认对客观检查使用代码型，对主观评估使用 LLM-as-judge，对模糊情况使用人工，对版本对比使用成对比较
☑️ 区分护栏（内联、运行时）与评估器（异步、质量评估）
☑️ 优先采用二元通过/失败而非数值评分
☑️ 将 LLM-as-a-Judge 评分器校准至人类偏好
☑️ 评估结果而非精确路径，并为渐进式进展设置部分得分
☑️ 使用基于您的错误分析的自定义评估器，而非通用现成指标
深度解析
按评估维度选择专用评分器
| 评分器类型 | 适用场景 | 注意事项 |
|---|---|---|
| 代码型 | 确定性检查、工具调用验证、输出格式、执行结果 | 可能对有效但非预期的格式误判失败 |
| LLM-as-judge | 精细质量、基于评分表的打分、开放式任务 | 需与人类校准（参见 Align Evals） |
| 人工 | 校准、主观标准、边缘情况 | 成本高、速度慢、难以扩展 |
当答案客观明确时，默认使用代码型评估器。对客观任务使用 LLM-as-judge 可能不可靠，不一致的判断会掩盖真实回归。切换至确定性比较常能消除不一致性，提供更清晰的信号。仅对真正主观的评估保留 LLM-as-judge。
💡
实用技巧： 与其试图创建一个正确性评估器，不如将评估分解为各维度的专用评分器，而非单一综合评估器。
例如：Witan Labs 团队构建了五个专用评估器（内容准确性、结构、视觉排版、公式场景、文本质量），每个都有适合该维度的阈值。这能让您更清晰地了解究竟何处失败！
区分护栏与评估器
| 护栏 | 评估器 | |
|---|---|---|
| 时机 | 执行期间、用户看到输出前 | 生成后、异步进行 |
| 速度 | 毫秒级（必须快速） | 秒至分钟级（可昂贵） |
| 目的 | 阻止危险或格式错误的输出 | 衡量质量并捕获回归 |
| 示例 | PII 检测、格式验证、安全过滤器 | LLM-as-judge 打分、路径分析 |
安全检查与格式验证属于护栏，应内联运行。质量评估与回归测试属于评估器，应异步运行。请勿混淆二者。
优先采用二元通过/失败而非数值评分
1–5 分制会引入相邻分数间的主观差异，并要求更大的样本量以获得统计显著性。二元制迫使思考更清晰：代理要么成功，要么失败。您总可将复杂任务分解为多个二元检查。
注：近期研究 表明，在使用 LLM-as-judge 时，短尺度（0–5）可能实现更强的人类-LLM 对齐，但对人工评审员而言，二元制更简单，迭代更快。
将 LLM-as-a-Judge 评分器校准至人类偏好
- 先用 LangSmith 的 Align Evaluator 功能标记 20+ 个示例，再逐步扩充至约 100 个以达到生产级置信度
- 在评判器输出中包含推理过程；这能提高准确性，并让您审计其为何给出某一分值（Anthropic 的 Demystifying Evals 也强调这一点）
- 定期重新校准；评判器会随时间漂移，且 没有单一评判器在所有基准上始终可靠
- 使用 少样本示例 提升评估器一致性；更正可自动填充为 LangSmith 中的少样本示例
评估结果而非精确路径，并为渐进式进展设置部分得分
代理常能找到创造性解决方案。正如 Anthropic 在 Demystifying Evals 中所言：“不要评估代理采取的路由，而要评估其产出。”若您要求“必须按 A→B→C 顺序调用工具”，则会淘汰那些找到更优路径的代理。更好的做法是：“会议是否被正确安排？”而非“是否先调用了 check_availability 再调用 create_event？”
能正确识别问题但最终失败的代理，优于立即失败的代理。应为渐进式进展设置部分得分，使您的指标反映阶段性进步。
使用基于您的错误分析的自定义评估器，而非通用现成指标
现成指标如“有帮助性”或“连贯性”会制造虚假信心。真正重要的评估器是能捕捉您通过上述错误分析发现的特定失败模式的那些。
运行与迭代
☑️ 区分离线、在线和临时评估，并同时使用三者
☑️ 每项任务运行多次试验以应对非确定性
☑️ 手动审阅失败评估的轨迹，以验证评分器公平性
☑️ 确保每次试验在干净、隔离的环境中运行，无共享状态
☑️ 按能力类别标记评估，说明每项评估的内容，并在质量之外跟踪效率指标（步骤数、工具调用、延迟）
☑️ 识别通过率何时趋于平稳，并据此演进您的测试套件
☑️ 只保留直接衡量您关心的生产行为的评估
☑️ 投资于工具接口设计与测试，而非仅优化提示词
☑️ 区分任务失败（代理出错）与评估失败（评分器出错）
深度解析
区分离线、在线和临时评估，并同时使用三者
本清单大部分聚焦离线评估，这很合理。离线评估让您能通过精心策划的数据集、受控实验，在发布前进行迭代。一旦代理进入生产环境，您还需要在线和临时评估。
| 时机 | 是什么 | 何时使用 |
|---|---|---|
| 离线 | 精心策划的数据集、预部署运行 | 在发布变更前测试 |
| 在线 | 在生产轨迹上的持续评估 | 在真实流量中捕获失败 |
| 临时 | 对摄入轨迹的探索性分析 | 发现未预料到的模式（见 Insights） |
下文“生产就绪”部分将详细讲解如何设置在线评估和调度临时轨迹探索。
每项任务运行多次试验以应对非确定性
模型输出在不同运行间存在波动。若非成本受限，请使用多次 重复。运行多次试验时，应在声明改进前计算置信区间——单次运行的基准噪声很大。对非确定性代理，可根据产品需求选用 pass@k（k 次尝试中至少一次成功）或 pass^k（k 次全部成功）指标。
同时跟踪运营指标：轮数、 token 用量、延迟、单任务成本。准确率达 95% 但速度慢 10 倍的代理未必是改进。
按能力类别标记评估，说明每项评估的内容，并在质量之外跟踪效率指标
按评估内容而非来源对评估分组。像 file_operations、retrieval、tool_use、memory、conversation 这样的类别，能为您提供介于单一总分与个别测试结果之间的“中间视图”。为每个评估添加 docstring，说明其如何衡量代理能力。这能在套件扩大时保持意图清晰，并让您在修改工具定义后仅运行 tool_use 子集。
为每项实验附加元数据，以便您能 按相关维度过滤、分组和比较运行。这可轻松回答“从 GPT-4.1 切换到 Claude Sonnet 是否提升了准确率？”或“哪个提示词版本在此数据集上出现回归？”等问题，而无需翻查日志。LangSmith 在可用时会自动捕获 git 信息，但显式标记模型与提示词元数据会在实验量增长时迅速体现价值。
质量确立后，可对模型进行效率对比。准确率达 95% 但速度慢 10 倍的代理未必是改进。跟踪观察步骤/理想步骤、观察工具调用/理想工具调用、观察延迟/理想延迟等比率。这与“评估结果而非精确路径”并不冲突：理想路径衡量效率，而非正确性。您仍会通过采用创新路径的代理，但能看到其是否耗时更长。参见 How we build evals for Deep Agents 中的指标框架，了解实际应用案例。
手动审阅失败评估的轨迹，以验证评分器公平性
“失败”任务可能是评分器未预料的创造性有效解决方案。审阅轨迹正是判断评分器是否公平的方式。
若试验 2 能看到试验 1 的产物，则结果不独立。具体表现为：
- 编程代理：每试验使用全新容器或虚拟机
- API 调用代理： staging 环境或 mock 服务
- 数据库代理：试验间快照还原
识别通过率何时趋于平稳，并据此演进您的测试套件
当通过率平稳且同类任务新增无法揭示新失败模式时，就该演进：加入更难的任务、测试新能力，或转向不同维度。在饱和评估集上反复打磨是浪费 effort。
只保留直接衡量您关心的生产行为的评估
每项评估都会随时间对系统施加压力。盲目添加数百项测试很 tempting，但这会制造进步的假象。您可能最终优化出一套与生产实际需求脱节的评估套件。更多评估不等于更好代理。构建针对性评估，并定期修剪那些不再提供信号的评估。参见 How we build evals for Deep Agents，了解该方法的实际应用案例。
投资于工具接口设计与测试，而非仅优化提示词
工具设计可消除一整类代理错误。Anthropic 团队 指出，他们在构建 SWE-bench 代理时，花在优化工具上的时间多于提示词。测试模型如何实际使用您的工具：尝试不同参数格式（diffs 还是全文重写、JSON 还是 markdown）， redesign 接口使错误更难发生，并投入精力编写带示例的清晰文档。目标是让错误在结构上 impossible，而不仅是 unlikely。例如，要求绝对文件路径即可 eliminate 一整类导航错误。
区分任务失败（代理出错）与评估失败（评分器出错）
显式跟踪运行状态（完成、错误、超时）。将超时标记为“推理错误”会污染您的信号。分离任务失败与评估失败，以保持指标 clean。
生产就绪
☑️ 将 consistently 高通过率的能力评估纳入回归套件
☑️ 将回归评估集成至 CI/CD 流水线，并设置自动化质量门禁
☑️ 捕获用户反馈
☑️ 为生产流量设置 在线评估 ****
☑️ 定期手动探索生产轨迹，超越自动化检查
☑️ 将提示词与工具定义的版本管理与代码同步
☑️ 确保生产失败能反馈至数据集、错误分析与评估改进
深度解析
登顶之后，就要守住成果。过去测试“我们能否做到？”的任务，现在变为“我们还能做到吗？”
将回归评估集成至 CI/CD 流水线，并设置自动化质量门禁
典型流程如下：
- 代码或提示词变更触发流水线（通过 git push、PromptHub 更新或手动触发）
- 离线评估运行单元测试、集成测试，并用 cheap fast 评分器对精心策划的数据集进行评估
- 若离线评估通过，则部署预览版
- 在线评估在预览版上用 live 数据运行，使用 LLM-as-judge 评分器
- 仅当所有质量门禁通过时才发布至生产，否则将失败轨迹路由至标注队列并提醒团队
在 CI 中为每次提交使用 cheap 的代码型评分器。将昂贵的 LLM-as-judge 评估保留给预览/生产评估。LangSmith 的 CI/CD 流水线指南 提供了结合 GitHub Actions 的完整实现示例。
为生产流量设置在线评估
安全检查、格式验证、质量启发式。您会在生产中发现意想不到的失败模式（参见 You don't know what your agent will do until it's in production）
捕获用户反馈
代理上线后，用户反馈 将成为最有价值的信号之一。自动化评估只能捕获您已知的问题。用户会暴露您未知的：数据集遗漏的边缘情况、技术上正确但无用的输出，以及您从未预料会 broken 的工作流。
结构化地 capture 此反馈，可将其 feed back 至数据集、将评分器校准至现实期望，并优先处理对用户真正重要的改进。
定期手动探索生产轨迹，超越自动化检查
不要 solely 依赖自动化通过/失败。 periodically 探索生产轨迹，寻找评分器未覆盖的意外模式或失败模式、 surprising 的用户行为，或改进机会。我们的 Insights Agent 是很好的方式！
将提示词与工具定义的版本管理与代码同步
LangSmith 让 提示词版本管理 变得 easy。若无此功能，您无法将评估结果与特定变更关联，也不知哪次编辑导致了回归。
确保生产失败能反馈至数据集、错误分析与评估改进
生产成功与失败都应 feedback 至数据集、错误分析与评估改进。这是让您的代理随时间 better 的飞轮！
您不必第一天就实现所有这些项目。选择与当前所处阶段匹配的部分，扎实做好，再逐步扩展。能交付可靠代理的团队，不是拥有最 sophisticated 评估基础设施的团队——而是那些 early 就开始评估且 never stopped iterating 的团队。
完整检查清单
构建评估前
⬜️ 在构建任何评估基础设施前，手动审查 20–50 条真实代理轨迹
⬜️ 为单个任务定义明确的成功标准
⬜️ 将能力评估与回归评估区分开
⬜️ 确保能够识别并解释每次失败的原因
⬜️ 指定一名领域专家负责评估工作
⬜️ 排除基础设施和数据管道问题后再归咎于代理
选择评估层级
⬜️ 理解三种评估层级：单步（run）、全回合（trace）和多回合（thread）
⬜️ 从 trace 层级（全回合）评估入手，再根据需要叠加 run 层级和 thread 层级
数据集构建
⬜️ 确保每项任务都无歧义，并提供参考解法以证明其可解
⬜️ 同时测试正例（行为应发生）和反例（行为不应发生）
⬜️ 确保数据集结构与所选评估层级匹配
⬜️ 根据代理类型定制数据集（编程、对话、研究）
⬜️ 若无生产数据，则生成种子示例
⬜️ 来源包括内部试用错误、改编外部基准及手工编写的行为测试
⬜️ 建立追踪到数据集的飞轮机制以实现持续改进
评分器设计
⬜️ 按评估维度选择专用评分器：默认对客观检查使用代码型，对主观评估使用 LLM-as-judge，对模糊情况使用人工，对版本对比使用成对比较
⬜️ 区分护栏（内联、运行时）与评估器（异步、质量评估）
⬜️ 优先采用二元通过/失败而非数值评分
⬜️ 将 LLM-as-a-Judge 评分器校准至人类偏好
⬜️ 评估结果而非精确路径，并为渐进式进展设置部分得分
⬜️ 使用基于您的错误分析的自定义评估器，而非通用现成指标
运行与迭代
⬜️ 区分离线、在线和临时评估，并同时使用三者
⬜️ 每项任务运行多次试验以应对非确定性
⬜️ 手动审阅失败评估的轨迹，以验证评分器公平性
⬜️ 确保每次试验在干净、隔离的环境中运行，无共享 state
⬜️ 按能力类别标记评估，说明每项评估的内容，并在质量之外 track efficiency metrics（步骤数、工具调用、延迟）
⬜️ 识别通过率何时趋于平稳，并据此演进您的测试 suite
⬜️ 只保留直接衡量您关心的生产行为的评估
⬜️ 投资于工具接口设计与测试，而非仅优化提示词
⬜️ 区分任务失败（代理出错）与评估失败（评分器出错）
生产就绪
⬜️ 将 consistently 高通过率的能力评估纳入回归套件
⬜️ 将回归评估集成至 CI/CD 流水线，并设置自动化质量门禁
⬜️ 捕获用户反馈
⬜️ 为生产流量设置 在线评估
⬜️ 定期手动探索生产轨迹，超越自动化检查
⬜️ 将提示词与工具定义的版本管理与代码同步
⬜️ 确保生产失败能 feedback 至数据集、错误分析与评估改进