Agent 系统中的 Harness 是什么

一、先给结论：Harness 是什么

Harness 是包裹在大模型推理循环外层、带有明确预设主张的那层运行时封装。 它自己不实现推理，也不定义通用编排语义，而是把一个”能干某类活”的智能体所需的一切都预先装配好：系统提示词、工具集合与参数约束、上下文组织策略、记忆与状态、权限边界、错误处理、可观测性埋点。用户面对的不是一个通用框架，而是一套开箱即可用的行为约定。

换个说法：模型是发动机，Framework 是零件仓库，Runtime 是传动系统，而 Harness 是整台出厂的车——它替使用者做了一堆”主见性”决定。这也是它与前两层最本质的区别：Framework 与 Runtime 追求通用与可组合，Harness 追求在某一类任务上表现稳定。

二、为什么这个概念会被单独拎出来

过去几年，构建一个 Agent 的路径通常是”选一个框架，把流程画出来”。这种做法在早期是合理的，因为模型能力弱，需要大量外部编排来补足推理与规划。但随着模型逐步内化规划、工具选择与自我纠错能力，过度编排反而变成了负担：流程僵硬、状态难以追踪、模型能力升级后原有提示与分支变成噪声。

于是工程界出现了三种代表性路线：一是重型框架，提供图结构编排、角色分工、复杂状态机；二是纯外挂层，只在 Agent 循环外围加薄薄一层重试、日志与工具调用封装；三是把框架拆成三层的分工模型——Framework 提供构建积木（提示模板、工具抽象、记忆接口），Runtime 提供执行引擎（持久化执行、流式处理、人机协同、调度），Harness 提供最上层有主见的封装。

一些编码类智能体的实践为第三条路线提供了直观证据：其外层实现极其朴素，核心就是一个 while 循环，没有复杂图结构，没有角色分配，却在真实代码缺陷修复类公开评测中表现突出。这引出了一个关键判断：当模型变强，Framework 层需要提供的抽象变少，Harness 层也会随之变薄。厚度不是设计者的审美选择，而是一个随模型能力浮动的变量。

三、Harness 的核心组成

一个可用的 Harness 通常包含以下六块能力，缺一块都会在长任务上暴露问题。

1. 主循环与终止条件。 最外层是 think → act → observe 的迭代：模型决策、工具执行、结果回灌。真正难的不是循环本身，而是终止判断——最大轮次、最大 token 预算、超时、任务完成信号、重复动作检测，任意一项缺失都会导致空转烧钱。

2. 上下文管理。 这是 Harness 技术含量最高的部分。它决定在每一轮把什么放进上下文窗口：系统提示与工具说明、任务目标、近期交互、检索到的资料、历史压缩摘要。工程上常见做法是分层——近期原文保留、早期压缩为摘要、可再检索的原始日志外置，需要时按需回捞。

3. 工具层与参数契约。 工具描述、参数 schema、返回值裁剪、错误信息可读性，直接决定模型能否正确调用。返回给模型的报错应当是可诊断的自然语言，而不是堆栈原样抛出。

4. 状态与持久化。 会话状态、检查点、事件日志需要落到外部存储，以支持长任务中断恢复、人工介入后继续、以及问题回放。

5. 权限与安全边界。 危险操作白名单、沙箱执行环境、敏感数据脱敏、人工确认节点。编码类场景下读写文件系统与执行命令风险极高，这层不可省略。

6. 可观测性与评测。 每一轮的输入输出、工具调用耗时、token 消耗、失败原因都需要结构化记录，并配套离线评测集回归。没有评测的 Harness 调优只能靠感觉。

四、它如何运转：一段示意性伪代码

function runAgent(goal, maxTurns, budget):
    state = load_or_create_session(goal)        # 从持久化层恢复
    while not state.done and state.turn < maxTurns
          and budget.remaining() > 0:
        ctx     = buildContext(state)           # 分层裁剪 + 压缩 + 检索回捞
        action  = model.decide(ctx)             # 决策：调用工具或结束
        if action.type == "finish": break
        checkPermission(action)                 # 权限与风险校验
        result  = executeWithRetry(action,      # 退避重试 + 幂等键
                                   timeout, sandbox)
        state.append(action, result)            # 事件日志 + 检查点持久化
    return summarize(state)

这段结构说明了两件事：Harness 的复杂度不在循环，而在 buildContext、checkPermission、executeWithRetry 三个函数里；以及它的运行形态天然是一个可恢复的事件流，而不是一次性调用。

五、重型基础设施还是轻量外挂层

这是原始问题的核心。两条极端路线各有明确失效点：

• 重型基础设施的问题：抽象层过深，调试链条长，模型升级后大量编排逻辑冗余；一次行为变更需要改动多处配置；迁移成本高，容易形成框架锁定。
• 轻量外挂层的问题：可靠性能力需要每个团队自己补齐。重试语义、状态持久化、并发控制、人机协同、审计与配额这些”苦活”并不会因为代码少而消失，只是转移给了业务团队重复实现。

因此更可能收敛的中间态是薄核心 + 可插拔模块 + 标准协议：主循环保持极简且可读，把可靠性、可观测性、上下文管理、工具接入做成可替换组件；对外通过统一的工具描述与消息协议与模型侧对接，避免绑定单一供应商。同时行业正在出现双向挤压——上游模型服务商向下提供完整智能体运行时，下游自动化平台向上整合推理能力，独立的中间层框架空间被压缩。这意味着判断标准不是”重还是轻”，而是”哪一层应该由平台承担，哪一层必须留在业务手里”。

六、典型适用场景

• 编码与研发辅助：多文件读写、执行测试、迭代修错，需要强沙箱与差异审查。
• 运维与故障排查：读取日志、指标、配置并生成处置建议，需要只读优先与人工确认高危操作。
• 数据处理流水线：大批量调用、结构化输出、失败重试与断点续跑。
• 企业业务助手：接入知识库与内部系统，重点在权限收敛、审计留痕与配额控制。
• 多智能体协作：角色分工确实有价值，但应作为 Harness 内的一个可选模块，而不是整个系统的地基。

七、与相邻概念的区别

概念	关注点	一句话区分
Framework	提供可复用积木	它是零件库，不含业务主张
Runtime	提供执行语义	它保证”跑得可靠”，不关心任务
Harness	提供成品行为	它对某类任务”有主见”
Orchestrator	调度与依赖编排	偏流程编排，通常不含提示与工具设计
Agent 本体	模型 + 决策	Harness 是它的外围支撑，不是它本身

三者是叠加关系而非替代关系：一个 Harness 内部可以依赖某个 Runtime，Runtime 又可以使用 Framework 的抽象。

八、使用与选型注意事项

1. 把 Harness 厚度当作变量管理。 模型能力升级后应主动做减法，定期删除已被模型内化的提示与分支步骤，而不是只增不减。
2. 上下文预算要显式建模。 明确每类信息的配额与淘汰策略，避免长任务后期质量塌陷。
3. 幂等与可恢复优先。 所有外部副作用操作都应带幂等键，检查点粒度以”可重放到出错前一步”为准。
4. 权限默认收紧。 高危操作走人工确认或隔离环境，密钥与凭据不进入上下文。
5. 成本可归因。 按会话与轮次统计 token 与工具调用开销，设置预算熔断。
6. 必须有回归评测集。 每次提示词或工具描述变更都跑一遍固定用例，用数据判断收益。
7. 落地资源可依托通用云能力。 状态与事件日志可放对象存储或数据库，任务调度可用消息队列与容器平台承载异步执行，可观测性可接入日志服务与监控告警，身份与权限可对接统一身份认证——保持组件可替换，避免与特定实现强耦合。

九、总结

Harness 的本质是”把一个通用模型驯化成一类可靠执行者的那层工程外壳”。它既不是越厚越安全的重型基础设施，也不是越薄越优雅的纯外挂层，而是一个随模型能力、任务风险与团队可靠性需求共同浮动的中间层。设计时的正确问题不是”选哪种架构”，而是”每一项能力应该沉到平台层，还是留在业务层”，并让这层划分始终保持可调整。