什么是 Harness
Agent 的“操作系统”：上下文、工具、权限、沙箱、重试与追踪。
一句话理解：模型只负责“想下一步做什么”，Harness 负责其余一切：把信息喂给模型、真正执行工具、拦住不该做的事、记住做到哪、出错后接着跑，并把全过程记录下来。
很多团队第一次做 Agent，会把精力全部花在“选哪个模型”和“Prompt 怎么写”上，然后发现 Demo 很惊艳，一上真实业务就频繁翻车：工具报错后整个任务卡死、跑到第 30 步上下文爆了、误删了不该删的文件、用户关掉页面后任务就没了。这些问题几乎都不是模型的问题，而是 模型外面那套运行系统 的问题。
这套运行系统就叫 Harness（直译是“马具、挽具”：让一匹马的力气真正变成拉车的力气）。导论里的 模型与 Harness 已经给出了直觉，这一课把它展开成一个可以画图、可以评审、可以和研发讨论的概念。
模型与 Harness：发动机和整车
把模型比作发动机，Harness 就是变速箱、刹车、方向盘、仪表盘和行车记录仪的总和。同一台发动机，装进赛车和装进卡车，开起来完全是两种体验。
| 问题 | 模型能回答吗 | 谁来负责 |
|---|---|---|
| 下一步该调哪个工具、填什么参数？ | 能 | 模型 |
| 工具真的被执行了吗？执行结果是什么？ | 不能，模型只输出“调用请求” | Harness 的工具执行层 |
| 这一步本次对话里该让模型看到哪些信息？ | 不能 | Harness 的上下文管理 |
| 这个操作允许自动执行吗？要不要问人？ | 只能“建议” | Harness 的权限与策略 |
| 跑到一半进程挂了，从哪里继续？ | 不能 | Harness 的状态与恢复 |
| 这次任务花了多少钱、为什么这么做？ | 不能 | Harness 的追踪与计量 |
关键认知：模型的输出只是文本（包括结构化的工具调用请求），把文本变成现实世界里的动作，完全是 Harness 的事。 这也是为什么同一个模型放进不同产品，可靠性可以差一个数量级。
一次任务穿过 Harness 的全过程
以 Coding Agent 修一个失败的测试为例，看看每一步分别是谁在干活：
十二步里，模型真正参与的只有“决定下一步”的那几次。其余的装配、执行、拦截、记录、压缩、保存全部由 Harness 完成。第 11 步尤其值得注意：模型说“通过了”不代表真的通过了，可靠的 Harness 会用程序再确认一遍（详见 为什么必须验证）。
Harness 负责的八件事
下一课「Harness 的组件」会逐个拆解，这里先建立全景：
下面这张全景图把模型放在中心，六个环节围成一次 Agent Loop，贯穿全程的能力列在底部：
| 职责 | 要解决的问题 | 订单售后诊断 Agent 里的样子 |
|---|---|---|
| 循环控制 | 什么时候继续、什么时候停 | 最多 15 步；连续 3 次查询同一订单视为打转 |
| 工具执行 | 把调用请求变成真实的 API 调用 | 调用订单系统、支付系统、工单系统 |
| 上下文管理 | 每一步给模型看什么、看多少 | 订单操作记录只保留最近 20 条；旧工具结果被清理 |
| 权限与护栏 | 能不能做、要不要问人 | 查询自动执行；改订单状态必须人工确认 |
| 执行环境 | 代码和命令在哪里跑 | 数据分析脚本在隔离沙箱里执行 |
| 状态与会话 | 记住做到哪、能否续跑 | 批量处理 200 个订单，第 87 个失败后从 87 继续 |
| 错误恢复 | 工具失败、做到一半怎么办 | 支付接口超时重试两次，仍失败则标记待人工 |
| 可观测性 | 事后能解释、能算账 | 每次运行记录每步工具调用、Token 与成本 |
买还是建：四种获得 Harness 的方式
以 Anthropic 的产品线为例（其他厂商也有类似分层），获得 Harness 的方式大致有四档，区别在于“谁写循环”和“谁负责部署”：
| 方式 | 你需要写什么 | Harness 由谁提供 | 适合 |
|---|---|---|---|
| 直接调用模型 API，自己写循环 | 全部 | 自己 | 想完全掌控、学习原理 |
| SDK 里的工具循环助手（如 Tool Runner） | 工具函数 | SDK 提供循环，部署归你 | 自定义业务工具的 Agent |
| 成品 Harness 库（如 Claude Agent SDK） | 提示词与配置 | SDK 提供完整 Harness（内置文件、命令、搜索等工具），部署归你 | 文件与代码类任务 |
| 托管 Agent 平台（如 Claude Managed Agents，目前为 Beta） | Agent 配置与事件处理 | 平台同时提供 Harness 与沙箱运行环境 | 长时间运行、异步任务 |
OpenAI Agents SDK、LangGraph 等框架处在这条光谱的不同位置，具体取舍见 框架与 SDK 选型。无论选哪档，都建议先亲手写一次最小循环（实操课），否则很难判断框架替你做了什么、没做什么。
薄 Harness 与厚 Harness
Harness 的“厚度”是一个设计选择：
- 厚 Harness：大量逻辑写死在程序里，例如固定先查订单、再查支付记录、再判断。可控、可预测，但模型的判断空间小，接近 Workflow。
- 薄 Harness：只提供工具、上下文、权限和循环，把“怎么做”交给模型。灵活，但更依赖模型能力和验证机制。
两种厚度的差别，以及始终不变的部分，可以画成这样：
一个常见的演进规律：模型能力提升后，原本用程序硬编码的步骤会逐渐交还给模型，而 权限、验证、状态、追踪这些“安全带”不会变薄，反而会变厚，因为 Agent 能做的事越多，出错的代价越大。
常见误区
- “换个更强的模型就好了。” 工具超时导致整个任务失败、上下文溢出、没有权限拦截，这些问题换模型解决不了。先看 Trace，定位问题出在模型决策还是 Harness。
- “Harness 就是一个 while 循环。” 循环是骨架，生产级 Harness 的大部分代码在权限、恢复、状态、上下文管理与追踪上。
- “用了框架就有了 Harness。” 框架提供的是零件和默认值，最大步数、审批点、失败策略、记忆边界这些产品决策仍然要你来做。
产品经理检查清单
评审一个 Agent 方案时，逐条问研发：
- 任务最多跑多少步、花多少钱？超限后用户看到什么？
- 哪些工具调用自动执行，哪些需要人确认？这个规则写在 Prompt 里还是程序里？
- 工具失败时是重试、换路径还是停下来找人？
- 用户关掉页面或服务重启后，任务还在吗？能从中断处继续吗？
- 每次运行能否回放：调了哪些工具、参数是什么、返回了什么、花了多少？
- 我们用的是自研循环、SDK 还是托管平台？哪些能力是它自带的，哪些要自己补？
练习
选一个你常用的 Agent 产品（Claude Code、Codex、ChatGPT Agent 等），用 30 分钟完成一张“Harness 拆解表”：
| 职责 | 产品里的具体表现 | 是否可配置 | 你的评价 |
|---|---|---|---|
| 循环控制 | 例：长任务会自动总结并继续 | ||
| 权限与护栏 | |||
| 状态与会话 | |||
| 错误恢复 | |||
| 可观测性 |
完成后写一句话：这个产品体验好（或不好）的主要原因，有多少来自模型、多少来自 Harness？
延伸阅读
- Building effective agents：Anthropic 关于 Workflow 与 Agent 的区分，以及“先直接用 API，再考虑框架”的建议。
- Agent SDK overview：把 Claude Code 的 Harness 作为库提供时，包含哪些能力。
- Claude Managed Agents overview：托管式 Harness 的核心概念（Agent、Environment、Session、Events）。
下一步
下一课「Harness 的组件」会把这八件事拆成具体模块，画出一张可以直接拿去和研发对齐的架构图。