从理论到实战：Agent 工程师必备的 Harness 能力

公众号名称：居丽叶的大模型视界

作者名称：居丽叶

发布时间：2026-06-10 11:45

大家好，我是居丽叶。

前几天发了一个agent harness的项目，里面还提到近期就业市场上也出现了很多harness相关的岗位：

刚入门的同学就要问了，harness是啥啊？看过医疗Agent项目的同学说，harness就这？

之前也写过一篇《从 Claude Code 源码解析 Harness》，因为claude code本身就是一个完整的、工业化的harness实现参考。

今天这篇文章就让我们一起来看看一篇最近发的harness的综述：Agent Harness Engineering: A Survey，来做一些更深入的讨论吧！

链接：https://openreview.net/pdf?id=eONq7FdiHa

什么是Harness？

在深入综述之前，让我们先来对齐一下Harness的定义。

Harness这个词来自马具。马具的作用是精确地把马的力量引导到正确的方向，防止失控，让骑手保持控制权。Harness Engineering对LLM的作用完全类比：让模型的能力被可靠地驾驭。

LangChain的Vivek Trivedy给了一个最干净的定义：Harness就是模型权重以外的一切，即 Agent = Model + Harness。

但这个定义好像说了什么又好像什么都没说，于是论文给出了更精确的工程定义。他们提出，Agent Harness是”将模型调用转化为有边界、有状态、工具中介的任务执行的工程化包装层”——包括执行基板（Execution）、工具接口（Tool）、上下文控制（Context）、编排（Lifecycle / Orchestration）、可观测性（Observability）、评估反馈（Verification）和治理约束（Governance）。

这七个层面，就是综述论文提出的ETCLOVG七层分类法。

这个定义把 Harness 定位为独立的系统层，相当于是把 Agent 开发从“模型中心”拉回了“系统中心”。

接下来，我们就针对这七个层级，进行逐一分析。

E（Execution） — 执行环境与沙箱

执行环境是Agent Harness的运行载体——Agent的代码跑在哪里，受什么约束。

论文把沙箱分为七类：通用托管沙箱（Daytona、E2B）、计算机操作Agent基础设施（Claude Computer Use）、代码专用沙箱（Judge0、CodeInterpreter）、框架集成运行时（OpenHands）、浏览器评估环境（WebArena）、OS级权限沙箱（bubblewrap/Seatbelt）、以及沙箱抽象层（SWE-ReX）。

七个类别背后，真正的设计维度不是用了什么隔离技术（Docker、microVM、WASM），而是三个问题：安全边界画在哪里？可复现的成本是多少？以及在多大程度上让Agent自主行动？

这里有一个工程细节特别值得关注：沙箱不仅是笼子，也是许可证。 Anthropic报告说，引入sandboxing后，Claude Code的权限弹窗减少了84%。原因是：当Agent在一个受限区域内被允许自由行动时，每步都要请示人类的死锁就被打破了。安全靠的是会话级别的配置，不靠用户每一步的确认。

这对做Agent产品的团队来说是一个重要的架构启示：沙箱设计将会直接决定用户体验的重要指标——Agent能在多长的时间内不需要打断人类继续执行任务。

T（Tool） — 工具接口与协议

工具层回答”Agent如何发现、调用和选择外部能力”，它位于两个矛盾目标之间：暴露更多工具提升能力覆盖，还是保持工具集精简化以保护决策质量？

论文按集成边界划分了四个层次：

Model ↔ Function（函数调用、OpenAI function calling）
Agent ↔ External capability（MCP、OpenAPI）
Agent ↔ Agent（A2A、ACP/ANP）
Agent ↔ Repo/environment（AGENTS.md、CLAUDE.md）

这四个边界各自解决不同的问题，不能互相替代但可以一起工作。很多团队一开始只关注第一个（函数调用），直接用Function Calling解决所有问题，后来发现工具一多模型就混乱，于是引入MCP做工具治理；再后来发现多Agent之间切换职责是个新问题，又加上A2A。四个边界的演化是与系统复杂性同步的。

一个更底层的工程洞察是：工具的选择本身就是 Agent 的意图信号，我们同时可以借此更轻松地做好权限管控。比如Claude Code没有把文件操作合并成一个”FileOperation”工具，而是拆成Read/Write/Edit三个独立的工具。模型选了Edit意味着局部修改，选了Write意味着全量覆写。工具粒度做得细，意味着权限控制也可以更细——只读权限允许Read但不允许Write。这个视角和论文中的设计原则吻合：更少但更好的工具往往优于暴力暴露更多工具。

C（Context） — 上下文与记忆管理

过去几年，LLM 工程落地经历了三次重心迁移。

第一阶段是 Prompt Engineering。这个阶段的问题是：怎么让模型听懂一句话？工程师主要在打磨 system prompt、角色设定、输出格式、few-shot 示例。任务通常比较短，几分钟就能完成，模型记性差一点也没关系，因为系统状态并不复杂。
第二阶段是 Context Engineering。模型开始处理更长任务，RAG、工具调用、多轮对话变多，问题变成：模型在每一步应该看到什么信息？于是检索增强、上下文压缩、工具调用结果排序、长期记忆，成了主要工程课题。这个阶段的隐含前提是：只要把正确材料放进上下文，模型就能做对。
第三阶段才是 Harness Engineering。任务不再只是让模型看到正确材料，而是让模型在真实世界里连续行动几十步、上百步，甚至运行数小时。这时候问题变成：执行环境是否隔离？状态怎么持久化？失败怎么归因？人类在哪里接管？工具调用是否可审计？错误动作是否能撤回？

这种升级里面体现的是工程对象的变化。Prompt Engineering 优化的是单次模型调用，Context Engineering 优化的是多步上下文构造，Harness Engineering 优化的是整个执行系统。

现阶段 Agent 工程师的核心竞争力就是能不能把模型包进一个可执行、可观测、可验证、可治理的系统里。

这篇论文中把上下文管理按时间维度分层：短期（活跃上下文窗口）、中期（会话状态和跨运行持久性）、长期（持久化记忆系统）。

短期管理有三条反直觉的实验结论：

U型注意力曲线

在多文档QA中，把相关信息放在上下文中间位置，准确率比放在开头或结尾低30%以上。信息位置和信息存在一样重要。

上下文腐烂（Context Rot）

Hong et al. (2025) 评估了18个前沿模型，所有模型随着输入增长都出现了性能退化。关键发现：退化在窗口远未填满时就开始——一个标称200K的模型可能在50K时就出现显著性能下降。对于Agent来说，这是每天累积工具输出、中间推理和文件内容后的常见情况。

KV-cache是生产环境最重要的指标

Manus团队经过五轮架构迭代后得出结论：KV-cache命中率是”生产级AI Agent最重要的单一指标”。ClaudeSonnet上，缓存的token成本是$0.30/MTok，未缓存的是$3.00/MTok——差10倍。而缓存命中的前提是：SystemPrompt前缀稳定、上下文追加式构建、JSON序列化确定性。

这三条结论合在一起意味着：上下文不是可以随便堆的。它是一个动态的、每步都需要决策的稀缺资源管理问题。做Agent工程，你得把上下文当成一个稀缺预算来管理。

中期的结构化笔记（Agent自己维护NOTES.md）和跨运行注入（前一次运行的总结注入下一次），以及长期的MemGPT、Mem0、A-MEM、Hindsight等持久化记忆系统，它们的目标都是努力让 Agent 的工作状态与真实任务状态保持对齐。然而，论文指出这些方法目前都失效了。在经过100+轮的长期任务后，压缩造成的误差复合和检索能力的失效，使得上下文偏移（Context Drift）依然是目前这一层最难、且未被解决的终极挑战。

L（Lifecycle / Orchestration） — 生命周期与编排

编排层涉及的是Agent系统如何把一个任务拆解、执行、交接、恢复——这是最直接影响”Agent能跑多远”的一层。

论文中总结了三种粒度的编排模式：

单Agent内循环：

这是Claude Code、Codex CLI、Aider等系统的基本执行单元。很多团队一上来就搞多Agent，但单Agent循环里的一个核心设计决策往往被忽视：执行是Stateless Replay还是Stateful？

Codex CLI坚持纯Replay——完整匹配重建执行轨迹，牺牲了效率换取了可复现性。而Claude Code、OpenCode等采用Hybrid模式，结合可回放历史和持久化artifact。这些实现细节决定了当这个Agent系统出现故障时，能不能重建当时的执行状态来定位问题。

多Agent编排：

层级式编排（DeerFlow、AutoGen、OpenAI Agents SDK）、团队式编排（oh-my-claudecode）、图编排（LangGraph）、Fan-out（Emdash）。

一个关键洞察来自Anthropic：他们展示了规划器-生成器-评估器的三Agent架构，在Opus 4.5上确实比单个Agent好——但当模型升级到Opus 4.6后，sprint contract和context resets可以直接移除，成本从$200降到$125，质量不降。

这说明：所有编排组件，本质都是用来弥补模型短板。随着大模型能力迭代，原先用来补短板的冗余调度逻辑会慢慢失去价值。

如果你的编排层堆砌了大量为老模型量身定做的补救逻辑，后续升级更强大模型时，这些旧设计不再起作用，反而变成额外开销拖累系统。

O（Observability） — 可观测性与运维

可观测性是论文从Lifecycle Hooks中剥离，提升为独立层的两层之一（另一个是Governance）。做Agent工程的同学对Langfuse、Phoenix、OpenLLMetry这些工具不陌生了。但我想重点讲这个层面对工程设计的两个启示：

只看不判

LangChain 2026年的调研显示，89%的团队在用可观测性工具，但只有52.4%在做离线评估。这意味着：绝大多数团队只能通过 Trace 看到 Agent 做了什么，却无法系统地判断这些行为是对是错。Trace 只是原材料，评估（Evaluation）才是加工厂。如果没有后端的判别机制，你得到的永远只是一堆流水账日志，而不是能指导系统迭代的有效认知。可观测性必须与评估闭环打通，否则毫无意义。

警惕基准分数的海市蜃楼

Anthropic的一项研究发现，基础设施配置本身就可以让基准分数偏移6个百分点（p<0.01）。这意味着你费尽心血优化了 Prompt、重构了 Tool、精简了 Memory，最终成功率涨了 6%。先别急着庆祝——这 6% 可能只是沙箱环境恰好稳定了。做 Agent 可观测性，必须把环境状态、测试脆弱性、甚至网络延迟等”基础设施噪声”纳入监控。否则，你的优化可能只是在拟合环境的随机误差。

每一个 Harness 组件，都代表着一个对模型自身能力不足的妥协。

V（Verification） — 验证与评估

这一层我着重要讲的是”从打分转向诊断”。传统LLM评估是一个分：输入→输出→打分。Agent评估是一个Episode：任务嵌入环境→Agent与环境交互（多步）→工具调用和状态变化→轨迹全量捕捉→多级评判→失败归因。

论文中提炼的五阶段评估生命周期（任务落地→执行前准备就绪验证→受控执行和轨迹捕获→多级评判和失败归因→持续回归和部署反馈），其中最关键的是Stage4多级评判和失败归因。

因为一次失败的Agent运行可能来自：模型推理错误、工具描述误导、沙箱配置错误、上下文陈旧、测试用例flaky、基准规格模糊、评分器不稳定、编排循环bug。

如果不做失败归因，你看到的所有”模型准确率”数字都是有污染的。

对于Agent开发工程师来说，这意味着：

评估应该分三层做：结果级（任务完成了吗）、轨迹级（怎么完成的、是否高效合规）、评分器级（这个评分本身可信吗）
确定性检查（工具调用格式、schema验证）和LLM语义判断（幻觉、plan-action对齐）应该分层组合
生产trace应该能回灌到评估中作为回归用例

G（Governance） — 治理与安全

治理是综述论文提升为独立层的第二个领域。这一层包括五个机制：权限模型、生命周期Hook、组件自身加固、声明式宪章，以及防篡改的审计日志。

值得关注的工程要点：

权限不能只按工具名判断，而要按上下文判断。

在传统系统里，权限经常是静态的：某个用户能不能用某个工具。但 Agent 的风险往往取决于“这次调用具体想干什么”。同样是写文件，写临时日志和覆盖生产配置不是一个风险等级；同样是发邮件，给自己发测试邮件和给外部客户发正式邮件也不是一个风险等级。

Progent 的思路是用领域特定语言 DSL 描述权限规则，让规则可以引用工具名、参数和环境状态。也就是说，权限不再是启动时声明一次的静态配置，而是在每次工具调用前动态求值的谓词。这和Claude Code的五道权限链（参数校验→PreToolUse Hooks→规则匹配→工具自检→AI classifier）异曲同工，层层判断这次动作能不能放行。

Hook 不是越多越安全。

Hook 可以在工具调用前后插入校验、拦截、改写和审计，是 Agent governance 里最常见的工程手段。但多个 Hook 叠加以后，可能产生副作用：上游 sanitizer 改写了输入，下游 detector 依赖的攻击信号被抹掉，最后系统看起来多了一层防护，实际检测能力反而变弱。比如，你最前面挂了一个“敏感词过滤插件”，它把输入里的危险指令给替换成了星号；结果导致排在后面的“恶意攻击报警插件”根本认不出这是个攻击，直接放行了。

所以 Hook 设计不能只看覆盖率，还要看 Hook 之间的顺序、依赖和信号保真。目前研究者还没有对这种叠加效应做出系统分析，这也是 Agent 安全管线里一个很容易被低估的问题。

治理要做分层防御，不能把安全性压在单一环节上。

理想的 Agent 应该有分层防御（模型够安全 + 工具加签验证 + 运行时层层 Hook + YAML 写的宪章规则 + 完整的审计日志）。但理想很丰满，现实很骨感。Kim 等人给市面上最出名的 6 个主流系统（包括 Codex、Gemini CLI、OpenHands 等）做了个全身体检，结果很尴尬：没有一个系统实现了完整的防御闭环。特别是在高级防御机制上——比如防止脏数据污染核心决策的信息流控制，以及弄清楚多 Agent 协作时”到底是谁下达了操作授权”的”身份管理”——目前所有的头部框架统统交了白卷。

四个跨层的工程权衡

梳理完 ETCLOVG 七大层级后，我们来看落地过程中四大核心跨层难题：

成本 - 质量 - 速度的三角困境

更强的沙箱能够提升安全性，但会增加启动延迟；更丰富的上下文可以保障任务连续性，却会拉高 Token 与检索开销；更完善的评估和观测体系有助于问题诊断，但会拖慢迭代速度。

核心问题是能否承受多层同时优化带来的综合成本。在实际落地中，团队需要界定各类检查是同步执行还是异步执行，同时判断哪些故障值得投入高成本去修复。

还有一个细节：为了解决问题而堆砌更长的系统提示词、更繁杂的工具描述、体量更大的上下文，会直接增加推理成本。Token 本身不只是计费单位，更是无效噪声。对于上下文窗口而言，每增加一个 Token，都会稀释模型的注意力密度。

能力与控制的权衡

开放更多工具、放宽权限、启用长效记忆，能让 Agent 处理更复杂的任务，但也会同步扩大安全攻击面。表面看这是安全与实用性的博弈，本质上存在更深层的工程逻辑。

工具列表越庞大，不仅越容易触发提示注入攻击，还会提升模型的决策错误率。工具集合是 Agent 的决策空间，菜单越繁杂，模型每一步的规划难度就越高。

因此，精简工具不只是出于安全考量，更是提升系统可靠性的工程选择。将工具收敛到最小必要集合，能够有效降低决策的不确定性。

Harness 耦合问题

这是我认为整篇综述里最深刻的一个观点。

执行环境的变动会影响最终评测结果（依赖包可用性、环境重置规则、延迟、故障模式都会随之改变）；工具描述会占用上下文空间，与其他内容形成资源竞争；观测轨迹只有和权限、身份采用同等精细度采集，才能作为治理审计的有效依据；评估规则也会通过奖惩不同执行逻辑，反向影响整体编排策略。

这就意味着，对 Harness 做任何改动，都必须以全系统视角测试，不能仅针对单个组件验证。单独优化提示词、工具设计、记忆模块、沙箱配置，看起来效果良好，但整合进整套控制系统后，反而可能拖累整体表现。

这也解释了为什么脱离 Harness 环境去讨论模型跑分，几乎没有参考价值。评测分数是模型 + Harness共同作用的结果，而非模型单独的能力体现。修改上下文策略这类 Harness 配置，等同于更换了模型的运行控制器，模型行为也会随之改变。这正是论文中「绑定约束理论（binding-constraint thesis）」的工程释义。

从开发单Agent框架到运营 Agent 集群

行业正在发生范式转变：大家的建设重心，正从单一 Agent 框架转向规模化 Agent 平台。

传统框架仅提供模型调用、工具、内存、基础执行能力；而成熟的 Agent 平台，会额外集成持久化工作空间、托管沙箱、身份认证、计费、观测、合规治理、人机交接等全套运营能力。

开放问题与未来方向

论文的最后提出了五个开放问题，我挑选了对Agent开发工程师最有启发的三个来讨论：

长期运行的 Agent 如何维持可靠状态

长周期 Agent 的难题在于：每一次上下文压缩、信息检索、内容淘汰的过程中，会产生多少信息损耗，以及我们能否对这类损耗进行管控。

每一轮摘要都会引入细微偏差，多次叠加后，偏差会持续放大，最终导致 Agent 的内部认知与真实任务状态出现偏差，而目前尚无架构可以有效识别这类问题。

对于 Agent 工程团队而言，想要支撑数百轮的长周期任务，不能只依赖传统的文本摘要工具，还需要实现这些能力：

支持携带不确定信息的摘要机制
完整的事实溯源能力
内容过期标记能力
依托代码、文件等持久化产物重建任务状态，而非单纯依赖压缩后的历史记录

模型升级后，Harness 怎么跟着升级

模型越强，Harness 就越该简化，这是一条经过实践验证的基本原则。

前面L（Lifecycle / Orchestration）中也提到过Anthropic 的发现：模型从 Opus 4.5 升级至 Opus 4.6 后，原本为弥补模型短板设计的上下文重置、评估反馈链路都不再必要。移除这些组件后，任务效果保持不变，运行成本却从 200 降至 125。

这引出了Harness 自主精简的工程需求。当模型能力迭代升级后，我们需要一套机制，区分仍在生效的管控逻辑和已经冗余的辅助组件。理想的落地方式为：

在影子模式并行运行多个不同复杂度的 Harness 版本（影子模式：线上正式业务不变，同时后台静默并行跑多套 Harness 方案，不影响用户使用，用来做对比测试）
在效果一致的前提下，筛选成本最优的方案
Harness 工程的目标是做到恰到好处的设计

如何从 Agent 的 Trace 中诊断故障

目前绝大多数 Agent 评估体系，都停留在 “成功 / 失败” 的二元判断层面。行业数据显示：64.7% 的团队可以实现链路观测，但仅有 52.4% 会开展系统化评估。

这就导致很多场景下，我们能看到各类运行指标，却无法定位故障根源。

基于链路追踪的评估（Trace-native evaluation）要实现的目标是：任务失败时，不只输出成败结果，而是完成故障诊断 —— 判断问题出在工具描述、上下文丢失、运行环境异常，还是评测规则本身。这样才能告别盲目试错，让迭代优化更有针对性。

给Agent开发工程师的几条takeaway

1.Harness 独立于大模型，绝非配套附属。工具、权限、上下文、编排、观测、评测、安全整套基建，才决定 Agent 长线稳定性。
2.不用一次性落地全七层架构。工程核心是厘清每段组件都是为弥补模型短板而搭建，随着模型变强，及时拆除冗余脚手架。
3.上下文是稀缺资源，不能无限堆砌。信息位置影响效果、内容变长提前出现性能衰减，多余 Token 既抬成本还引入噪声，要像管控预算一样管理上下文。
4.评测不能只盯着最终得分，要落地故障诊断。只知道任务失败、定位不了根源，就等于观测和评测链路失效。
5.Harness 改动要做全系统验证。Prompt、工具、上下文单点优化看似优秀，组合落地后反而拖累整套 Agent 运行。

基于以上整套理论与行业现状，我在我的医疗助手 Agent项目中也实现了一套 Harness 方案。医疗场景具备强合规、长会话、输出规范性要求高的特点，我针对性设计了核心机制：

1.约束驱动（软约束机制）：通过 YAML 配置文件定义 Agent 能力边界、可用技能、输出规范与医疗合规规则。运行时由验证器实时巡检，发现违规调用、缺失免责声明等问题时，仅记录告警日志而不中断会话，在合规要求与服务连续性之间实现平衡。
2.自动修复能力：联动评估校验模块，当检测到输出存在缺陷时自动修正。例如识别到回答缺少医疗免责声明、用户描述胸痛 / 呼吸困难等高危症状却无就医提醒时，系统会自动补充标准提示，规避医疗风险、保障输出合规。
3.熵管理机制：针对短期记忆做专项优化，利用 MD5 哈希去除重复对话，结合滑动窗口压缩历史内容，控制上下文体量；同时内置熵值监控，在对话冗余度过高、系统状态异常时主动告警，有效缓解上下文腐烂与漂移问题。

这套方案跟 ETCLOVG 七层架构中的上下文、治理、评估三个层级也是一脉相承的，是 Harness 工程在强监管垂直领域的典型落地实践，可供合规类 Agent 项目进行参考。

— 完 —

欢迎扫码加入我的知识星球，内含多个Agent大项目

更有完整大模型笔记、八股速记、简历模板

和优秀的同行者们一起入职大模型技术岗

内容效果不满意？点此反馈