Agent harness
Agent harness 是包在 AI 模型外面的运行时层。它决定模型能看到什么上下文、能调用哪些工具、权限怎么控制、记忆放在哪里，以及出错后怎么恢复。
不要把 harness 当成普通胶水代码。对编码 Agent 和工作流 Agent 来说，harness 经常比“换一个更强模型”更直接地影响可靠性。
一个好用的理解框架
好的 Agent 系统会把不适合只放在模型权重里的能力外化出来。
| 层级 | 外化什么 | 例子 |
|---|
| 记忆 | 持久状态与检索 | 项目笔记、用户偏好、任务历史、向量检索 |
| 技能 | 可复用流程 | 浏览器控制、代码审查、图片生成、部署 helper |
| 协议 | 通信契约 | MCP、JSON schema、类型化工具返回、错误格式 |
| Harness | 运行时协调 | 上下文组装、工具路由、审批、日志、重试、评测 |
哪些能力应该继续留在模型内部，哪些能力应该变成明确的外部组件？
如果这个能力会影响可靠性、可审计性、复用性或成本，通常就值得外化。
Harness 负责什么
Harness 至少应该把这些决策显式化：
- 哪些文件、页面、工具和记忆进入上下文
- 旧上下文什么时候总结、丢弃或保留
- 工具调用在执行前怎么校验
- 哪些动作必须经过用户审批
- 工具错误怎么表示、怎么重试
- 推理强度、延迟和成本怎么权衡
- 每次运行怎么记录，方便之后排查
薄 harness 可以成立，但隐式 harness 很难排错。行为变差时，如果分不清原因是模型、提示词、上下文缓存、工具层还是产品默认值，说明 harness 的可观测性不够。
设计原则
工具要小而清楚
优先设计输入输出明确的小工具。一个工具只做一件事，模型更容易正确调用，人也更容易审查。
本地工作流里，CLI 往往够用。需要跨客户端复用时，再考虑 MCP 这样的协议边界。稳定产品后端则继续用直接 API，通常最简单。
保留影响推理的上下文
上下文裁剪不只是省 token 的优化，它会改变行为。
如果 Agent 前面基于某段推理调用了工具或修改了文件，harness 就必须保留足够的原因链。否则后续轮次可能重复执行、忘记为什么选这条路，或者调用奇怪的工具。
让推理强度可见
推理强度不只是模型参数，也是产品决策。降低强度可以减少延迟和 token，但也可能让复杂编码任务明显变差。
要让用户看见当前 effort 级别，方便切换，并避免在复杂工作流里静默修改默认值。
把 system prompt 当代码审查
System prompt 的改动可能和代码改动一样影响质量。处理它时也应该有工程纪律：
- 跑分模型评测
- 用 ablation 检查单条指令的影响
- 灰度发布
- 保留变更记录
- 模型专用指令只作用到目标模型
对编码 Agent 来说，过强的“少说话”约束尤其危险。它可能减少工具调用之间必要的计划和验证。
测试真实公开版本
内部版本可能掩盖线上问题。应该 dogfood 用户真正运行的公开版本、公开默认值和公开上下文行为。
对代码审查或编码 Agent 评测来说，还要给足真实任务需要的仓库和文件上下文。缺少跨仓库上下文时，模型明明有能力找出问题，评测里也可能看不到。
常见故障模式
Anthropic 在 2026 年 4 月发布的 Claude Code 质量问题复盘很有参考价值：用户感知到的退化来自产品和 harness 改动，而不是底层 API 模型退化。
常见故障包括：
- 默认推理强度回退：为了降低延迟改默认值，可能让复杂任务显得“不聪明”。
- 上下文缓存 bug：错误地清理 reasoning history，会让 Agent 健忘、重复、工具选择异常。
- 提示词过度限长：笼统的短回答约束可能降低编码质量。
- 评测盲区：内部评测通过，不代表真实用户工作流没问题。
- 版本不一致：内部 dogfood 的 harness 和用户运行的 harness 不一致。
实用结论是：Agent 变差时，要排查整个运行时，而不是只怀疑模型。
快速排查清单
当 Agent 表现异常时，按这个顺序问：
- 模型或 effort 级别变了吗？
- System prompt、工具描述或 skill 指令变了吗？
- 上下文裁剪、总结或缓存策略变了吗？
- 工具 schema 或返回格式变了吗？
- Agent 拿到的文件和仓库上下文和以前一样吗？
- 用户运行的 harness 版本和内部评测版本一样吗？
- 日志里是否出现重复工具调用、缺少原因链、无新增信息的重试？
这能把模型退化和 harness 退化分开看。
什么时候值得投入更强的 harness
一开始可以简单。等任务变得重复、高风险或高成本，再加结构。
这些情况值得认真做 harness：
- Agent 会修改代码或生产数据
- 多个工具需要共享状态
- 用户会恢复长会话
- 审批和审计日志很重要
- 同一套流程要给团队多人使用
- 需要比较不同模型版本下的行为
如果只是一次性、低风险任务，一个提示词加几个工具就够了。只要任务开始变成长时间、带状态、可复用的工作流，就应该尽早设计 harness。
参考资料
Last modified on April 27, 2026
