从回答问题到完成任务

假设你要做一个资料整理助手：读取指定文件夹里的会议记录，找出尚未完成的事项，再生成一份汇总。

调用一次模型，可以得到整理思路。但真正执行时，还需要读取文件、接收结果、决定是否继续查找，并在信息足够时交付。Agent 的运行通常包含这样的循环：模型决定下一步，程序执行工具，再把结果交给模型。(openai.com)

负责组织这一过程的运行支撑，就是本文讨论的 Agent Harness。

Harness 管理什么

可以把 Harness 理解为包围模型的一层程序设施。模型根据输入提出行动，Harness 组织模型调用、分发工具请求，并维护运行所需的状态。它与模型配合，构成可以持续工作的系统。(anthropic.com)

为了方便入门，我们把它拆成四个问题：

  • 循环：下一轮什么时候开始，工具结果怎样返回？
  • 上下文：这一轮应该让模型看到什么？
  • 权限：模型提出的操作是否允许执行？
  • 结束判断：什么时候完成，什么时候暂停或失败？

写第一个项目时，可以先围绕这四个问题设计一个简单的控制器，再按实际需要增加能力。

为什么需要这层支撑

长任务会暴露出单次调用不明显的问题。例如，上下文窗口有限，跨会话继续工作时，需要重新提供进度；模型也可能看到部分成果，就过早宣布任务完成。仅靠压缩对话，未必能解决这些问题。(anthropic.com)

因此，建议把“任务如何运行”明确写进程序：保存完成状态，限制可执行操作，检查交付结果。提示词负责表达目标，运行逻辑负责落实约束。

四个部分如何配合

循环：让行动接上结果

一轮基本流程是：组装输入，调用模型，检查输出；如果包含工具请求，就执行工具并回传结果；如果产生最终答案，就进入结束处理。运行还需要设置轮数等限制，避免无限继续。(openai.com)

实现时，建议为每次工具调用记录名称、参数、结果和错误。工具失败后，也要把失败作为明确结果处理，而不是让模型误以为操作已经成功。

第一版可以采用串行执行：每次处理一个动作，确认结果后再继续，便于观察和调试。

上下文：提供继续工作所需的信息

上下文窗口有容量限制，长期任务需要通过进度记录、文件等方式，在不同会话之间衔接工作。压缩历史可以节省空间，但不能保证所有重要信息都完整保留。(anthropic.com)

建议把信息分成两类：

  • 当前输入：目标、约束、近期动作和必要的工具结果。
  • 持久状态：已处理文件、已确认事实、未解决事项及证据位置。

每一轮从持久状态里取出相关内容。摘要中保留文件名、关键结论和待办项，原始材料则单独保存，方便回查。

权限：在执行之前检查

权限检查应放在实际执行工具的边界。对于需要人工确认的操作，运行系统可以先暂停，保存状态，收到批准或拒绝后再继续。(developers.openai.com)

在资料整理助手中，可以规定：只读指定目录，只能向一个输出目录写文件，不能删除原始记录。每次收到工具请求，都校验工具名称、参数和目标路径。

如果以后增加“发送汇总邮件”，再为这个动作加入确认步骤。界面应展示实际收件人和内容，让批准对应一项具体操作。

结束判断：区分停止与成功

运行可能因为最终输出而结束，也可能因为轮数耗尽、工具错误而停止；等待人工批准则属于暂停，需要保留可恢复的状态。(developers.openai.com)

建议设置四种结果：成功、等待确认、失败、达到限制。成功还要通过任务验收。例如，资料整理任务应检查目标文件是否全部处理、汇总是否生成，以及每条待办是否有出处。

小例子：整理三份会议记录

下面设计一个最小版本。输入限定为三份文件，输出是一份待办汇总，只提供读取文件和保存汇总两个工具。

开始时，程序建立状态：三份文件均未处理，汇总尚未生成。模型先请求读取第一份文件；程序检查路径，读取成功后，将内容交回模型，并记录读取结果。

后续轮次继续处理剩余文件。提取出的每条待办，都附上文件名和原文位置。没有写明负责人的事项，标记为“未明确”，不自行补全。

当模型请求保存汇总时，程序检查输出路径并执行写入。模型随后提出完成，程序再验收：三份文件是否都已处理，汇总是否存在，条目是否包含出处。

如果其中一份始终读取失败，就返回“部分完成”及失败原因，不能把两份文件的结果包装成完整交付。

这个例子中，内容理解交给模型，执行范围、进度记录和验收条件由程序维护。

常见坑与改进顺序

调试时，可以优先排查三种设计：

只看最终回答。 建议保留逐轮日志，能够追查模型提出了什么、程序执行了什么、工具实际返回了什么。

所有错误都重试。 建议区分临时故障、参数错误和权限拒绝，分别处理，并为重试设置上限。

只检查文件是否存在。 建议同时检查必需字段、材料覆盖情况和证据位置。格式通过后，内容质量仍可安排人工抽查。

第一版不必追求复杂架构。先用少量工具跑通一个范围明确的任务，再针对失败记录改进。

小结

理解 Agent Harness，可以从四个设计问题开始：如何推进循环，如何准备上下文，如何检查权限，如何判断结束。

做入门项目时，建议先写清可执行动作、状态结构和验收条件，再接入模型。这样，每一步都能观察，每次停止都有原因，也更容易判断下一次改进应该落在哪里。

参考来源