Agent 评测与可观测性

普通生成任务常只评价最终文本；Agent 还必须评价过程。同一个正确结果，可能来自一次精准调用，也可能来自二十次碰撞、越权尝试后侥幸成功。只看终点会奖励危险和昂贵的轨迹。

1. 定义任务成功

每个任务样本至少包含：初始环境、目标、可用工具、验收器、禁止动作和预算。

{
  "id": "repo-fix-017",
  "goal": "修复日期解析回归",
  "initial_snapshot": "fixture:v12",
  "acceptance": ["targeted_tests_pass", "typecheck_pass", "no_unrelated_diff"],
  "forbidden": ["disable_test", "network_access"],
  "budget": { "max_steps": 12, "max_cost": 0.8 }
}

验收尽量在隔离环境中由代码执行。模型自己说“测试已通过”不是测试证据。

2. 结果、轨迹与效率三层指标

2.1 结果指标

任务成功率、部分完成率、验收项通过率、安全违规率、人工接管后的成功率。

2.2 轨迹指标

工具选择正确率、参数有效率、重复动作率、无效重规划次数、危险动作拦截率、关键结论证据覆盖率。轨迹不要求与专家路径完全相同，但必须满足不变量。

2.3 效率指标

每成功任务的 Token、费用、步骤数、P50/P95 时长，以及失败任务浪费的费用。用“每成功任务成本”比“每次调用均价”更能反映系统价值。

3. 事件与 Span 设计

一次 Run 对应一条 Trace，每个模型、检索、工具、审批和校验动作对应 Span：

run: repo-fix-017
├─ context.build
├─ model.choose_action
├─ tool.read_file
├─ model.choose_action
├─ tool.apply_patch
├─ tool.run_tests
├─ verifier.diff_scope
└─ run.finish

每个 Span 记录：run_id、step、父节点、开始结束时间、组件版本、输入输出摘要、Token/费用、状态、错误码和重试次数。提示词正文与工具结果可能含秘密，应分级存储并设置保留周期，不能为了可观测性制造新的泄露面。

4. 建立稳定的故障分类

建议从以下顶层开始：

类别	表现	责任层
意图错误	理解错目标或验收	上下文 / 模型
规划错误	步骤缺失、顺序错误、循环	模型 / 状态机
工具选择错误	选错工具或没调用必要工具	工具描述 / 模型
参数错误	Schema 或业务参数非法	工具接口 / 模型
执行错误	超时、外部服务失败	运行时 / 依赖
观察错误	忽略或误读工具结果	上下文 / 模型
验收错误	错把未完成当完成	验收器 / 模型
策略违规	越权、未审批写入	权限 / 运行时

稳定错误码能回答“本周成功率下降是模型选择变差，还是外部工具超时”，避免所有失败都归因于模型。

5. 离线评测方法

5.1 可重放环境

代码任务使用固定仓库快照和容器；浏览器任务使用测试站点与固定数据；业务任务用沙箱 API。外部时间、随机数据和真实账户会让结果不可复现。

5.2 多次运行看分布

Agent 路径具有随机性。关键样本至少运行多次，报告成功率分布与尾部成本，而不是只展示最好的一次。模型或提示词版本比较时使用相同快照和预算。

5.3 故障注入

主动制造工具超时、429、返回空列表、部分写入、格式变化和权限拒绝，验证 Agent 是否分类错误、遵守预算并安全恢复。顺利路径通过不代表系统可靠。

6. 轨迹评分避免两个极端

不能要求 Agent 完全复制标准轨迹，因为可能存在多条正确路径；也不能只看最终状态。更合适的是定义轨迹不变量：

• 写入前必须读取当前版本；
• 高风险动作前必须有有效审批；
• 测试失败后不能宣称成功；
• 不得访问范围外资源；
• 相同失败不得无上限重试。

其余步骤允许自由，只对成本与冗余施加软评分。

7. 线上仪表盘与告警

至少分任务类型展示：成功率、人工接管率、P95 时长、每成功任务成本、工具错误率、预算耗尽率、安全拦截和用户撤销率。按模型、提示版本、工具版本、租户和任务难度切片。

告警应对应可行动问题：某工具 PERMISSION_DENIED 激增、P95 步数翻倍、验收失败但 Agent 报成功、单任务费用越过硬上限。单纯 Token 总量上升可能只是流量增长，信息不足。

8. 从一次失败到永久改进

1. 用 run_id 重建时间线；
2. 找到第一个偏离正确路径的 Span，而不是只看最后报错；
3. 判断属于数据、上下文、模型、工具、运行时还是验收；
4. 把脱敏后的案例加入对应组件评测；
5. 做最小修改并运行全量回归；
6. 灰度发布，观察同类错误是否下降。

没有进入评测集的事故，很容易在下一次模型、提示词或工具升级后复发。