Agent Harness 设计：重型基座还是轻量外挂

一、先把概念说清楚：什么是 Agent Harness

Agent 与普通模型调用的最大区别在于：它不是一次问答，而是一段会持续运行、会反复调用模型、会操作外部工具、会失败重试、会跨进程恢复的执行过程。Harness 就是包裹这段执行过程的那层运行时封装。

一个更精确的定义：Harness 是位于模型推理之上、业务应用之下的一层薄封装，它把”一次模型推理”提升为”一个可持续推进的任务执行体”。它自身不提供新的智能能力，但它决定了模型已经具备的智能能否被稳定、可控、可复现地兑现出来。

从技术视角看，Harness 是一组确定性的程序逻辑：它决定何时调用模型、把什么放进上下文、如何解析模型输出、如何执行工具、失败了怎么办、进度存到哪里。
从工程视角看，Harness 是一层有”主见”的封装：它不是通用库，而是对某个具体产品场景的预置方案，预设了提示词、工具集、记忆策略与上下文压缩规则。
从使用者视角看，Harness 就是用户实际感知到的那个”助手”——用户说它”聪明”或”笨”，绝大多数情况下评价的是 Harness 的设计质量，而不是底层模型的全部能力。

二、背景：Harness 为什么会成为独立的设计问题

早期做 Agent，人们习惯把逻辑写死在业务代码里：拼提示词、调函数、判断返回值、再调一次模型。这种做法在单步任务下没问题，一旦任务需要多轮推进，问题会集中暴露：

上下文会溢出。多轮工具调用产生的中间结果（文件内容、日志片段、接口响应）体量巨大，全量塞回上下文既昂贵又降低推理质量。
执行会失败。网络抖动、工具超时、模型返回格式不合法、外部服务限流，都是常态而非异常。
状态会丢失。进程重启、容器被驱逐、长任务排队，都会打断一条已经跑到一半的任务链。
权限边界必须收口。模型输出直接映射为外部副作用（写文件、改数据、发消息）是危险的，中间必须有策略层。
可观测性缺失。出问题时无法回答”它当时看到了什么上下文、为什么做了这个决定”。

这五个问题构成了 Harness 的核心职责清单。也正因为它们与模型能力弱相关、与工程要求强相关，Harness 才从业务代码中被抽取出来，成为独立的一层。

三、与相关概念的边界：框架、运行时、Harness

业界常用一套三分法来描述 Agent 技术栈，三者是叠加关系而非替代关系：

框架（Framework）：提供构建积木，例如提示词模板、工具抽象、模型适配接口、记忆抽象。它解决”少写重复代码”。
运行时（Runtime）：提供执行引擎，例如持久化执行、流式输出、并发调度、人机协同中断点、工作流编排。它解决”任务怎么稳定地跑完”。
Harness：最上层的成品封装，面向具体场景预置提示词、工具集、上下文管理策略与默认策略集。它解决”开箱就能干这件事”。

需要额外区分几个容易混淆的概念：

Agent 本身 vs Harness。Agent 是”能自主决策并作用于环境”的抽象；Harness 是把该抽象落地的具体实现外壳。
上下文工程 vs Harness。上下文工程是 Harness 中权重最高的一个子模块，但不能与整层划等号。
编排引擎 vs Harness。编排引擎擅长声明式的确定性流程（条件分支、并行、子流程），Harness 擅长不确定的多步探索。前者约束模型，后者释放模型。
RAG 管道 vs Harness。检索增强是给模型补知识的单向通路；Harness 是让模型可以反复观察环境并据结果修正下一步的双向闭环。

四、工作原理：主循环就是核心

绝大多数设计得好的 Harness，其核心都是同一个形状——一个带预算与状态的循环：

# 语言无关的示意伪代码
state = checkpoint_store.load_or_init(goal)      # 可恢复状态
budget = Budget(max_steps, max_tokens, max_cost)  # 硬约束
while not state.is_finished and budget.has_remaining():
    context = context_manager.build(state)        # 组装：系统提示 + 目标 + 相关历史 + 工具契约
    decision = model.call(context)                # 模型输出：思考 / 工具调用 / 结论
    if decision.is_final_answer:
        state.finish(decision.answer)
        break
    tool = registry.get(decision.tool_name)
    if not policy.allow(tool, decision.arguments):    # 权限与风险闸门
        observation = refuse_with_reason(decision)
    else:
        try:
            observation = tool.run(decision.arguments, timeout=tool.timeout)
        except RetryableError:
            observation = backoff_and_retry_or_record_failure(decision)
        except FatalError as e:
            observation = record_failure(e)
    state.append(decision, observation)
    state = context_manager.compact(state)        # 摘要、裁剪、按需回捞
    checkpoint_store.save(state)                  # 每一步落盘，支持断点续跑
return state.result

这段代码里没有智能，但每一行都在决定智能的产出质量。值得单独说明的三点：

预算优先于提示词。一个没有步数、Token、成本、时间上限的循环，等价于把成本交给概率。预算是第一等公民。
上下文组装是显式的。把”塞什么进上下文”当成随机事件，是 Agent 表现不稳定的主要来源。可检索的历史、按需加载的文件视图、结构化的工具契约，都属于这一层。
checkpoint 的位置决定了系统上限。若只在任务结束时落盘，长任务中断即全废；若每步落盘，则天然支持人工审核、恢复、回滚与灰度重放。

五、两种设计取向：重型基础设施与轻量外挂层

重型基础设施取向：把执行语义做成一套完整平台。典型特征包括显式状态机或状态图、持久化工作流引擎、内置人机协同节点、统一的队列与调度、成体系的可观测面板。

它的优势是确定性强：流程可被审计，中断点可被精确定义，故障可被精确恢复，适合强合规、强审计、步骤相对固定的业务。
它的代价也很明确：心智负担与迭代速度。当模型能力快速演进时，越厚的封装越容易与模型自身能力重复，甚至互相冲突——模型已经学会的技能，被外部状态机强行约束，反而限制了它的自由度。更现实的风险是耦合：一旦业务流程绑定到某个框架的抽象模型上，替换或升级成本极高。

轻量外挂层取向：只做模型必需的最小工程支撑。典型特征是一个主循环、一组工具契约、一套上下文管理策略，外加必要的重试与日志。

它的优势是模型升级成本最低：换模型几乎不用改代码，新能力自动被继承。
它的代价是工程责任外移：幂等、并发、恢复、审计这些能力不会自动出现，需要团队自己补齐。在早期常见的失效方式是”能跑通演示，但撑不住并发与长任务”。

六、为什么中间态更可能是收敛方向

判断重型与轻量谁胜出，需要先看清一个变量：模型能力曲线。模型能力的提升会持续”吞掉”上层抽象的份额。原本需要在框架里显式建模的动作——任务分解、工具选择、错误自修复、自我检查、少量规划——正逐步被模型内化。这意味着任何以”补足模型短板”为存在理由的厚封装，都会面临价值被稀释的问题。

但另一端同样成立。模型能力的提升不会自动带来工程属性：幂等性、审计追溯、成本上限、权限边界、跨进程恢复、多租户隔离，这些是系统工程问题，与模型强弱无关。一个只有 while 循环的实现可以做出很好的效果，但它无法在无人值守的生产环境中直接上线。

由此得到一个更可操作的结论：Harness 的最优形态是薄核心 + 可插拔模块 + 标准协议。

薄核心：主循环足够简单，语义足够清楚，能被一个工程师在一天内读完。核心里不写死任何具体业务判断。
可插拔模块：上下文管理策略、工具集、权限策略、记忆后端、存储与队列、可观测方案，均以接口形式可替换。策略可以演进，接口保持稳定。
标准协议：工具调用、模型接入、能力描述尽量走通用协议，避免专有格式锁定，让模型侧与工具侧可以独立演进。

一个可检验的设计准则：如果某个 Harness 模块的唯一价值是替模型完成它已经开始擅长的事，就应该考虑删除它。工程团队定期精简封装中的规划步骤，本质上是在跟随模型能力做负向重构。

七、典型适用场景

代码与工程类助手。工具面广、上下文敏感、需要长循环与反复验证，适合轻量核心加可插拔工具集。
客户服务与业务办理。步骤相对固定、需要人工审核卡点与强审计，适合在薄核心之上叠加持久化编排与人机协同模块。
数据查询与分析。关键在于上下文构造与结果校验，适合把”检索—计算—核对”做成显式子循环。
批处理与离线任务。强调并发、限速、失败重试与成本预算，适合依托消息队列、容器平台、对象存储等通用基础设施承载。
运维与巡检类场景。强调权限收口与变更审计，工具调用必须有白名单与二次确认。

八、选型与实施注意事项

先定义评测集，再选架构。用一批真实任务（含失败样本）建立可重复的离线评测，才能判断某层抽象是否真的带来收益。缺少评测集的架构讨论基本是偏好之争。
把状态与进程解耦。状态存外部存储、每步落盘，是实现可恢复与可回放的前提。
所有工具调用视为不可信副作用。统一走超时、重试上限、幂等键、权限校验与审计日志，尤其是写入与外部发布类操作。
预算显式化并前置。步数、Token、成本、墙钟时间四项都要有上限，并在接近上限时主动降级为”返回部分结论并说明未完成”。
为模型漂移留余量。提示词与封装策略应版本化，模型升级时做回归评测，而不是直接上线。
接口优先于实现。工具与模型接入使用通用协议与稳定接口，避免深度绑定某一实现细节。
把可观测性作为一等能力。至少需要记录每次调用的输入上下文摘要、工具入参、耗时与结果状态；日志、监控告警、链路追踪等通用云上能力可直接承载这一层。
明确人工介入点。高风险动作设置确认卡点，并保留可中止与可回滚能力。

九、总结

Harness 的定义可以压缩为一句话：它是让模型能力变成稳定生产能力的运行时封装层，核心职责是上下文管理、工具执行、状态持久化、预算控制、权限收口与可观测。

重型基础设施与轻量外挂层的争论，本质上不是架构审美之争，而是对”模型能力会走多快”的赌注。赌模型进步快的方案会保持薄核心，把工程能力做成可插拔模块；赌流程可控性优先的方案会加厚编排与状态层。在能力快速演进的阶段，薄核心加可插拔模块加标准协议的中间态同时满足了两个约束：升级成本低，工程属性可补齐。

判断自己该怎么做，用三个问题即可：这一层抽象是否替代了模型已经擅长的能力；去掉它之后，损失的确定性能否用测试与流程弥补；把它做成接口而非硬依赖，替换成本有多高。三个问题的答案，比任何架构偏好都更接近正确答案。