Agent Harness 是什么？从执行循环到安全恢复

**Agent Harness 是模型外围的运行与控制系统。**它决定模型这一步能看到什么、可以调用哪些工具、工具在哪里执行、什么动作必须由人批准、进度怎样保存，以及失败后从哪里继续。

这也是它与「多写一段 Prompt」最根本的区别。模型能够提出下一步，却不会天然拥有文件系统、登录身份、审批策略、重试边界，也不知道某个外部动作是否已经执行。Harness 把连续的模型判断组织成一次受控、可追踪、可恢复的任务运行。

可以用一个替换实验来理解：保留模型，换掉外围系统，同一个模型可能从普通聊天助手变成编码 Agent 或持续工作的 Work Agent；保留外围系统，只换模型，文件、工具、审批、日志和任务状态依然存在。这套没有随模型一起消失的运行层，就是 Harness。

一次 Agent 运行究竟怎样向前推进

从系统视角看，Agent 不是「模型连续思考」，而是一组有边界的反馈循环：

1. **组装上下文：**载入目标、指令、相关资料、当前状态和可用工具；
2. **请求决策：**模型返回文字、工具调用、任务委派，或请求人工补充信息；
3. **检查权限：**Harness 核对身份、作用域、策略、预算和审批条件；
4. **执行动作：**在合适的环境中运行工具，并获取结构化结果；
5. **读取现实反馈：**把输出、错误、文件变化或外部系统状态交回下一轮；
6. **验证结果：**用测试、规则、外部状态或人工标准判断任务是否真的完成；
7. **保存或停止：**写入检查点，等待审批，正常完成，或者在超时、超预算时安全退出。

Anthropic 对 Agent 的工程解释也强调这个闭环：模型使用工具，根据环境反馈调整下一步，直到完成、遇到阻塞、需要人介入或触发停止条件。它同时提醒，Agent 的灵活性会增加延迟、成本和错误累积风险；路径明确时，固定 Workflow 甚至单次模型调用通常更合适（Anthropic：Building effective agents）。

所以 Harness 的职责不是把所有任务都变成自主 Agent，而是让系统以适合当前任务的方式运行。

架构的三条边界：控制、执行与状态

理解 Harness，最有用的办法不是背组件名单，而是看三类职责是否分得清楚。

OpenAI 的 Sandbox 架构明确区分了前两层：Agent Runtime 负责模型、工具、审批、追踪与恢复，Sandbox 则提供隔离的文件和命令环境（OpenAI：Sandbox Agents）。状态面同样不能省略。聊天历史、可恢复的任务状态、用户记忆和最终交付物，各自有不同的保存、更新和删除周期。

上下文管理不是比谁的窗口更长

一次模型调用可能需要系统指令、用户目标、项目规则、检索文档、工具定义、最近的执行结果，以及一份压缩后的进度记录。Harness 决定哪些内容在这一轮出现，哪些内容应该暂时留在外部。

无差别塞入更多文字会制造三个问题：无关历史挤占注意力，过度摘要丢掉硬约束，旧缓存覆盖当前文件。因此，成熟的上下文策略至少应做到：

• 把不可变指令和外部网页、邮件等不可信内容区分开；
• 让当前权威文件优先于历史摘要；
• 压缩长记录时保留已经作出的决定、未解决问题和失败证据；
• 只在需要时加载工具说明和专业 Skills；
• 把审批结果、文件哈希、任务 ID 等必须精确的状态结构化保存。

这里也能看出「记忆」一词为何经常造成混乱。会话记忆用于接着聊天，任务状态用于恢复执行，长期记忆保存可复用事实或偏好，Artifact 才是实际交付物。四者混在一段对话里，修正、删除、审计都会变得困难。

工具是可验证的契约，不是能力魔法

每个工具都应有清楚的名称、用途、参数、返回值、错误行为和执行身份。Harness 把这些信息呈现给模型，校验模型提交的参数，再调用真正的实现，并把结果作为环境反馈送回循环。

工具设计差，模型再强也只能猜。参数含糊、多个工具职责重叠、失败时只返回一句自然语言，都会让后续判断失去依据。Anthropic 曾披露，他们在编码 Agent 中发现模型会因工作目录变化而使用错误的相对路径；把工具改为强制绝对路径后，问题才被消除。这不是换模型或堆 Prompt，而是改进 Agent 与计算机之间的接口（Anthropic：工具设计说明）。

Agent Connector 可以向 Harness 提供 SaaS 数据与动作；Shell、浏览器、文件编辑器等原生工具则可能直接作用于执行环境。Harness 必须保留这种差别：读取本地草稿与使用企业账号发信，执行身份和后果完全不同。

Sandbox 约束执行范围，但不能代替授权

Sandbox 可以限制进程、目录、依赖、网络目标、运行时间和持久卷，使代码执行的影响范围更小，也让任务结束后的文件变化可供检查。

不过，隔离环境并不能回答「这个动作是否应该发生」。一个进程即使被严密隔离，仍可能通过远程 API 发错邮件；一次只读的本地分析则未必需要容器。Harness 应按照工具与风险选择隔离方式，并把密钥、审批规则、费用限制和审计记录放在模型无法直接改写的位置。

外部集成也不能只看 OAuth Scope。Model Context Protocol 的安全建议明确反对 Token Passthrough，并要求验证 Token、划清授权边界、避免 Confused Deputy 等问题（MCP 安全最佳实践）。最终仍要由 Harness 约束当前运行可以代表哪位用户、访问哪个租户和资源、执行什么动作。

审批不是弹窗，而是一种可恢复状态

合理的审批策略从后果出发。查看公开资料、修改临时草稿、更新生产数据库、正式发布文章和付款，不应该套用同一种确认规则。

判断一个动作是否需要审批，可以依次看六件事：

• **能否撤销：**错误发生后能不能完整恢复？
• **影响范围：**只改一份文件，还是影响整个组织？
• **外部可见性：**结果留在私有工作区，还是会发给客户或公开发布？
• **执行身份：**使用谁的账号、权限和凭据？
• **成本：**是否消耗大量 Token、云资源、API 费用或真实资金？
• **验证条件：**执行前后能否用确定性规则检查？

低风险读取可以按策略自动放行；受限目录里的草稿修改可以先执行、后审查；发送、发布、删除、采购或生产变更通常应跨过更强的人工边界。

真正的难点在运行状态：系统必须在工具产生副作用之前暂停，保存足够的信息，记录审批决定，并在进程重启后继续，同时不能重放已经成功的前置动作。OpenAI Agents SDK 的 Human-in-the-loop 机制就是这种模型：需要批准的工具产生 interruption，RunState 可以序列化保存，批准或拒绝后再恢复原来的运行（OpenAI：Human-in-the-loop）。

只有参与这套状态机，审批才是 Harness 能力；否则它只是界面上的「确定」按钮。

可观测性要能回答「为什么会这样」

普通应用日志很难解释 Agent 为什么得出错误结果。一次可审计的运行至少应能串起这些信息：

• 模型实际收到的指令与上下文版本；
• 每轮使用的模型与运行参数；
• 工具名称、校验后的参数、执行身份和返回结果；
• 审批请求以及最终决定；
• Handoff 或 Subagent 的边界；
• 交付物变化与验证结果；
• 延迟、Token、工具费用、重试次数和停止原因。

这些事件需要共享 Run ID 或 Trace ID。OpenAI Agents SDK 会记录模型生成、工具调用、Handoff、Guardrail 和自定义事件，同时允许控制敏感输入输出是否写入 Trace（OpenAI Agents SDK：Tracing）。后一点尤其重要：如果原样导出 Prompt、客户资料或凭据，可观测系统本身就会成为新的泄露面。

同一套事件通常服务三类人。用户想看到容易理解的操作记录；运维人员需要关联错误与资源消耗；评估人员需要复现运行并标注结果。底层数据可以连通，但展示范围与保留期限不应完全相同。

失败恢复不能简化成「再试一次」

不同失败需要不同处理：

盲目重试搜索通常问题不大，盲目重试「创建发票」「发送邮件」或「合并分支」却可能造成重复副作用。Harness 需要在这类边界使用幂等键、执行前置条件、补偿动作，或重新交给人判断。

长任务还需要专门的检查点。它不必保存所有聊天文字，但至少要记录目标、已完成步骤、待执行动作、关键观察、交付物位置、审批状态，以及本次使用的指令和工具版本。OpenAI 的 Runner 文档把 Temporal、Dapr、Restate 与 DBOS 等 Durable Execution 集成用于跨重启、长时间等待和人工审批；RunState 则提供可序列化的中断恢复边界（Running agents、Run state）。

Harness、Model、Framework、Workflow、Connector 与 Workspace

这些词在营销页面中经常混用，但它们解决的不是同一个问题。

Framework 可以用来搭建 Harness；Harness 既能运行固定 Workflow，也能运行开放式 Agent；Workspace 可能内置 Harness，也可能连接远程运行服务。把它们分开，最大的价值不是术语准确，而是故障发生时知道应该查哪一层。

本地优先与云端 Agent 工作站讨论的是状态和执行发生在哪里；Harness 讨论的则是无论它们在哪里，运行如何被控制。

哪些任务值得使用 Harness

Harness 适合步骤数量不固定、需要真实工具、会被中断、存在外部副作用，或结果可以独立验证的工作。

跨文件的软件修改

Agent 可以检查仓库、在隔离环境里改文件、运行测试、读取失败并继续修改。Harness 在这里承担仓库规则、命令权限、Diff 记录、任务检查点，以及 Push 或 Merge 前的人工审查。自动测试提供了明确的环境反馈，但最终还要由人确认改动是否符合产品目的。

有证据链的研究与文档生产

系统可以收集一手来源、保存出处、起草文档、检查必需章节，并在事实缺口会改变结论时暂停。关键能力不是单纯「能够上网」，而是让每项主张找到来源，并且把未解决问题和已完成文字清楚分开。

跨业务系统的运营任务

Agent 可能读取工单、查询账号资料、草拟处理方案，再更新外部系统。在这里，委托身份、最小权限、敏感字段处理、对外动作审批和审计记录，往往比复杂的自主规划更重要。

反过来，简单分类、摘要和确定性格式转换通常不需要完整 Harness。单次模型调用或固定 Workflow 更容易测试，成本也更可控。「Agent 化」应该来自任务需要，而不是为了凑功能。

选型或验收时，现场做这七项测试

演示视频通常只展示成功路径。真正评估 Harness，应选择一项有代表性的任务，并主动制造中断与错误。

1. 看清执行循环

能否辨认规划、工具调用、结果验证、人工求助和停止分别发生在什么时候？系统是否有轮次、时长与预算上限，而不是无限循环？

2. 检查上下文纪律

任务开始后修改一份权威文件，观察系统是否仍按旧摘要工作。询问本轮用了哪些指令和证据，再测试网页或邮件里的恶意文本能否伪装成系统规则。

3. 验证最小权限

只给读取权限，再要求 Agent 修改内容。继续检查目录边界、租户边界、网络范围和凭据。聊天中说「我不能」不算通过，限制必须由工具层真正执行。

4. 在高风险动作前打断

让运行停在发送、发布、删除或付款之前。重启进程，拒绝这项动作，再确认系统既没有偷偷执行，也没有重复前面的副作用。

5. 制造部分失败

让工具在外部服务已经接收请求后超时。合格系统会检查外部状态或幂等键，再决定是否重试，并说明它是修复、回滚还是停止。

6. 复查 Trace 与交付物

最终结果能否追溯到模型轮次、工具调用、审批和验证？敏感字段能否脱敏？导出交付物时，是否可以不连带导出私人 Trace？

7. 衡量任务结果

关注完成率、验证正确率、人工介入次数、危险动作拦截率、恢复成功率、耗时和总成本。工具调用次数和 Token 数只能说明系统很忙，不能证明它完成了有价值的工作。

三个一票否决的架构信号

**聊天记录就是全部状态。**进程重启后审批结果丢失，或者旧动作重新执行，说明它只有会话历史，没有可恢复执行。

**让模型自己执行安全策略。**Prompt 里写「不要访问生产环境」只是提示，不是权限控制。真正的边界必须落在工具网关、身份层、Sandbox 或审批服务中。

**没有独立验证器。**让同一个循环自己判断「已经成功」，远弱于运行测试、检查 Schema、对比文件 Diff、读取 API 实际状态或由人验收。Harness 应优先相信环境事实，而不是模型的自信表达。

关键不在于让 Agent 看起来更忙

Agent Harness 的价值，是把模型行为变成可治理、可解释、可恢复的运行。模型提出动作；Harness 提供上下文，调度工具，执行权限边界，记录真实影响，验证结果，并留下足以安全继续的状态。

因此，同一个模型在不同 Harness 中会有完全不同的可靠性。更强的模型放进薄弱运行层，仍可能使用过期上下文、越过权限或重复副作用。好的 Harness 也无法消除模型错误，但它能让错误被看见、被限制、能够修复——这正是演示型 Agent 与可承担真实工作的系统之间的分界线。