Harness：Agent 的执行与反馈

Harness 是模型外部的运行程序，负责组织模型调用、工具执行和结果反馈，让 Agent 持续执行任务。

模型提出操作请求，Harness 调用工具执行，把结果放进下一轮输入，再次调用模型。模型根据新的结果调整判断，任务就这样逐轮推进。

1. Agent 执行循环

如果模型只提供文字建议，就需要用户自行修改代码、运行测试。测试失败时，用户还要把错误信息发给模型，供它继续排查。

接入 Harness 后，这些动作可以由程序连续组织起来。下面是一段简化的修复示例：

任务：购物车为空时，总价应该返回 0，当前程序却报错。项目已有相关代码和测试，本次要求保留原接口。

1. 查看代码。 Harness 把任务要求和可用工具说明交给模型。模型请求读取总价计算函数，Harness 调用文件工具，并把读到的代码交回模型。
2. 定位问题。 模型发现代码直接读取了第一个商品，没有处理空购物车。它请求运行空购物车测试，Harness 调用测试工具，得到“预期返回 0，实际发生越界错误”。
3. 修改文件。 Harness 把报错加入下一轮输入。模型据此提出补上空购物车分支，并发出修改请求；Harness 调用写入工具，文件才发生变化。
4. 检查修改。 写入结果交回模型后，模型请求运行相关测试。Harness 调用测试工具，把结果交回模型；模型看到空购物车和普通购物车的测试都通过，提交修改说明。

这段过程需要多次模型调用。代码、报错和测试结果陆续进入模型的输入，模型才有依据选择后续动作。Harness 负责执行请求，并将结果交回模型。

这种反复“调用模型 → 执行工具 → 返回结果”的过程，称为 Agent Loop（Agent 执行循环）。Harness 负责驱动这个循环；Anthropic 对 Harness 的定义也直接强调了调用模型和转交工具请求这两件事。

如果测试仍然失败，新的报错进入下一轮输入，模型就有机会调整修改。遇到需要用户授权的操作，或者达到约定的运行上限，Harness 则暂停或停止。本次运行停下，可能意味着完成，也可能意味着暂时无法继续。

2. 模型、工具与 Harness 的分工

在上面的修复过程中，三者承担的工作不同：

Agent 是执行任务的整体：模型、Harness、工具，以及它们使用的任务配置和工作环境共同参与。 这些是职责上的区分，不要求每一部分都部署成独立程序。

模型选择“接下来检查哪个函数”，Harness 按程序规则处理“这个工具能否调用、结果放在哪里、是否继续运行”。同一个模型接上不同的工具和运行规则，能完成的任务就会不同。

模型选择动作的方法中，ReAct 强调推理与行动交替进行：模型分析已有信息，提出动作请求，根据行动结果调整后续判断。ReAct 描述模型采取行动的方式，Harness 是组织实际执行的程序，两者不能画等号。

Harness 并不要求所有动作都由模型选择。每次修改后运行指定检查，就能写成固定流程，由程序自动执行。

3. Harness 的运行设计

有了执行与反馈的循环，Agent 就能连续推进任务。任务变长、工具变多以后，还会遇到资料不全、操作越权、中断丢进度、结果不达标等问题。

Harness Engineering 就是设计和改进 Agent 的运行机制。 除了驱动执行循环，还要准备上下文、接入工具、控制权限、保存进度，并安排结果检查。项目文档和测试环境也需要接入相应流程。

这些能力可以由现成的 Agent 运行框架提供，再接入项目自己的资料和流程；不必重写已有的文件工具、测试系统或审查平台。

3.1 上下文管理

模型在一次调用中能直接使用的是本轮输入，也就是当前上下文。任务要求、工具说明、读到的代码、近期测试结果，都可能放在里面。

Harness 将所需资料放入输入，或提供工具读取入口。文档写入文件以后，还要读入上下文，模型才能在本次调用中使用它。

实际组织资料时，可以让 AGENTS.md 这样的入口文件保留少量常用规则，并指向业务说明、架构文档和测试入口。详细内容按当前任务读取，避免每轮都夹带整份项目资料。

修复空购物车时，模型需要总价计算代码、返回值约定和相关测试。部署手册里的服务器配置通常帮不上忙。测试失败后，提供失败用例、预期值和报错位置，往往比塞入整份构建日志更便于定位；完整日志保留下来，信息不足时继续读取。

上下文过长时可以压缩成摘要，但摘要会丢失细节。重要规则、原始文件和完整执行记录应有可回查的位置，不能只留下压缩后的几句话。

3.2 工具接入与权限

模型要生成工具请求，需要知道工具的用途、参数和返回结果。它按约定格式输出工具名称和参数，Harness 据此找到对应的函数或服务，传入参数并接收结果。

接入工具时，Harness 可以直接调用本地函数，或通过 MCP 连接工具服务。

MCP（Model Context Protocol，模型上下文协议） 是应用连接工具和数据源的统一协议，规定双方如何通信。

工具应贴合 Agent 的职责。修代码需要读取、修改和测试能力；工具名称相近、用途重叠，会增加选择难度。把职责和工具限定在某一类任务内，就是一种 Agent 专业化，不必为此引入多个 Agent。

工具接入不代表所有操作都被允许。实际读写权限由应用、工具服务和运行环境控制，在操作执行前检查。提示词能告诉模型应该遵守什么规则，工具和环境则需要真正限制操作范围。

要求“不要修改部署配置”时，如果写文件工具仍能改这个文件，模型提出错误请求就可能造成修改。把对应路径设为不可写，或在工具执行前拒绝该请求，限制才会实际生效。

被拒绝的原因要返回模型，供它调整动作或请求授权。网页、文档和工具结果里的文字属于输入资料，不能替用户授予新的权限。发送消息、删除数据、修改生产配置等动作，应按任务授权接入确认步骤。

失败也要分原因处理：临时服务故障可以在运行上限内重试；参数错误需要把原因交回模型；权限不足或业务规则冲突则可能需要暂停，等待人处理。

创建工单时，请求超时不一定代表创建失败，可能只是响应没传回来。重试前要查询是否已创建，或使用服务提供的幂等机制，避免同一个请求留下两张工单。即使本地代码回滚，服务端已创建的工单仍然存在。

3.3 进度保存与恢复

当前上下文供模型判断下一步，外部进度记录供任务中断后恢复。记录可以存入文件、数据库或任务系统，内容需要对应实际执行结果：

• 修改了哪些文件，产物放在哪里。
• 哪些检查已完成，各自通过还是失败。
• 哪些步骤尚未执行，正在等待什么。

计划里写着“运行测试”，只能说明准备做这件事；工具返回结果后，才能据此记录测试是否结束、通过还是失败。

如果文件已经改好，测试运行到一半时任务中断，恢复记录应写明“修改已保存，测试结果不完整”。重新启动后，Harness 读取进度并交给模型，模型通过工具核对代码和测试状态，再决定是否补跑测试。

Git 历史保留代码变更，进度文件保留待办与停下的位置；恢复时仍要检查实际文件和外部操作是否与记录一致。

3.4 验收与停止条件

最简单的循环可以在模型提交最终回答时结束。任务如果要求验收，Harness 就需要在结束之前接入对应检查：检查通过进入交付，未通过则把具体问题交回模型；需要人工审查时，保存结果并等待意见。

验收需要对照用户要求检查实际产物。 “文件写入成功”说明修改已保存，“测试通过”说明被测试的条件成立，它们支持的结论不同。

空购物车测试通过，只说明这个场景返回了预期结果。若任务还要求接口不变，就需要检查函数参数、返回格式和调用方是否受到影响。模型把接口改掉，即使金额算对了，也没有满足全部要求。

检查标准来自具体任务。Harness 负责安排检查、接收结果和选择后续流程；没有业务规则，它无法仅凭一个“验收”步骤判断结果是否正确。

Agent 还可能同时修改实现和测试。如果把错误结果写成新的预期，测试也会通过。关键规则可以由独立维护的验收用例检查，人工审查同时核对测试的修改是否合理。

已有 PR（合并请求）和 CI（持续集成）流程时，Harness 可以读取检查状态，把失败日志交回模型，并在要求人工审查时等待。交付记录应说明产物、修改范围，以及通过、失败和未运行的检查。测试通过不自动意味着已经获准合并或部署。

运行次数、时间和费用上限也需要明确。达到上限时，Harness 应记录当前产物和停下的原因，结束本次运行；“停止运行”与“任务完成”分别记录。

4. 运行追踪与评测

循环接通以后，失败可能来自模型判断，也可能来自提供的资料、工具执行或检查流程。要知道该改哪里，需要看到实际发生过什么。

4.1 Trace：运行追踪

Trace（运行追踪）把一次任务中的模型调用和工具执行连起来记录。 排查时应能找到当轮输入、模型提出的请求、工具返回的结果，以及最终产物和验证状态。

假设模型反复把空购物车改成返回 null。查看 Trace 后发现，输入里一直带着旧版接口说明，里面约定空值返回 null。排查时就要核对这份说明是否过期，以及本轮输入是否保留了“空购物车返回 0”的要求。如果两种要求同时存在，还需要消除其中的冲突。

记录中还需要保留模型和配置版本、耗时、费用、重试次数及人工介入情况，便于比较不同运行。完整输入和日志可能含有敏感内容，保存时要限制访问；保留多久、是否脱敏，也会影响维护成本。

4.2 Evals：任务评测

Evals（评测）给 Agent 一组任务，按约定的标准检查结果。 改了提示词、工具说明或上下文选择方式，就让新旧版本执行同一组任务，比较表现；单看一次成功无法判断改动是否有效。

评测程序负责准备任务、检查和汇总，Agent 负责实际执行。被比较的是模型与 Harness 配合后的表现；评测本身不必放进每一次任务的运行循环。

比较时需要同时看任务完成情况、原有功能是否正常、运行耗时和费用，以及需要多少人工介入。失败记录可以整理成评测案例，但还要保留当时的输入、环境与预期结果，才能重现问题。

同一任务的结果可能随运行而变化，因此重要的版本比较需要重复执行，并保持任务、环境和运行限制一致。评测集还应包含未参与调优的任务，避免只把已知案例修好，却无法处理新的情况。反复执行同一类任务不能替代场景覆盖；任务差异和出错代价越大，需要检查的情况就越多。

如果新版本多花几倍费用才提高成功率，这笔开销也是结果的一部分。Anthropic 的 Agent 评测说明进一步区分了执行记录、环境里的实际结果，以及运行 Agent 和组织评测的两类程序。

5. 提示词、上下文与 Harness 的关系

三者关注的是同一段任务过程中的不同问题：

提示词属于发给模型的上下文。上下文工程还要选择资料和执行记录；Harness 把准备好的上下文交给模型，并组织随后的工具执行和反馈。同一套程序通常会同时承担这些工作。

修改提示词，会改变模型收到的要求；补充上下文，会改变模型判断所依据的信息；调整 Harness，则能改变整个任务运行的方式，包括工具能否执行、中断后能否恢复、提交后是否检查。这些改动作用的位置不同，可以结合具体失败原因分别调整。