Agent Harness 工程：开篇

过去两年，Agent 几乎成了 AI 圈最热的词。

能自动发邮件的是 Agent，能总结会议纪要的是 Agent，能改代码、查资料、操作浏览器的也是 Agent。这个词被用得越来越宽，反而让一个基础问题变得模糊：我们到底在开发什么？

我的理解很简单：

Agent = LLM + Harness

LLM 提供语言理解、推理、规划和决策能力；Harness 则提供模型运行所需的外部环境。对于大多数应用开发者来说，我们并不训练模型。我们真正大量投入的工作，是把模型接入一个可以观察、行动、反馈、受控的系统里。

这也是这个系列想讨论的主题：如何把一个聪明的模型，变成一个可靠、可控、可完成任务的 Agent。

什么是 Harness

Harness 这个词原本有“马具、系带、装备系统”的意思。它不是马本身，却决定了马能不能被安全、稳定、有效地驾驭。

如果用汽车类比，模型像发动机，提供动力；Harness 则是发动机之外的整辆车：底盘、车身、方向盘、仪表盘、刹车、导航和安全系统。发动机再强，如果没有这些配套系统，也无法变成一辆可以上路的车。

放到 Agent 里，Harness 可以理解为“模型和真实世界之间的工程层”。它大致包含五类能力：

Tools：文件读写、Shell、网络、数据库、浏览器、业务 API。
Knowledge：产品文档、领域资料、API 规范、架构约束、风格指南。
Observation：用户输入、git diff、错误日志、页面状态、执行结果、外部事件。
Action Interfaces：CLI 命令、函数调用、HTTP 请求、UI 操作、消息发送。
Permissions：沙箱隔离、审批流程、角色权限、信任边界、审计记录。

这些东西合在一起，才构成了模型能够“做事”的环境。没有 Harness，模型最多是在文本里给出建议；有了 Harness，模型才真正具备了观察环境、调用工具、影响系统并接受约束的能力。

模型负责思考和决策，Harness 负责把环境、工具、知识、反馈和边界组织起来。

为什么说多数 Agent 开发其实是在开发 Harness

很多人说“我在开发 Agent”，听起来像是在造一个智能体本身。但拆开看，真正的工程问题往往不是“模型会不会想”，而是：

模型能不能拿到正确的信息？
工具的描述是否足够清楚？
调用工具失败后，模型能不能理解错误并恢复？
上下文会不会被无关信息污染？
危险操作是否需要审批？
任务执行到一半中断后，状态能不能恢复？
最终结果是否可验证、可追踪、可复现？

这些问题都不属于模型训练，而属于 Harness 工程。

换句话说，LLM 是 Agent 的认知核心，但 Harness 决定了它能看见什么、能调用什么、能影响什么，以及什么时候必须停下来等待人类确认。模型负责生成可能的下一步，Harness 负责把“下一步”变成可执行、可回收、可审计的动作。

一个 Agent 的基本循环

一个实用 Agent 不是一次性输出答案，而是在环境里不断推进任务。它通常会经历这样的循环：

观察：读取用户目标、当前环境、历史上下文和外部反馈。
建模：把目标、约束、已知事实和当前状态整理成可推理的上下文。
决策：理解任务，选择策略，决定下一步行动。
行动：调用工具、写文件、发请求、运行命令或操作界面。
验证：接收执行结果、错误信息、状态变化和用户补充，判断是否继续迭代。

Agent 的能力不是来自单次回答，而是来自观察、决策、行动和验证之间持续闭环。

这个循环看起来简单，但每一步都藏着大量工程细节。真正的 Harness，不只是把工具暴露给模型，而是要让每一步都有稳定的输入、清晰的边界和可验证的输出。

例如，工具不是“能调就行”。一个好的工具应该足够原子化，参数清晰，返回结构稳定，并且让模型能够判断成功、失败和下一步修复方向。否则 Agent 很容易陷入“看似在执行，实际在乱试”的状态。

知识也不是“全部塞进 prompt 就行”。好的 Harness 应该让 Agent 知道有哪些知识源可用，并在需要时按需拉取。这样既能控制上下文长度，也能减少无关信息对判断的干扰。

权限更不是最后再补的安全模块。它应该从一开始就成为 Harness 的一部分：哪些路径可以读写，哪些命令需要审批，哪些外部系统允许访问，哪些动作必须留下审计记录。这些边界越清楚，Agent 越有机会在真实生产环境里安全运行。

Harness 工程要解决的核心问题

如果把 Agent Harness 当成一个工程系统来看，它至少要解决五类问题。

Harness 工程的核心，是让 Agent 有手、有知识、有干净上下文、有边界，并且能验证结果。

1. 给 Agent 一双手

工具是 Agent 触达世界的方式。文件系统、Shell、数据库、浏览器、HTTP API，本质上都是 Agent 可以采取的动作。

工具设计的关键不是“越多越好”，而是让每个工具都有清晰的职责、输入、输出和失败语义。工具越稳定，模型越容易形成可靠的行动策略。

2. 给 Agent 合适的知识

知识决定 Agent 是否理解任务所在的领域。

产品文档、代码规范、接口说明、业务规则、历史决策，都可以成为 Agent 的知识来源。真正重要的是知识的组织方式：哪些知识常驻上下文，哪些知识按需检索，哪些知识需要版本化，哪些知识只在特定任务中生效。

3. 给 Agent 干净的上下文

上下文是 Agent 的工作台。工作台太乱，模型就会被噪声干扰；工作台太小，又会丢掉关键线索。

所以 Harness 需要管理上下文：保留目标、约束、关键事实和执行状态；压缩冗长历史；隔离子任务；在必要时把长期目标持久化到对话之外。

4. 给 Agent 明确的边界

Agent 越能做事，越需要边界。

读文件和删文件不是同一种权限；查看日志和操作生产数据库也不是同一种风险。一个成熟的 Harness 应该能区分动作的危险等级，并在关键节点引入沙箱、审批、回滚和审计。

5. 给 Agent 可验证的反馈

Agent 不能只“自我感觉完成了”。它需要通过测试、日志、截图、diff、监控指标或业务结果来确认任务是否真的完成。

反馈机制越清楚，Agent 越容易从错误中恢复，也越容易被人类信任。

重新理解 Agent 开发

如果只看模型能力，我们很容易把 Agent 想象成一个会自动完成任务的“大脑”。但在真实工程里，一个可靠 Agent 更像一套运行系统：模型是大脑，Harness 是身体、感官、工具、环境和安全机制。

所以，开发 Agent 的重点不是把模型神化，而是认真回答一组非常工程化的问题：

它看见了什么？
它知道什么？
它能做什么？
它做错了会怎样？
它什么时候必须停下来？
它如何证明自己做完了？

这些问题回答得越清楚，Agent 就越不像一个演示 Demo，越像一个可以被托付任务的工程系统。

接下来写什么

这篇是 Agent Harness 工程系列的开篇，先把概念边界划清楚。后续我会继续拆具体主题，例如：

工具系统如何设计；
知识如何按需加载；
上下文如何压缩和隔离；
子 Agent 如何分工；
权限与审批如何落地；
任务状态如何持久化；
如何评估一个 Agent 是否真的可靠。

Agent 的上限由模型决定，但 Agent 能不能落地，往往取决于 Harness。

模型负责“想”，Harness 负责让它在真实世界里安全、稳定、可验证地“做”。这件事，才是 Agent 工程里最值得深挖的部分。