agent-harness-">AI Agent 的“Harness”到底是什么

在大语言模型（LLM）驱动应用的早期，开发者最常遇到的一个落差是：模型在对话里表现得博学而流畅，一旦要它真正“动手做事”——读取一个文件、修改一段配置、执行一条命令、检索一次线上数据——它就无能为力了。模型本身唯一原生具备的能力，是在给定上下文后生成文本。要让这份文本能力转化为对外部世界的实际操作，中间必须补上一层工程结构。这层结构，业界常称为 Harness。

一、概念定义：Harness 是什么

Harness 原意是“马具”“挽具”，指套在马身上、把马的牵引力传导到车辕上的那套装置。这个比喻非常贴切：马有力量，但力量本身不会拉车，必须通过挽具被约束、被导向、被传导。在 AI Agent 语境下，Harness 指的是包裹在语言模型之外、负责把模型输出转化为工具调用、把工具结果回灌给模型、并驱动多轮循环直至任务完成的那一层运行时结构。

更精确地说，Harness 不是模型的一部分，也不是某一个具体工具，而是模型与外部环境之间的“驱动层 + 编排层 + 约束层”。它至少承担四件事：

• 向模型提供可用的工具清单及其调用规范；
• 解析模型输出的调用意图，校验参数，执行对应工具；
• 把执行结果（成功、失败、返回数据）格式化后重新送入模型上下文；
• 控制循环的终止条件、轮次上限、错误重试与安全边界。

因此，一个完整的 Agent 大致可以表述为：Agent = 模型 + Harness + 工具集。模型提供推理与决策，工具提供外部能力，Harness 负责把两者稳定地咬合在一起。

二、为什么需要 Harness：背景与价值

1. 模型的原生边界

默认情况下，模型能做的只有生成文本。它没有文件系统、没有网络、没有 shell，也无法感知自己上一次调用的结果。即便今天多数模型经过了工具调用相关的专门训练，懂得配合工具工作，这份“懂得”仍然只是生成符合工具调用格式的文本，真正执行动作的仍然是外部程序。Harness 就是那个把“格式文本”变成“真实动作”的执行者。

2. 从单次问答到多步任务

真实任务往往不是一次调用能完成的。例如“定位某配置文件中的错误项并修正”，需要先列目录、再读文件、再定位内容、再写回、再验证。每一步的结果都影响下一步决策。Harness 提供的循环机制，使模型能够在“思考—调用—观察—再思考”的闭环中逐步推进，这正是 Agent 区别于单轮问答的本质。

3. 稳定性与可控性

如果让模型自由生成任意命令并直接执行，风险与不确定性极高。Harness 通过在中间层做参数校验、权限检查、超时控制、输出截断、失败重试，把不可控的模型输出收敛为可控的工程行为。它也是审计与可观测性的落点：每一次工具调用都可以被记录、回放与分析。

三、核心组成：Harness 的关键模块

可以把 Harness 拆解为以下几个关键部分。

工具注册与描述层。Harness 维护一份工具清单，每个工具包含名称、用途说明、参数结构（名称、类型、是否必填、取值范围）以及返回格式。这份描述会以结构化形式注入模型上下文，模型据此判断该不该调用、调用哪个、传什么参数。描述质量直接决定调用准确率——用途说明含糊，模型就容易误选工具。

调用解析与校验层。模型输出的是文本形式的调用意图，Harness 需要将其解析为结构化对象，并逐项校验：工具是否存在、参数是否齐全、类型是否匹配、取值是否越界。校验不通过时，可以选择返回错误信息让模型自我修正，而不是直接崩溃。

执行与沙箱层。校验通过后由执行器真正调用工具。这一层通常需要沙箱隔离、资源限额（CPU、内存、执行时长）、网络访问策略与文件访问范围限制。对于命令执行类工具，超时与输出长度截断尤其重要，避免一次调用拖垮整个会话。

结果回灌与上下文管理层。工具返回结果需要被裁剪、摘要或结构化后重新写入模型上下文。原始输出可能极长（例如一次日志查询返回数万行），直接塞入会挤爆上下文窗口。Harness 需要做截断、摘要、分页或只保留关键字段。

循环控制层。负责维护轮次计数、终止判断（任务完成、达到最大轮次、连续失败、超时）、错误重试策略以及中断恢复。这是 Agent 不会“无限打转”的关键。

可观测与安全层。记录每次调用的入参、出参、耗时、结果状态，供调试与审计；同时实施权限校验、敏感操作二次确认、危险命令拦截等策略。

一段示意性的循环伪代码如下，可帮助理解各模块的协作关系：

context = 初始任务 + 工具清单描述
loop:
    output = 模型(context)
    if output 不含调用意图:
        返回 output 作为最终答案，结束
    call = 解析并校验(output)
    if 校验失败:
        context += 错误说明
        continue
    result = 沙箱执行(call, 超时, 权限)
    context += 裁剪与格式化(result)
    if 达到轮次上限 or 超时:
        结束并返回当前状态

四、工作原理：通俗视角

用餐厅来类比会很直观。模型像一位有想法但被隔离在后厨的大厨，他知道菜谱、懂得搭配，却看不见冰箱、摸不到灶台。工具是厨房里的设备：读取食材、切配、点火、出餐。而 Harness 是那套把大厨的指令传导到设备上的操作规范与传菜机制——它规定每道指令怎么写、由谁执行、执行结果怎么反馈回大厨、出问题时怎么处理、什么时候该停下来。

大厨说“取三号冰箱第二层的食材”，Harness 负责确认三号冰箱存在、第二层有权限打开、取出后把“取到了什么、是否新鲜”回报给大厨。大厨据此决定下一步是继续切配还是换方案。整个过程中，大厨始终只输出指令，真正触碰设备的是 Harness。这个分工正是 Agent 系统稳定运行的基础。

五、典型场景

Harness 的价值在需要“多步操作 + 外部系统交互”的场景中最为突出。

• 代码与配置维护：读取仓库文件、定位问题、生成修改、执行验证命令，形成闭环。
• 运维与故障排查：查询监控指标、拉取日志、比对变更记录、触发回滚流程。
• 数据处理流水线：检索数据源、转换格式、写入目标存储、校验结果一致性。
• 企业知识检索与问答：多轮检索、结果筛选、引用核对后再组织答案。
• 自动化测试与验证：生成用例、执行、读取结果、根据失败信息迭代修正。

在这些场景里，单纯依赖模型生成文本无法落地，必须由 Harness 把决策转成动作、把动作结果转回决策依据。

六、易混淆概念的区别

Harness 与模型：模型是决策核心，Harness 是执行与编排外壳。换模型不影响 Harness 的职责，换 Harness 则会显著改变同一模型的落地效果。

Harness 与 Agent 框架：框架是开发侧的抽象与脚手架，提供组织代码的结构；Harness 是运行时的实际驱动逻辑。框架可以帮助你构建 Harness，但二者不等同。

Harness 与工具：工具是被调用的能力单元，Harness 是调用工具、管理调用过程的机制。工具越多，Harness 的注册、校验与权限管理职责越重。

Harness 与提示词工程：提示词影响模型如何理解任务与工具；Harness 决定这些理解能否被正确执行与反馈。二者互补，缺一不可。

七、使用注意事项

在设计与选型时，有几个点值得重点关注。

• 工具描述即接口契约：描述不清会直接导致误调用，应把参数含义、边界条件、返回结构写清楚。
• 上下文预算管理：长输出必须裁剪或摘要，否则轮次稍多就会触及上下文上限，导致早期信息丢失。
• 终止条件必须显式：轮次上限、超时、连续失败阈值都要设定，避免循环失控与成本放大。
• 权限最小化与沙箱隔离：文件访问范围、命令白名单、网络策略都应默认收紧，敏感操作增加确认环节。
• 可观测性前置：调用日志、耗时、失败原因应从一开始就记录，否则线上问题难以定位。
• 幂等与副作用控制：写文件、发请求等有副作用的操作要考虑重试带来的重复执行风险。
• 成本与延迟权衡：多轮循环意味着多次模型调用，需在任务复杂度与响应成本之间取得平衡。

八、总结

回到定义本身：Harness 是包裹在语言模型之外的运行时结构，负责把模型的文本输出转化为工具调用、把工具结果回灌为模型输入，并驱动多轮循环直至任务完成。它解决的是“模型只会生成文本”与“任务需要真实操作”之间的断层问题。理解 Harness，本质上就是理解 Agent 系统中“决策”与“执行”如何被可靠地连接起来——模型负责想，工具负责做，而 Harness 负责让这两件事稳定地发生在同一个闭环里。把握住这一层，Agent 的方案设计、问题定位与能力边界判断都会清晰许多。