Agent Harness 定义:重型基础设施还是轻量外挂层

一、Harness 到底是什么

Agent Harness(常译作”智能体运行外壳”或”执行外壳”)指的是包裹在模型推理循环外层、面向某个具体任务目标的可运行封装层。它不生产智能——智能来自模型;它决定这份智能以什么方式被组织、被约束、被赋予工具、被持久化、被观测,从而能可靠地在真实环境里干活。

可以从三个视角把它说清:

• 技术视角:Harness = 主循环(think → act → observe)+ 预置工具集 + 上下文管理策略 + 状态与容错 + 可观测性。它是一段有主见的代码,而不是一个通用引擎。
• 业务视角:Harness 是”开箱即用的任务能力包”。用户买的不是模型 API,而是”它能提交 PR””它能定位线上故障””它能跑完一套回归测试”这种被封装好的确定行为。
• 使用视角:Harness 定义了用户与 Agent 之间的行为契约——它看哪些文件、允许执行哪些命令、什么动作必须先审批、失败时重试几次、上下文满了怎么处理。

有一个很实用的判定标准:如果把底层模型换成另一家的同代模型,你需要改的是配置、提示词和工具描述,还是核心代码? 只改配置的是 Harness;必须改代码的,你写的其实是业务应用(application)。Harness 的设计目标,正是把”模型差异”隔离在薄薄一层适配代码里。

二、先厘清分层:Framework、Runtime、Harness

业界较早系统区分这三层,是理解这场争论的前提:

层次	职责	关键特征	变化频率
Framework(框架)	提供构建积木:提示词模板、工具抽象、记忆接口、检索接口	无状态、可组合、不预设观点	中
Runtime(运行时)	执行引擎:持久化执行、流式输出、断点续跑、人机协同、并发调度	与业务无关、通用基础设施	低
Harness(外壳)	有主见的封装:预置提示词、固定工具集、第三方集成、记忆与上下文策略	面向具体任务、可被替换	高

三者是叠加关系,不是替代关系。一个成熟的 Agent 系统通常同时用到三层:框架提供积木,运行时提供可靠性,外壳提供”这一版产品该是什么样”的判断。

关键的动态变化在于:这三层的最优厚度正在快速变化。 模型能力越强,框架层需要提供的抽象越少,Harness 层也随之变薄——很多过去必须硬编码在编排层的”规划””反思””分步拆解”能力,已经被更新的模型内化。一个很有说服力的行业实践是:有工程团队会定期从自己的 Agent 外壳中删除规划步骤,因为新模型已经不需要这些人工护栏;也有团队在半年的产品周期内多次重写外壳,只为了适配模型能力的变化。这说明 Harness 的很多代码是折旧资产,不是长期资产。

三、为什么 Harness 会成为独立的设计议题

四个驱动力叠加:

1. 抽象需求下降。模型能力提升后,复杂的图状编排常常只是把模型本来会做的事又写了一遍,反而限制了它的推理路径。
2. 可靠性需求上升。真正难的从来不是”让模型答一次”,而是让它连续工作 30 分钟、调用 40 次工具、中途断网、上下文溢出之后还能收敛。这是分布式系统工程问题,不是编排语法问题。
3. 双向挤压。一方面,模型能力提供方从上往下补齐完整的 Agent 运行时;另一方面,自动化与集成平台从下往上把推理能力整合进既有工作流。中间的独立重型编排层,恰好被两头压缩,最辉煌的窗口期正在过去。
4. 评价标准变了。在面向真实代码仓库缺陷修复的公开评测里,反复胜出的方案往往是”一个极简循环 + 扎实的上下文工程 + 好用的工具”,而不是精巧的多智能体角色分工。这件事本身就回答了一半问题:复杂度不是能力的来源。

四、核心组成:一个 Harness 里必须有什么

1. 主循环与终止条件
最小心智模型就是循环:让模型思考 → 执行动作 → 观察结果 → 再思考,直到给出最终答案或触发终止条件。终止条件必须显式设计:完成标记、最大步数、最大 token 预算、最大墙钟时长、连续无进展检测。

2. 工具层与工具协议
工具是把模型接到真实世界的手。设计上要关心四件事:工具描述是否让模型一眼看懂(名字、参数、何时不该用)、返回结果是否为模型优化过(截断、结构化、错误信息可行动)、鉴权与最小权限、以及是否通过标准化的工具接入协议接入,以便工具能跨多个外壳复用。工具数量应严格控制,过多会显著降低选择准确率。

3. 上下文工程
这是 Harness 中投入产出比最高的部分,包含:预算分配(系统提示、任务描述、历史、工具结果各占多少)、按需检索(不预先灌入,而是让模型主动查询)、压缩与摘要(接近上限时对早期历史做结构化压缩)、外部化记忆(把长文档、大结果落到文件或对象存储,只把引用路径留在上下文里)。

4. 状态持久化与恢复
长时任务必须能中断后从检查点继续。要点是:每一步的输入输出可序列化、工具调用幂等或可补偿、恢复后不重复已完成动作。

5. 容错与循环防护
指数退避重试、超时与熔断、模型/工具双降级路径、以及原地打转检测(相同工具+相同参数连续出现即干预)。缺少这一项,长任务几乎必然烧掉预算。

6. 并发与资源隔离
每个任务应有独立的文件系统沙箱或容器、独立的凭据作用域、明确的 CPU/内存/时长配额。并发控制既要限制单租户总量,也要防止同一任务的并行工具调用互相踩踏。

7. 人机协同与审批闸门
按风险分级:只读动作自动放行,可逆写操作放行并记录,不可逆或高影响动作(删除数据、发布变更、对外发送)强制人工确认。闸门要支持异步等待,不阻塞执行线程。

8. 可观测性与评测
需要一条贯穿全链路的追踪记录:每一步的提示词、模型响应、工具入参出参、token 与耗时、失败原因。没有 trace,就没有优化,只有玄学调参。

9. 安全与权限
最小权限、凭据托管与轮换、输入输出的注入检测、工具返回内容的可信度分级(外部内容视为不可信数据,不能当指令执行)。

五、工作原理:极简主循环的样子

context  = 加载任务目标 + 系统规则 + 可用工具描述
history  = []
budget   = { max_steps, max_tokens, max_wall_clock }
while not terminated(budget):
    prompt = context_builder.build(history, budget)   # 上下文裁剪/压缩
    action = model.invoke(prompt, tools=tool_specs)
    if action.type == "final_answer":
        return action.content
    for call in action.tool_calls:
        if loop_detector.is_stuck(call):              # 原地打转保护
            history.append(intervention(call)); continue
        if risk_level(call) >= HIGH:
            call = await_human_approval(call)         # 审批闸门
        result = tool_gateway.execute(call, sandbox, timeout, retry_policy)
        history.append(observation(result))           # 结果需为模型优化过
        checkpoint.save(history)                      # 可恢复
    budget.consume(model_usage, elapsed)

值得注意的是:这段逻辑与任何具体框架无关,也不需要图结构或角色定义。真正的工程难点集中在 context_builder、tool_gateway、checkpoint、loop_detector 这四个函数上——它们才是 Harness 的价值密度所在。

六、重型还是轻量:答案是中间态

纯重型基础设施的问题:抽象层与模型能力重复建设,迭代速度慢于模型迭代速度,迁移成本高,且大量能力(多级编排、复杂状态机)在真实任务中根本用不到。

纯轻量外挂的问题:能快速跑通演示,但缺少持久化、并发控制、权限边界、可观测性和评测闭环,一旦进入生产环境,失败模式不可解释、成本不可控、事故不可追溯。

站得住的是中间态:”薄核心 + 可插拔模块 + 标准协议”。

• 薄核心:主循环、上下文管理、终止判定——保持在几百行量级,追求可读与可改。
• 可插拔模块:工具、检索、记忆、审批、沙箱以插件形式接入,按任务裁剪。
• 标准协议:工具描述、事件格式、追踪格式尽量对齐通用约定,让同一套工具与观测能力能被多个外壳复用。

在这个架构下,“非差异化”的部分应当外包给通用基础设施:容器平台承载任务沙箱,对象存储保存轨迹、制品与大结果集,消息队列承担异步任务分发与事件路由,日志服务与监控告警承担可观测性,身份认证与密钥托管划定权限边界,负载均衡与内容分发处理接入与分发。这些是业界通用的云服务类目,主流云服务商(包括百度智能云)提供的通用能力即可覆盖大部分需求,不必在 Agent 系统内部重新造一遍。差异化只保留在两处:面向具体任务的提示词与工具设计,以及上下文工程策略。

同时要明确一件事:最优厚度是动态的。模型每提升一档,就应当重新审视一遍外壳,删掉已被模型内化的护栏,把省下的复杂度投到人机协同、评测体系和安全边界上。复杂度应当被主动管理,而不是只增不减。

七、典型适用场景

• 编码与代码治理:缺陷修复、重构、依赖升级、批量迁移。工具需求相对标准(读文件、改文件、跑测试、跑构建),是 Harness 设计最成熟的场景。
• 运维与故障处置:从只读诊断起步,逐步开放受控执行动作,高危操作保留人工确认。
• 数据处理与报表:自然语言到查询、异常检测、口径核对,重点在查询安全与结果可验证。
• 企业知识检索与问答:重点在检索质量、引用可追溯、拒答策略。
• 测试与质量保障:自动生成用例、补充断言、失败归因,天然适合与持续集成流程结合。
• 业务流程自动化:与既有工作流系统集成,Agent 负责判断与异常分支,确定性流程仍交给传统编排。

八、容易混淆的概念

• Harness vs Agent 本体:Agent 指”模型 + 工具 + 循环”构成的执行体;Harness 是把该执行体产品化、可靠化的那一层封装。
• Harness vs 工作流/BPM 编排引擎:后者执行预先声明的固定流程,分支由人定义;Harness 的下一步由模型在运行时决定,流程是涌现的。
• Harness vs 通用运行时:运行时是业务无关的执行与持久化基础设施;Harness 是有任务观点的封装,会预设提示词与工具集。
• Harness vs API 网关:网关管的是请求路由、限流、鉴权,不理解任务语义;Harness 管的是任务级的步骤、上下文与终止。
• Harness vs 工具接入协议:协议解决”工具怎么被描述和调用”,Harness 解决”什么时候调、调完怎么办、失败怎么办”。
• Harness vs 系统提示词:提示词只是 Harness 的一个组成部件,且是最易折旧的那部分。

九、选型与实施注意事项

1. 先定义终止条件和成功判据,再写循环。没有可判定的”完成”,后面全是返工。
2. 上下文预算优先于提示词技巧。多数失败源于信息不足或信息过载,不是措辞。
3. 幂等与可恢复是长时任务的前提,不是优化项。
4. 权限默认拒绝,按动作风险分级放行,不可逆动作强制人工闸门。
5. 可观测性先行:先埋 trace,再谈调优。
6. 建立回归评测集,覆盖典型任务与已知失败模式;模型升级后必须全量重跑,防止能力回退被漏掉。
7. 定期做复杂度减法:每轮换模型,主动删掉已内化的护栏。
8. 设定成本模型:单任务的 token 上限、工具调用次数上限、时长上限,以及超预算后的降级策略。
9. 避免过早抽象:只有一个任务类型时不要做通用框架,等第二类任务出现再提取共性。

十、结论

回答最初的问题:Harness 设计既不会走向纯重型基础设施,也不会停在纯轻量外挂层。重型基础设施正在被上下双向挤压,轻量外挂层撑不起生产环境的可靠性要求,最终胜出的形态是”薄核心 + 可插拔模块 + 标准协议”的中间态——核心循环保持极简并随模型能力演进持续瘦身,可靠性与安全边界交给通用基础设施,差异化集中在上下文工程与工具设计上。

判断一个 Harness 设计是否健康,可以问三个问题:核心循环是否足够短到能一次读完?非差异化能力是否已经外包给通用基础设施?模型升级后,是否有机制强制它变薄?三题都为是,方向就没错。