Agent Eval：如何判断你的 Agent 真的变好了？
Eval 不是挑几个顺眼案例做演示，而是用任务数据、可判定标准和过程证据，持续比较 Agent 的质量、安全、效率与成本。
文章目录
- 导语
- 一、先定义任务成功，而不是先选评分工具
- 二、Agent 需要评最终结果，也要评执行过程
- 三、评测集从哪里来
- 手工设计的核心场景
- 生产流量中的真实样本
- 对抗与边界样本
- 四、选择能匹配标准的 Grader
- 确定性检查优先
- 参考答案适合边界明确的任务
- 模型评分适合语义质量
- 人工评审用于校准与复杂判断
- 五、一个可执行的 Case 结构
- 六、两条落地路径：自己搭 Runner，或使用评测平台
- 路径 A：自己实现最小 Eval Runner
- 路径 B：使用 LangSmith、Langfuse 等成熟平台
- 怎么选
- 七、怎样公平比较两个版本
- 发布门不应只有平均分
- 八、Trace 如何帮助 Eval 解释失败
- 九、从离线 Eval 走到生产闭环
- 十、前端与后端视角
- 前端工程师
- 后端工程师
- 十一、费曼式检查：一次 Prompt 优化真的有效吗
- 十二、常见误区
- 十三、本篇总结
- 参考资料
导语
一个 Code Review Agent 改了 Prompt 后，五个演示 PR 都给出了更完整的建议。上线第二天，团队才发现它虽然更爱说话，却漏掉了必须运行的测试，还对低风险文件多调用了三次工具。
这个结论可能只是错觉。
Agent 输出具有非确定性，任务又包含多步决策。最终答案看起来更漂亮，不代表工具用对了；成功率上升，也可能伴随成本翻倍或越权风险。
Eval（评测）要把“我感觉更好”改成可重复的问题：
在一组有代表性的任务上，按照预先定义的标准，新版本是否以可接受的安全、延迟和成本更可靠地完成目标？
一、先定义任务成功，而不是先选评分工具
假设评测“查订单并解释延迟”的 Agent。成功不应只写成“回答质量好”，而要拆成可以判断的条件：
- 使用正确订单，且没有跨用户访问；
- 状态和时间来自工具证据，不编造；
- 必要时查询物流，避免无意义调用；
- 对仍不确定的原因明确说明边界；
- 用户能看懂下一步；
- 延迟和成本在预算内。
不同任务的完成标准不同。代码 Agent 可能要求测试通过且变更范围受控；资料研究 Agent 更关心引用覆盖和来源质量。
Eval 的第一产物不是分数，而是任务契约。
二、Agent 需要评最终结果，也要评执行过程
普通文本生成常关注最终输出。Agent 还会选择工具、修改外部状态，因此至少有四个维度。
| 维度 | 典型问题 |
|---|---|
| 结果 | 目标完成了吗，事实和格式正确吗 |
| 路径 | 工具、顺序、参数和重试是否合理 |
| 安全 | 是否越权、泄露数据或跳过批准 |
| 效率 | 延迟、步数、Token 与外部调用成本如何 |
不要要求执行轨迹与“标准答案”逐步完全一致。开放任务可能有多条正确路径。更合理的是检查关键约束，例如必须读取真实文件、不能调用发送工具、最终修改必须通过测试。
三、评测集从哪里来
一套有用的数据集通常混合三类来源。
手工设计的核心场景
覆盖产品承诺的主要能力、边界和高风险动作。它们数量可以不大，但每条都要知道为何存在。
生产流量中的真实样本
从经过授权和脱敏的运行中抽样，尤其关注用户纠正、失败、低评分、超时和人工接管案例。真实分布能揭示设计者没想到的表达方式。
对抗与边界样本
包括缺少信息、冲突指令、工具超时、空结果、重复回调、过期知识、Prompt Injection 和越权请求。
数据集要保留切片标签：任务类型、语言、用户层级、风险、工具、难度等。总体平均分可能掩盖“新版本让中文请求明显退化”。
生产失败进入评测集前要去重、脱敏并明确预期行为，不能把一堆未分析日志直接称为 Eval。
四、选择能匹配标准的 Grader
确定性检查优先
能用代码判断的，就不要先请另一个模型猜：
- JSON 是否符合 Schema；
- 必须工具是否调用；
- 禁止动作是否出现；
- 引用 ID 是否存在；
- 文件 diff 是否只在允许目录；
- 测试是否通过；
- 延迟和成本是否超预算。
参考答案适合边界明确的任务
分类、抽取、计算等任务可与已验证答案比较，但自然语言表述不应只做完全字符串相等。
模型评分适合语义质量
完整性、解释清晰度和证据一致性常需要模型 Grader。评分 Prompt 应给出明确 rubric、输入证据和等级定义，并用人工标注样本校准。
模型评模型不是客观真理。它可能受措辞、顺序和模型偏好影响。高风险结论仍需要人工抽检，重要发布可采用多种 Grader 交叉验证。
人工评审用于校准与复杂判断
专家评审成本高，却能发现指标遗漏。人工不是只在最后“看几个例子”，还应参与定义 rubric、处理分歧和审查关键失败。
五、一个可执行的 Case 结构
type EvalCase = {
id: string;
input: unknown;
fixture: {
toolResponses: Record<string, unknown>;
initialState?: unknown;
};
assertions: Array<
| { type: "tool_called"; name: string }
| { type: "tool_not_called"; name: string }
| { type: "json_schema"; schemaId: string }
| { type: "contains_evidence"; evidenceIds: string[] }
| { type: "max_cost"; usd: number }
>;
tags: string[];
};
工具响应最好用固定 Fixture、录制回放或隔离测试环境。否则今天查到的订单状态和明天不同，版本差异就无法归因给 Agent。
但离线环境也不能替代线上验证。真实 API 的权限、延迟和数据漂移需要单独的集成测试、Canary 与生产监控。
六、两条落地路径：自己搭 Runner，或使用评测平台
路径 A：自己实现最小 Eval Runner
适合已有测试体系、任务结果容易用代码检查，或数据不能离开本地环境的团队。
第一步先写 10～20 个高价值 Case，而不是搭大平台。Runner 读取固定输入和 Tool Fixture，分别运行基线与候选版本，收集最终输出、Trace、延迟和成本，再执行确定性断言与少量语义 Grader。
输出至少包含：每个 Case 的通过项、失败项、版本差异、失败 Trace 链接和切片汇总。把严重安全约束设为硬门槛，不要与文风分数平均。
常见失败是 Runner 每次访问变化中的真实 API，或修改 Prompt 的同时修改数据与 rubric。验证方法很朴素：同一版本连续跑两次，若大量差异来自环境而非模型，先修测试隔离。
路径 B：使用 LangSmith、Langfuse 等成熟平台
适合希望把生产 Trace 直接加入数据集、运行离线实验、配置线上评分并比较版本的团队。LangSmith 支持数据集、代码/人工/LLM-as-judge/成对评测，并区分离线与在线评测；Langfuse 也能把 Trace、数据集实验、评分和 Prompt 版本关联起来。
落地顺序仍然从任务契约开始：创建小数据集，配置一个确定性安全检查和一个经过人工校准的语义 Grader，运行基线与候选实验，再审查“成功变失败”的样本。平台提供执行与分析表面，不会自动替你定义正确答案。
常见误区是看到平台有很多指标就全部开启，最后没人知道哪个分数决定发布。验证时要求每个发布门都能指回一个业务风险、一个 Case 切片和一条失败 Trace。
怎么选
| 情况 | 起步建议 |
|---|---|
| 测试主要是 Schema、工具和文件断言 | 先写自建 Runner |
| 已有大量 Trace，需要快速沉淀数据集和实验对比 | 评测平台 |
| 数据不能外发，但需要统一界面 | 自托管平台或内部 Runner |
| 团队还说不清“什么叫成功” | 暂停选型，先写任务契约 |
七、怎样公平比较两个版本
比较时控制无关变量：同一数据版本、工具 Fixture、模型快照与参数、最大步数和预算。对非确定性任务，可以重复运行，报告通过率与波动，而不是只挑最好的一次。
同时看“成对变化”：哪些 Case 从失败变成功，哪些从成功变失败。总体提升两分，可能掩盖一个严重安全回归。
发布门不应只有平均分
可以设成：
核心任务成功率不得下降
高风险越权样本必须全部拦截
P95 延迟不超过预算
平均成本涨幅不超过阈值
所有新增严重失败均完成人工复核
阈值是产品选择，不是通用标准。
八、Trace 如何帮助 Eval 解释失败
第十一篇保存的 Trace 可以支持过程 Grader：
- 上下文是否包含正确政策版本；
- 模型是否发出了预期工具调用；
- Runtime 是否拦截了越权动作；
- Tool Result 是否截断；
- 完成条件是否真的被验证。
例如最终答案错误，Trace 显示检索从未返回正确文档，根因更可能在查询或索引；如果正确证据已经在上下文里，问题才更靠近模型判断或最终表达。
Eval 给失败贴标签，Trace 帮你找到修改位置。
九、从离线 Eval 走到生产闭环
推荐的节奏是：
- 开发时运行小而快的回归集；
- 合并前运行完整离线集；
- 候选版本在隔离环境做集成测试；
- 灰度发布，观察真实成功、接管、安全、延迟和成本；
- 将新失败整理为可判定 Case；
- 修复后同时跑旧回归和新 Case。
生产反馈不能直接当真值。用户没投诉不代表答案正确，点赞也可能只反映语气。需要结合业务结果、抽检和后续行为解释。
十、前端与后端视角
前端工程师
前端行为也属于 Agent 体验：流式内容是否乱序、工具状态是否误报、批准按钮是否重复提交、引用能否打开、失败后是否可恢复。端到端 Eval 要覆盖这些交互，而不只是后端最终字符串。
后端工程师
后端需要可重复的 Runner、Fixture、版本清单、追踪关联、结果存储与 CI 门禁。评测代码和数据也要版本化，规则变化时能解释历史分数为何不同。
十一、费曼式检查：一次 Prompt 优化真的有效吗
团队修改了工具描述，五个演示都成功。你应该怎样验证？
- 冻结覆盖正常、异常和越权请求的评测集；
- 用相同环境运行旧版和新版；
- 检查任务成功、安全约束、工具路径、延迟和成本；
- 按任务类型切片，而不只看平均分；
- 阅读从成功变失败的 Case 及其 Trace；
- 达到预设发布门后再灰度观察。
本文简化了统计显著性、标注者一致性和在线实验设计。流量大、风险高的系统需要更严谨的方法；小团队也至少应做到固定数据、明确标准和版本对比。
十二、常见误区
- 用几个精心挑选的 Demo 代替评测集；
- 只评最终文风，不评工具路径和安全；
- 把模型 Grader 当绝对真值；
- 总体分上升就忽略高风险切片回归；
- 每次运行都访问变化中的真实数据，却比较细小差异；
- 修改 Agent 的同时修改数据和 rubric，导致无法归因；
- 只收集失败，不把失败转成明确可判定的回归 Case。
十三、本篇总结
Eval 是 Agent 工程的测量系统，而不是发布前的一次打分活动。
一套可信评测至少包含：代表性任务、明确成功条件、结果与过程 Grader、受控执行环境、分切片比较，以及从生产失败回流的回归闭环。
可观测性回答“发生了什么”，Eval 回答“是否足够好”。下一步我们还要控制模型每一轮究竟看到了什么，因为很多失败既不是工具问题，也不是模型版本问题，而是上下文装错了。
下一篇：Context Engineering：Agent 到底该把什么放进上下文？
参考资料
- OpenAI：Evaluation best practices https://developers.openai.com/api/docs/guides/evaluation-best-practices
- OpenAI：Graders https://developers.openai.com/api/docs/guides/graders
- OpenAI Agents SDK：Tracing https://openai.github.io/openai-agents-js/guides/tracing/
- LangSmith：Evaluation https://docs.langchain.com/langsmith/evaluation
- Langfuse：Experiments API https://langfuse.com/docs/api-and-data-platform/features/experiments-api