Agent系列之二：什么是Harness工程？

字数统计: 6.1k阅读时长: 22 min

 2026/09/04

同一个模型，放进不同的系统，表现可以天差地别。同一个 Claude Sonnet 4.5，只换一套 Harness，在 GAIA 基准上就从 30.91% 跳到 74.55%——43.64 分的提升，比大多数模型换代带来的提升还大；LangChain 团队不改一行模型、只改 Harness，把 Terminal Bench 从第 30 名做到第 5 名。权重没变，变的是模型周围的那套工程，这就是 Harness 工程要关注的东西。

大模型LLM出现之初，出现了提示词工程（Prompt Engineering），是为了解决模型单次调用输出的可控性与稳定性问题，而上下文工程（Context Engineering）则是保证在多轮对话后，交互的上下文信息能准确地传递给大模型。而最近看文章又频繁出现循环工程（Loop Engineering）、图工程（Graph Engineering）。总结来说，循环工程是解决Agent下一步做什么以及什么时候结束的问题，类似于ReAct中的推理-决策-观察循环；图工程则是围绕多步骤执行节点、跨Agent之间的工作流编排。Harness工程则可以看作是执行环境、反馈闭环、可观测性和治理的综合体，用于解决Agent在任务执行中的上下文管理、工具调用控制、身份验证与权限控制、执行跟踪、结果反馈等问题。

Harness在不同框架中也被称为Agent Runtime。本文采用广义的说法，将其视为支撑Agent运行的完整（非模型）系统；Loop和Graph则属于Harness中的执行编排机制。

agent-engineering-concept-map

多项研究表明，在不更新模型权重的情况下，仅通过优化Agent的工具接口、上下文管理、反馈循环、记忆和验证机制，就可以显著提高任务完成率。这说明Agent的最终能力并不完全由基础模型决定，Harness同样是影响系统表现的重要变量。

SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering — Yang et al., 2024：通过专用代码搜索、文件编辑、精简反馈、上下文裁剪和 Lint 护栏构建 Agent-Computer Interface。在相同 GPT-4 Turbo 下，SWE-bench Lite 解决率从 Shell-only 的11.0%提升至18.0%，相对提升约64%
Self-Refine: Iterative Refinement with Self-Feedback — Madaan et al., 2023：将单次生成改造为“生成—反馈—修正”的迭代Loop，不增加训练数据、不进行模型微调。使用相同模型在7类任务中，相比一次性生成，任务表现平均取得约20个百分点的绝对提升
Reflexion: Language Agents with Verbal Reinforcement Learning — Shinn et al., 2023：Agent读取测试反馈、生成自我反思，并把反思写入情景记忆，用于指导后续尝试。HumanEval Python：pass@1由80.1%提升至91.0%；HumanEval Rust：由60%提升至68%；LeetCode Hard：由7.5%提升至15.0%
ReAct: Synergizing Reasoning and Acting in Language Models — Yao et al., 2022：通过“推理—行动—观察”循环，让模型在推理过程中调用工具、获取环境反馈并调整后续行动。ALFWorld成功率绝对提升34个百分点；WebShop成功率绝对提升10个百分点；在知识问答和事实验证任务中，减少了单纯思维链的幻觉与错误传播
Voyager: An Open-Ended Embodied Agent with Large Language Models — Wang et al., 2023：围绕 GPT-4 构建自动课程、Skill Library、环境反馈、执行错误处理和自我验证机制，无需微调基础模型。获得的独特物品数量达到此前方法的3.3倍；探索距离达到此前方法的2.3倍；解锁关键技术树节点的速度最高达到15.3倍

由此可见，Harness工程对大模型执行任务的结果有着至关重要的影响。总结一句话来说：模型决定Agent能力的上限，Harness决定这些能力能否稳定地转化为生产结果。 这一篇我们重点讲清Agent Harness是什么，核心要素怎么设计。

Harness是什么

大模型做的事，本质上是一次性、局部的推理映射：

1	当前上下文 → 模型推理 → 候选答案或下一步行动

真实任务要求的却是一个持续闭环，两者的核心差异在于模型负责预测下一步该做什么，而Agent任务系统则必须保证最终目标真正达成：

1 2	任务目标 → 获取状态 → 规划行动 → 执行工具 → 观察结果 → 验证纠偏 → 达到最终状态

Harness工程就是连接模型局部行动与最终结果的工程系统，它解决的就是大模型推理过程中存在的核心问题：

无持续记忆：模型只知道当前上下文窗口的内容，不会自动保存跨调用、跨会话和跨任务的长期状态，一旦任务状态信息超过上下文窗口，就会出现信息遗漏的问题，可能丢失关键的决策信息
无执行能力：模型本身只能生成 Token，不能真正修改文件、查询数据库、控制设备或观察执行结果——它需要工具去“做”，需要环境反馈去“看”
无外部真值：模型优化的是在给定上下文下生成合理输出，而不是天然保证输出符合客观事实或业务验收标准。“说得通”并不能等同于“做得对”，比如代码看起来合理，但可能执行异常；报告结构完整，但是引用的文献可能不存在
无可靠安全边界：模型可以理解规则，但模型本身不能成为安全边界。如果系统向它暴露了某个工具和凭据，它就可能在推理偏差、提示注入或目标冲突下调用这些能力。不能依靠一句“请勿访问生产环境”实现生产安全。Harness必须从系统层面限制能看到哪些数据、能调用哪些工具、能修改哪些资源、能执行多长时间、哪些操作要审批、哪些必须禁止；真正的边界应由权限系统、策略引擎、沙箱和人工审批实现，而不是依赖模型自律
无可靠收敛机制：模型可以不断生成下一个判断，但却无法可靠地判断任务是否已经完成；当前方案是否有效；是否应该停止并请求帮助。因此，（没有Harness的）Agent可能出现无限重试、目标偏移、过早结束或者成本失控

把这五处缺失补上，就是Harness的定义：

Agent Harness是围绕模型构建的一套运行环境与控制系统——它向模型提供上下文、工具、状态、约束与反馈，使模型能够持续、安全、可验证地完成任务。

具体到Harness工程的详细构成，比较倾向于文章Harness Engineering: the skill that replaced prompt engineering in 2026给出的7个核心组成部分的框架，这里我将其画成了一个详细的系统框图，便于理解。

harness-engineering-architecture

`Harness`组成部分	功能说明
1. 任务与工具编排 Task & Tool Orchestration	1. 将目标拆解为可执行任务，通过`Loop`、`Graph`组织执行顺序与工具调用； 2. 管理重试、失败恢复、超时、终止及人工接管，推动任务完成。
2. 上下文与记忆 Context & Memory	1. 管理任务状态、检查点及短期与长期记忆； 2. 按需检索知识，组装、筛选和压缩模型输入，维持多步任务的连续性。
3. 路由与模型选择 Routing & Model Selection	1. 根据任务类型、能力要求、成本与时延选择模型； 2. 统一调用接口，处理故障回退与用量控制，并将模型响应返回编排模块。
4. 验证闭环 Verification Loops	1. 通过测试、规则与验收标准检查执行结果和候选答案，输出通过、失败与需人工确认的结论； 2. 为重试、纠错和最终交付提供依据。
5. 安全护栏 Guardrails	1. 检查身份、权限和数据访问范围，控制工具执行与高风险操作审批； 2. 制定资源限制及沙箱隔离策略，阻止未授权行为。
6. 可观测性 Observability	1. 记录模型调用、工具执行、状态变化与审批事件； 2. 跟踪时延、费用和失败原因，支持审计、故障定位、过程回放与效果分析。
7. 反馈与自我改进 Feedback & Self-Improvement	1. 从执行记录中沉淀失败案例与有效经验； 2. 通过离线评测优化记忆、提示词、编排及路由策略，经回归验证和版本发布后改善后续任务表现。

基于上述框图与表格中的内容，我们一一来看下Harness工程里最核心的7个要素，简要介绍下其核心功能以及具体应该怎么实现。

Harness的七个核心要素

先厘清一件事：上一节提出的五个缺失（无记忆、无执行、无真值、无边界、无收敛）分别由哪些要素来补，对应关系如下：

模型缺失的能力	由哪些要素补上
无持续记忆	上下文与记忆
无执行能力	任务与工具编排
无外部真值	验证闭环
无可靠安全边界	安全护栏
无可靠收敛机制	任务与工具编排、验证闭环

路由与模型选择、可观测性、反馈与自我改进是三个横向、跨模块的系统机制：它们分别服务于成本与时延控制、过程证据留存以及跨任务的持续改进，不针对某一处单一缺失。

下面逐一深入看下每个要素需要解决的问题，以及可能的方案设计。

1. 任务与工具编排｜Task & Tool Orchestration

模型可以提出下一步行动，但任务往往包含依赖关系、并行步骤、等待审批和失败重试。没有执行控制，Agent容易重复调用、遗漏步骤，或在异常后丢失进度。任务与工具编排主要负责将目标组织成可持续推进的任务，其核心职责主要有如下几个：

任务组织与控制：拆解目标，维护步骤、依赖关系与完成状态
执行调度：组织Loop、Graph、串行与并行任务，调用模型和工具
异常恢复：处理超时、重试、取消和断点恢复，避免重复执行产生副作用
停止与接管：根据验收结论、步数和预算决定继续、结束或转交人工

task-tool-orchestration-diagram

例如，我们可以在编排器初始化时加载如下配置，确保任务与工具编排按照指定的要求执行：

orchestration:
  mode: graph_with_agent_loop  # 固定流程中嵌入局部Agent循环
  max_steps: 30               # 限制模型决策轮数
  task_timeout_s: 1800        # 任务截止时间，包含审批等待
  max_parallel_tools: 4       # 仅并行无依赖、无资源冲突的调用

  checkpoint:
    backend: postgres
    save_on: [step_completed, before_approval, task_finished]

  retry:
    max_attempts: 3
    backoff: exponential
    only_if: transient_and_retry_safe

  completion:
    require_verification: true
    on_limit_reached: handoff # 达到限制后转人工，不视为完成

tools:
  default: deny              # 未注册工具禁止执行

  file_read: auto            # 限定在授权目录内
  file_write: auto           # 限定目录，写入前保存版本
  file_delete: confirm       # 展示具体删除对象
  git_commit: auto           # 限定仓库，校验待提交内容
  git_push: confirm          # 展示远端、分支与提交范围
  shell_exec: confirm        # 审批具体命令，执行仍受沙箱限制
  api_call: auto             # 仅允许已登记的只读端点
  api_mutate: confirm        # 展示资源、参数及变更范围

approval:
  bind_to: [task_id, call_id, tool, args_hash]
  on_rejected: handoff
  on_args_changed: reapprove # 参数变化后重新审批

2. 上下文与记忆｜Context & Memory

上下文窗口有限，持续追加历史会增加成本和噪声；压缩或截断又可能遗漏关键约束。跨会话任务还需要保存进度和经验。这个模块负责让模型在每一次调用时获得足够、相关且可信的信息。上下文与记忆模块核心是要实现：

上下文构建：选择系统指令、任务目标、相关知识和近期工具反馈
任务状态管理：保存已完成步骤、待办事项、产物引用和检查点
记忆管理：维护用户偏好、业务事实和经过验证的操作经验
信息生命周期：处理来源、权限、过期、冲突、更新与删除

不同的数据与信息需要采取不一样的存储方式，例如检查点负责恢复执行，长期记忆负责复用信息。这也对应 LangGraph 的两类持久化机制：Checkpointer保存线程执行状态，Store保存跨线程数据。

存储类别	保存内容	推荐存储	主要用途
任务状态与检查点	目标、约束、执行步骤、待审批调用、产物引用、当前版本	PostgreSQL	断点恢复，确保任务连续性
会话与执行记录	用户消息、工具结果、验证反馈、事件序号	PostgreSQL；大型内容引用对象存储	还原上下文，为摘要与经验提取提供来源
长期记忆	用户偏好、项目事实、历史案例、已验证经验	PostgreSQL＋pgvector	跨任务检索与复用
原始文档与产物	文档、图片、代码快照、报告、完整工具输出	对象存储；数据库保存元数据	保留原始证据，按需读取

除了上述几个上下文信息存储，我们可能还需要将项目上沉淀的CLAUDE.md与AGENTS.md也整合到持久化存储中来，将项目中的一些稳定通用的约定通过统一的上下文构建器输入给大模型：

context-memory-architecture

3. 路由与模型选择｜Routing & Model Selection

不同任务对能力、成本、时延和数据处理位置的要求不同。统一使用高成本模型可能浪费资源，统一使用轻量模型又可能降低复杂任务的成功率。模型服务也可能超时、限流或不可用，需要统一管理调用与回退。其核心职责如下：

能力匹配：按任务选择推理、视觉、长上下文或工具调用能力
硬约束筛选：检查数据处理区域、上下文长度、输出格式和预算要求
调用与回退管理：统一接口、响应格式、限流、超时和故障回退
成本控制：统计用量，在质量要求允许的范围内选择合适模型

模型路由一般分为两个步骤：首先需要根据当前的约束条件排除不符合要求的模型，这些约束可能包括输入只有图片不包含文本但模型不支持图片输入、指定的输出格式、上下文可能超过模型上限、模型 Token 预算不足等；第二步则是根据任务规则从候选集合中选择合适的模型，可以根据不同的任务类型来匹配对应的模型，具体可以参考LiteLLM Routing & Load Balancing。

routing-model-selection-diagram

4. 验证闭环｜Verification Loops

模型生成了答案，或者工具返回执行成功，都不代表业务目标已经达成。例如，文件成功写入不等于内容正确，程序可以运行不等于满足需求。这个模块负责提供明确的完成依据，并把失败转化为可用于纠错的反馈。通常有如下几类结果与产物需要进行校验：

接口检查：校验输出结构、必填字段和工具参数
结果验证：执行测试、规则校验和业务一致性检查
任务验收：逐项判断是否满足目标和交付标准
纠错反馈：返回失败项、证据和可重试性，由编排模块决定下一步

对于每一项检查都需要明确检查的契约：具体检查什么、使用什么证据、哪些条件必须通过、无法验证时怎么办，一般由业务规则、用户需求与任务类型共同确定，并绑定版本号。验证器可以采用分层设计的方式，从结构验证（数据的格式）、规则验证（状态转换、字段一致性、业务不变量），到执行验证（编译、测试、接口行为、业务状态）、语义验证（内容完整性、需求覆盖、论据与结论一致性），最后是人工验证，对高风险结果、论据冲突等进行人工审核。

verification-loops-diagram

5. 安全护栏｜Guardrails

Agent会读取不可信内容，并将模型输出转化为实际操作。提示注入、参数错误或权限配置不当，都可能导致越权访问和错误执行。提示词中的限制需要由系统权限和执行环境共同落实。安全护栏子系统主要负责：

身份与授权：识别用户、Agent和租户，限定可访问的数据与工具
行动审批：对高风险操作、批量修改和外部发送设置审批条件
数据保护：管理敏感信息、凭据和外发范围
执行隔离：限制文件、网络、进程、资源及运行时长

实际设计方案时，需要包括身份与请求校验、策略决策器（根据执行动作、资源、身份和环境返回授权结论）、审批管理（展示操作影响、复核权限和审批）、授权执行网关（阻止绕过检查的调用，复核权限和审批）、数据出入控制（检查敏感信息、数据来源和外发目的地）以及运行时隔离（通过沙箱限制任务执行时文件、网络、进程等资源的使用）等几个模块。

guardrails-system-diagram

6. 可观测性｜Observability

长程任务可能经过多轮模型调用、检索、工具执行和重试。只看最终答案，难以判断失败源于上下文、模型选择、工具异常还是验证规则，也无法准确计算一次成功任务的实际成本。可观测性模块主要目的就是监控Agent任务执行过程中的状态，比如具体执行了什么操作，发生了何种异常，消耗了多少 Token，任务执行状态如何等，为运行监控、故障分析定位和持续改进提供证据。

链路追踪：记录模型、工具、检索和验证之间的调用关系
状态记录：保存关键状态变化、审批与异常事件
指标统计：跟踪成功率、时延、Token、费用、重试和人工介入率

可以采用 Trace、Metric、Log 三类基础信号，并增加明确的业务事件与产物引用。OpenTelemetry 提供这些信号的统一采集与关联基础。

数据类别	主要内容	解决的问题
执行链路 Trace	模型、检索、工具、验证之间的调用关系与耗时	时间花在哪里，哪一步引发后续失败
运行指标 Metric	请求量、错误率、时延、Token、费用、队列长度	系统是否异常，趋势如何变化
结构化日志 Log	错误码、异常摘要、服务与版本信息	具体发生了什么错误
业务事件 Event	任务开始、等待审批、恢复、验证失败、交付	任务处于什么状态，为什么停住
证据引用 Artifact	输入快照、工具输出、代码版本、测试报告	如何核对和解释结果

observability-system-diagram

7. 反馈与自我改进｜Feedback & Self-Improvement

验证闭环能够纠正当前任务，但如果经验没有沉淀，后续任务仍可能重复犯错。模型、工具和业务规则也会变化，需要持续衡量现有策略是否有效。这个模块负责把运行中积累的证据，转化为经过验证、可发布、可回滚的系统改进——改进的对象是上下文策略、长期记忆、任务编排、模型参数和提示词，改进的效果则用成功率、成本、时延和人工介入率来衡量：

案例沉淀：收集成功路径、失败轨迹和人工纠正记录
问题归因：识别记忆遗漏、提示词缺陷、路由不当和工具问题
策略优化：更新记忆、提示词、工具描述、编排和路由策略
评测与发布：通过回归评测、版本管理和灰度验证控制变更量

feedback-self-improvement-diagram

总结

自从 ChatGPT 出现以来，我们可以说Harness工程已经走过了五个阶段：L0 对话助手（Prompt＋模型）→ L1 工具Agent（模型＋工具）→ L2 受控Agent（权限＋沙箱＋审计）→ L3 长任务Agent（状态＋制品＋恢复）→ L4 生产系统（评测＋治理＋持续优化）。要想让大模型成为一个可持续产出的大脑，提升企业、组织效能，构建一个稳定可靠、能持续改进的Agent系统势在必行。

再回顾一下最开始的定义，Prompt工程研究如何向模型提出一个好问题；上下文工程研究模型在每一步应该看到什么；Harness工程研究如何为模型构建一个能够持续行动、获得反馈、控制风险并完成目标的世界。

模型能力越高，Harness越不会消失。那些专为修补模型缺陷而存在的补丁会被淘汰，但环境、工具、权限、验证和反馈闭环只会越来越重要。未来企业Agent之间的竞争，不仅是模型能力的竞争，更是Harness工程能力的竞争。 模型是买来的，Harness是自己建的——后者才是壁垒。而且只有Harness的改进是复利的：Prompt修正每次对话都要重新施加，上下文配置随语料增长而退化，只有结构性改进（一条 linter 规则、一道权限边界）会一直生效。

单Agent的Harness成熟之后，多个Agent开始分工、通过 A2A 协作、形成数字员工、数字公民与Agent组织，最终靠运行数据、评测和反馈实现自我改进——这是下一篇《Agent系列之三》要讨论的话题。