聊聊Agent Harness

现在谈 AI Agent，很容易把注意力放在模型上。模型越强，Agent 就越强，这个判断有一部分是对的，但不完整。

同一个大语言模型，放在不同环境里，表现可能完全不一样。一个模型只能在聊天框里回答“你可以这样改代码”；另一个模型却能自己打开项目，搜索文件，修改代码，运行测试，再根据失败日志继续修。它们背后的模型能力可能差不多，但外面包着的工作系统不同。

这个工作系统，就是 Agent Harness。

为什么只谈模型不够

想象一个很普通的任务：登录页上的按钮点了没有反应。

如果你把这句话发给一个普通聊天模型，它通常只能根据你贴出来的代码给建议。它可能会说：“检查事件监听器是否绑定”“确认按钮没有被 disabled”“看看控制台有没有报错”。这些建议可能有用，但它不能自己进入你的项目，也不能验证问题是否真的解决。

如果你把同一个任务交给一个 coding agent，情况就不同了。它可以先读项目规则，再搜索登录页相关文件，查看按钮事件、状态管理和错误日志。然后它可以修改代码，运行测试，甚至打开页面验证按钮是否恢复响应。如果第一次修改失败，它还能读失败信息，继续定位问题。

差异不只在模型是否聪明。更关键的是，第二个系统给了模型一套可执行的工作环境：它知道该读什么、能用什么工具、哪些操作需要批准、如何检查结果、失败后如何继续。

这套环境就是 harness。它不是一个华丽的外壳，而是把模型能力转化为可靠行动的工程层。

什么是 Agent Harness

可以用一句话定义：Agent Harness 是连接模型、上下文、工具、环境、权限、验证和状态管理的控制系统。

如果把模型比作“大脑”，harness 就像工作制度和操作环境。它决定模型能看到什么信息，能调用什么工具，行动范围在哪里，结果如何验证，长任务中状态如何保存。

工具调用只是 harness 的一部分。一个文件读取工具、一个命令行工具、一个浏览器工具，本身只是行动接口。真正重要的是这些工具如何被描述、如何被选择、失败时如何回传信息，以及高风险动作是否会被限制。

所以，一个好的 harness 不是让模型神秘地“更聪明”，而是让模型更稳定地把已有能力转化成结果。

先澄清几个误解

第一个误解是：Agent Harness 就是 prompt。不是。Prompt 只是上下文的一部分。Harness 还包括工具、权限、状态、验证和恢复机制。

第二个误解是：Agent Harness 就是工具调用。也不是。工具没有权限、验证、状态和恢复，就只是 API 列表。模型能调用工具，不等于它能可靠完成任务。

第三个误解是：Agent framework 就等于 harness。Framework 更像代码框架和组件库，帮助开发者快速搭建 Agent。Harness 更关心运行时控制：上下文怎么装配，工具怎么暴露，权限怎么管理，失败怎么恢复。

第四个误解是：模型更强以后，harness 就不重要了。实际情况可能相反。模型越能行动，越需要清楚的边界、验证和治理。一个只能聊天的模型，风险主要在回答错；一个能改文件、跑命令、访问网络的模型，风险会进入真实环境。

第五个误解是：多 Agent 一定更强。多个 Agent 可能带来并行和分工，也会带来协调成本。只有当任务真的能拆分、上下文太大、需要不同角色或独立判断时，多 Agent 才值得引入。

Harness 为什么会显著改变 Agent 表现

Agent 的表现不是模型单独决定的。至少有六个因素会被 harness 改变。

第一，上下文质量决定模型看到的问题形状。模型不知道项目结构，就只能猜。模型读到了错误文件，也会朝错误方向努力。

第二，工具接口决定模型能否把计划变成行动。工具描述不清楚，输入格式混乱，输出错误难理解，都会让模型误判下一步。

第三，反馈回路决定错误能不能被发现和修正。没有测试、日志和页面检查，模型很容易在“看起来合理”的地方停下。

第四，权限制度决定自动化和安全之间的平衡。全部禁止，Agent 无法行动；全部放开，风险不可控。好的 harness 会区分低风险动作、高风险动作和禁止动作。

第五，验证机制决定 Agent 是“自信地结束”，还是“证据充分地结束”。这两者差别很大。

第六，可观察性决定人能否理解失败发生在哪里。Agent 做过什么、看过什么、为什么停下，如果没有记录，失败后就很难复盘。

同一个模型放进不同 harness，就像同一个工程师进入不同组织。能力可能相同，但能调动的信息、工具、权限和检查制度完全不同，最后产出也会不同。

一个 Coding Agent 真正做事时，Harness 在管什么

继续用“登录页按钮没有响应”这个例子。

一个最低限度可工作的 harness，首先要把任务交给模型。它不只是把用户的一句话塞进对话框，还要补上项目规则、当前工作目录、相关文件、历史状态和安全约束。

然后，Agent 会进入一个循环。

它先判断下一步需要什么信息。比如，按钮在哪个文件里？登录页用的是 React、Vue，还是普通 HTML？点击事件是否绑定？浏览器控制台有没有报错？

接着，它调用工具读取文件或搜索代码。工具返回结果后，Agent 再根据观察到的信息继续判断。如果发现按钮事件确实没有绑定，它会修改代码。如果发现事件绑定了，但请求接口失败，它会继续查 API 调用和错误日志。

修改完成后，Agent 不应该马上说“修好了”。它要运行测试，或打开页面点击按钮。如果测试失败，它继续读错误。如果页面仍然无响应，它继续查浏览器状态。只有当验证通过，才进入交付。

这个过程看起来像人在调试，但关键在于：模型本身并不会天然拥有这些流程。Harness 把这些步骤变成可执行、可观察、可约束的系统。

第一步：给 Agent 正确的上下文

上下文是 harness 的第一道核心能力。

这里的上下文不只是用户输入的一句话。它可能包括系统提示、项目规则、当前任务、历史状态、检索内容和文件片段。对 coding agent 来说，还可能包括仓库结构、测试命令、代码风格、禁止修改的目录，以及已有的失败日志。

上下文不是越多越好。模型有 token 预算，输入越长，越容易混入噪音。旧信息如果没有清理，还会造成上下文腐化：模型被过时目标、旧错误或无关文件牵着走。

所以 harness 要做三件事。

第一是装配，也就是 assembly，把当前任务真正需要的信息放进来。第二是压缩，也就是 compression，把长历史和工具输出变短，但保留关键事实。第三是预算，也就是 budgeting，为模型推理和最终输出留下空间。

在长任务中，一个实用做法是写结构化交接物。比如记录当前目标、已尝试方案、失败原因、下一步计划。这样即使上下文重置，Agent 也能从一个清楚的状态继续，而不是从一团聊天记录里恢复记忆。

第二步：让 Agent 能行动

工具系统让模型进入外部世界。

常见工具包括文件读写、命令行、浏览器、搜索、数据库、API，以及通过 MCP 这类标准协议接入的外部工具。工具越强，Agent 能做的事越多。但工具系统的质量，不只在功能，还在接口设计。

一个好工具描述至少要告诉模型四件事：什么时候使用，输入格式是什么，输出代表什么，常见失败如何处理。

如果一个命令行工具只返回一大段杂乱日志，Agent 很难判断错误在哪里。如果一个搜索工具没有说明搜索范围，Agent 可能在无关目录里浪费时间。如果工具太多而没有动态加载机制，模型还会在选择工具上消耗大量注意力。

因此，工具治理是 harness 的核心问题。工具太少，Agent 无法行动。工具太多，Agent 选择困难，上下文也会变脏。更成熟的系统会使用动态加载、技能菜单和工具注册表，让模型只在需要时看到相关能力。

回到登录页例子。读文件工具决定 Agent 能不能定位按钮代码；命令行工具决定它能不能跑测试；浏览器工具决定它能不能验证真实页面行为。没有这些工具，模型只能建议。接入这些工具后，模型才开始真正行动。

第三步：限制 Agent 的行动边界

自动化不是无约束执行。

一个能读文件、写文件、跑命令、访问网络的 Agent，必须有清楚的行动边界。Harness 至少要回答三个问题：哪些动作可以自动执行？哪些动作必须请求批准？哪些动作永远禁止？

人工确认是常见做法，但它也有局限。如果 Agent 每隔几十秒就请求一次确认，人会疲劳，最后可能机械地点同意。更麻烦的是，复杂工具调用的风险并不总是容易判断。一个命令看似普通，实际可能写入敏感目录、覆盖重要文件，或触发外部服务。

更可扩展的做法是风险分级。低风险读操作可以自动执行，高风险写操作需要批准，破坏性操作直接禁止。沙箱也很关键，它限制 Agent 能访问和修改的范围。即使模型判断错误，损害也被控制在边界内。

有些系统还会使用分类器审查高风险动作，甚至采用盲审式风险判断，也就是 reasoning-blind review。它的意思是，审查时不要被 Agent 自己的解释带偏，而是直接看动作本身的风险。

权限系统不是补丁。它是 harness 的一等公民。

第四步：让 Agent 根据反馈继续修正

Agent 不应该只是一次性生成完整答案。更可靠的方式是循环推进。

这个循环可以简化为三步：思考、行动、观察。英文里常写作 Reason, Act, Observe。

思考，是判断下一步要做什么。行动，是调用工具。观察，是读取工具返回、错误信息、日志或页面状态。观察之后，Agent 再决定继续、换方向，还是停止。

这个循环让 Agent 有机会从失败中恢复。测试失败，它可以继续读错误信息。页面无响应，它可以继续查浏览器控制台。权限受阻，它可以说明需要用户批准，或者换一条低风险路径。

好的 harness 还会有明确的停止条件。比如目标已经达成，验证已经通过，权限受阻，信息不足，或者超出预算。没有停止条件的 Agent 容易陷入无意义循环；停止太早的 Agent 又容易交付一个未经验证的答案。

第五步：先验证，再交付

验证是 Agent 能否可靠完成任务的分水岭。

低质量 Agent 的结束方式是：答案看起来合理，于是停止。高质量 harness 的结束方式是：先验证，再交付。

验证可以有很多形式。代码任务里常见的是单元测试、类型检查、lint、构建和浏览器交互。API 任务可以用请求检查状态码和响应结构。数据任务可以检查行数、字段、异常值和日志。

关键不在于每次都跑所有检查，而是验证要和任务风险匹配。改一个文案，不一定需要完整构建。改登录流程，就应该至少跑相关测试或做一次页面验证。

在登录页按钮的例子里，真正的交付不是“我改好了”。更可信的交付是：“我修正了按钮点击事件的绑定，并运行了相关测试；随后打开登录页确认点击后状态正常变化。”这类说法把结论和证据绑定在一起。

验证不是附加步骤，而是 Agent loop 的一部分。

第六步：保存状态，让长任务可恢复

短任务可以靠当前上下文撑住。长任务不行。

一个复杂任务可能持续几十轮，甚至跨越多次会话。模型不可能永远把全部历史塞在上下文里。此时，harness 需要把状态保存到更稳定的位置。

最简单也最可靠的状态载体，往往是文件系统。任务计划、日志、交接文档、测试结果、已知风险，都可以写成结构化文件。这样即使会话中断，下一次也能恢复。

这里的重点不是“记住所有聊天记录”，而是保存真正有用的状态：当前目标是什么，已经尝试过什么，哪些验证通过或失败，下一步应该从哪里继续。

这也是为什么很多有效的 Agent 系统，并不把记忆设计成神秘的黑箱，而是让状态尽量显式、可读、可审计。

什么时候需要多个 Agent

多 Agent 是 harness 能力的扩展，不是默认答案。

当一个任务上下文太大，一个 Agent 装不下；或者任务可以自然拆分；或者需要不同角色做独立判断；或者多个部分可以并行推进，这时多 Agent 才有价值。

常见模式包括 leader-worker、planner-generator-evaluator、fan-out / fan-in 和 supervisor。比如一个 Agent 负责规划，一个 Agent 负责实现，一个 Agent 负责检查。或者多个 Agent 分头读不同资料，最后由主 Agent 汇总。

但多 Agent 也会带来问题。每个 Agent 看到的上下文不同，判断可能冲突。它们之间需要清楚的边界、最小共享上下文、文件式交接、超时和失败回收。否则，多 Agent 不是增强系统，而是在制造协调成本。

所以，对普通读者来说，只需要记住一点：多 Agent 不是“越多越强”，而是当任务真的需要分工时，harness 提供的一种组织方式。

从本地工具到生产级 Runtime

本地 harness 关注的是单次任务能不能完成。生产级 runtime 关注的问题更多。

如果一个 Agent 要成为产品，它需要持久 session、可恢复执行、任务调度、密钥边界、按需创建运行环境、审计日志和用户通知。

这里有一个重要变化：模型调用可以是无状态的，但会话和工作环境不能完全无状态。模型可以每次重新被调用，但它正在处理的任务、已经打开的文件、运行过的命令、等待中的验证、用户授权过的权限，都需要被系统保存。

这就是所谓“大脑与双手解耦”。大脑是模型，双手是工具和运行环境。大脑可以临时调用，双手所在的工作环境需要被创建、隔离、替换和恢复。

当 Agent 从个人工具变成长期运行的产品，harness 就不只是一个调用模型的小壳，而会变成 runtime 和基础设施问题。

一个好 Harness 的判断标准

判断一个 Agent 产品好不好，不应该只看它接了哪个模型。还要看它的 harness 是否可靠。

可以问几个问题。

Agent 能否找到正确上下文？能否选择正确工具？工具失败时是否暴露真实错误？长任务中状态是否可恢复？高风险动作是否被拦截？结果是否经过验证？人能否追踪 Agent 做过什么？系统能否从失败中恢复，而不是只能重来？

这些问题比“模型参数有多大”更接近真实使用体验。

一个 Agent 如果不能找到正确信息，模型再强也会猜。一个 Agent 如果不能验证结果，回答再流畅也不可靠。一个 Agent 如果没有权限边界，自动化越强，风险越大。

结尾：Agent 时代的软件工程重心变化

过去的软件工程主要是人写代码，机器执行。Agent 时代会逐渐变成：人定义目标和制度，Agent 在 harness 中执行。

真正的竞争点不只是模型能力，也包括仓库是否 agent-readable，工具是否 agent-friendly，验证是否机器可消费，权限和状态是否制度化。

未来判断一个 Agent 产品好不好，不只看模型名，还要看它怎样获得信息、怎样行动、怎样验证、怎样被约束。

Agent Harness 的意义就在这里。它把“会说话的模型”放进一个有上下文、有工具、有边界、有反馈、有验证的系统里。只有这样，模型才不只是回答问题，而是开始负责做事。