[!info] related notes

• 所属 MOC: Agent Evals MOC, Testing MOC, AI MOC
• 相关概念: Monorepo 测试架构, AI 编码时代的 TDD, Monorepo 测试中的共享质量资产, Agent 中的 Ground Truth Feedback, Agent Guardrails
• 相关资源: OpenAI Codex

Agent 测试与评估

范围

这篇笔记讨论的是 AI agent 的测试体系，而不是传统服务的单元测试。

为什么要把这些内容放在一起理解

agent 的风险不只是“代码错了”，还包括：

• 路由漂移
• 工具选择错误
• prompt 改动后的行为漂移
• guardrail 失效
• 模型升级后质量波动

如果只靠人工聊一聊试一试，这类问题几乎无法稳定比较和回归。

agent 测试的五层

1. deterministic unit

这层最好尽量结构化，典型对象包括：

• prompt rendering
• tool schema
• parser
• policy filter
• router output

如果 router / planner 输出可以被约束成严格 JSON，断言会比自然语言字符串稳定很多。

2. stubbed workflow tests

固定工具返回，验证：

• 路由是否正确
• 多步流程是否按预期推进
• 失败分支是否被正确处理

这层比真实模型评估更快，也更适合高频运行。

3. trace grading

在 agent 调试期，最值钱的是看真实 trace：

• 工具选择是否合理
• handoff 是否正确
• guardrail 是否触发
• 哪里开始偏航

trace 让问题不再只体现在最终一句错误回复上。

4. dataset evals

当流程稳定后，就应该把代表性场景固化成数据集：

• 输入
• 上下文
• 预期行为
• graders / thresholds

这样每次改 prompts、models、tools、policies 时都能做版本对比。

5. shadow / canary

上线阶段还需要：

• shadow traffic
• 小流量 canary
• prompt / model diff eval

因为很多非确定性问题只有在真实分布下才会暴露。

agent 测试和传统测试最大的不同

传统服务更强调编译、接口、状态和确定性输出；agent 还必须额外处理：

• 非确定性
• 数据分布变化
• 模型版本变化
• prompt 演化

所以 agent 的“测试”天然更接近“测试 + 评估 + 运行期观察”的组合。

evals 为什么必须版本化

如果 prompt、tool schema、grader、阈值和基线结果不版本化，团队就很难回答：

• 这次行为为什么变了
• 变好还是变坏
• 回滚后为什么还回不到原来

这也是为什么 packages/evals 应该成为一等公民。

一个实用工作流

1. 调试期先看 traces
2. 把稳定问题收进 deterministic tests
3. 把关键场景固化成 dataset evals
4. 发布期做 shadow / canary
5. 把生产反馈继续回流成新样本

最短记忆方式

agent 质量体系不是“多跑几次聊天”，而是 deterministic tests + traces + datasets + rollout checks 的组合。

学习检查

不看正文回答：

1. deterministic test、stubbed workflow test、trace grading、dataset eval、shadow/canary 分别覆盖哪一层风险？
2. 为什么 Agent quality 不能只靠“多跑几次聊天看看”？
3. 非确定性为什么让 pass/fail test 不足以覆盖全部 Agent 行为？
4. Eval dataset 为什么必须版本化并保留 provenance？
5. grader、threshold、prompt、tool schema、model version 为什么都可能改变 eval 结果？
6. trace grading 与最终输出 grading 分别能发现什么不同问题？
7. production failure 应怎样回流成 deterministic regression test 或 dataset sample？
8. 给一个 coding agent release，设计从 unit → trace → dataset → canary 的质量门禁。

参考资料

• https://developers.openai.com/api/docs/guides/agent-evals
• https://developers.openai.com/api/docs/guides/evaluation-best-practices
• https://platform.openai.com/docs/api-reference/evals

Related notes

• Agent MOC
• Agentic Systems
• Agent 执行闭环