拆解Agent Harness的11大核心组件与工程实践（附下载）

很多开发者在做智能体落地时，应该都遇到过类似的困境：在简单的演示场景下，靠着ReAct循环、几个基础工具和一套精心设计的提示词，Agent跑得稳稳当当，效果看起来相当不错。可一旦任务复杂起来，需要十几步甚至更多操作的时候，系统就开始各种出问题——要么卡住不动，要么答非所问，要么直接崩溃。

大多数人的第一反应是：模型不够强，换个更大的模型试试。但大量行业实践和研究给出的结论恰恰相反——

。

LangChain在TerminalBench 2.0上的实战数据就是最好的佐证：在模型权重、模型本体完全不变的前提下，仅仅优化了大模型外围的那层基础设施，他们的产品就从30名开外一路跃升至第5名。这套决定Agent性能、处于大模型外层的系统设施，正是行业目前公认的

。

一、Harness的核心定义与核心逻辑

Harness其实不算一个全新的概念，相关技术雏形早就存在了，只不过到2026年初行业才把它标准化、统一了定义。简单来说，它就是大模型之外的那套完整的软件基础设施——包括编排循环、工具集成、记忆系统、上下文管理、状态持久化、异常处理、安全防护等所有核心能力。

LangChain的核心开发者Vivek Trivedy有句话说得特别清楚：

换句话说，我们平时说的Agent，是模型依赖基础设施产生的一种涌现行为——它是面向用户、具备目标导向、能调用工具、会自我纠错的交互实体。而Agent Harness，是承载和驱动这种自主智能行为运行的底层系统架构。

研究者Beren Millidge在2023年的一篇文章中，用计算机硬件架构做了一个非常精准的类比，让Harness的定位一目了然：

• 原生大模型相当于一个没有内存、没有硬盘、没有输入输出的空白CPU——只有计算能力；
• 上下文窗口相当于高速内存，读写快但容量有限；
• 外部数据库相当于硬盘存储，容量大但读取速度慢；
• 工具集成相当于硬件设备的驱动程序；

• Agent Harness就是整套Agent的操作系统
  ，统筹调度所有硬件资源和运行流程。

二、生产级Agent Harness的11个核心组件

结合Anthropic、OpenAI、LangChain等主流厂商的技术方案和行业实践，一套真正可落地、可量产的Agent Harness，至少需要包含11个独立又协同工作的核心组件。

1. 编排循环（The Orchestration Loop）

这是整个Agent的心脏，核心就是实现

——也就是行业里常说的ReAct循环。完整的运行逻辑是：组装输入提示词 → 调用大模型 → 解析模型输出 → 执行工具调用 → 反馈运行结果，循环往复直到任务完成。

从代码层面看，它本质上就是一个while循环，实现起来并不复杂。真正的复杂度在于对整个流程的管控。Anthropic把它定义为一个“dumb loop”——所有智能推理能力由模型承担，Harness只负责管控任务轮次、串联全流程。

2. 工具系统（Tools）

工具是Agent落地操作的“双手”。开发者通过定义工具名称、功能描述、参数类型等结构化信息，把工具能力注入模型上下文，让模型知道它可以调用什么资源、怎么用。

工具层的核心能力包括：工具注册、参数校验、信息提取、沙箱安全执行、结果捕获、结果格式化适配模型读取。主流产品都有非常成熟的工具体系——Claude Code覆盖了文件操作、搜索、代码执行、网络访问、代码智能分析、子Agent生成六大类工具；OpenAI Agent SDK支持函数工具、托管工具、MCP服务器工具等多种类型。

3. 记忆系统（Memory）

Agent的记忆分为短时记忆和长时记忆两大维度，覆盖不同的运行场景：

• 短时记忆
  ：单一会话内的对话历史，支撑单次任务的连贯执行；

• 长时记忆
  ：跨会话持久化存储的信息。Anthropic依托CLAUDE.md、MEMORY.md文件实现长效记忆；LangGraph采用命名空间结构化JSON存储；OpenAI基于SQLite、Redis实现会话持久化。

其中Claude Code采用的三层记忆架构非常值得关注：轻量化索引常驻内存、详情文件按需加载、原始对话记录仅检索调用——既兼顾了响应速度，又不会浪费存储资源。

4. 上下文管理（Context Management）

绝大多数Agent的隐性故障，根源都出在上下文衰减上。实测数据显示，关键信息一旦落在上下文窗口的中间位置，模型性能会直接下降30%以上。即便现在很多模型支持百万级的token窗口，随着上下文不断扩容，模型的指令遵循能力也会持续退化。

生产级Harness主要通过四大核心策略来解决这个问题：

• 信息压缩
  ：临近窗口上限时，主动总结对话历史，只保留核心决策信息和未解决问题，剔除冗余的工具输出；

• 观测屏蔽
  ：隐藏过期的工具运行记录，保留调用轨迹，精简掉无效信息；

• 按需加载
  ：只加载轻量化的标识，动态调取所需数据，避免把整个文件都塞进上下文；

• 子Agent委派
  ：让子Agent完成详细探索后，只返回1000-2000token的精简结果，大大减轻主上下文的压力。

上下文管理的核心目标其实就一句话：

5. 提示词构建（Prompt Construction）

这个组件负责每一轮模型输入的分层组装。一个完整的输入包含系统提示词、工具定义、记忆文件、对话历史、当前用户指令五大模块，而且有严格的优先级层级。比如OpenAI Codex的优先级是：服务端系统指令最高，然后依次是工具定义、开发者指令、用户指令、对话历史——确保核心规则不会被意外覆盖。

6. 输出解析（Output Parsing）

现在的Agent Harness都采用原生工具调用机制，模型直接输出结构化的tool_calls对象，不再需要人工去解析自由文本。Harness只需要做标准化的逻辑判断：有工具调用就执行对应操作继续循环，没有就输出最终结果。

而且OpenAI、LangChain都支持基于Pydantic模型的结构化输出约束。对于极端场景，也保留了错误重试解析机制——把错误日志反馈给模型，让它自己修正输出。

7. 状态管理（State Management）

状态管理负责Agent全流程数据的记录、更新与持久化，支持任务中断恢复和回溯调试。不同框架的实现方式各有特色：LangGraph通过结构化字典存储状态、聚合更新数据，在关键步骤实现断点存档；OpenAI提供了四种独立的状态管理策略；Claude Code则创新性地通过Git提交记录作为断点、进度文件作为临时工作台，实现了状态留存。

8. 异常处理（Error Handling）

复杂任务中，异常的累积效应非常强：一个10步流程，即便每一步的成功率高达99%，最终的整体成功率也只有90.4%。所以完善的异常处理是生产级Agent的必备能力。

行业主流的方案是把异常分成四类来分别处理：瞬时异常用退避重试机制；模型可修复的异常，把错误日志返回给模型让它自主调整；用户可修复的异常，暂停任务等待人工介入；未知异常直接上报用于调试。同时，主流产品都会限制重试次数，避免无效的资源消耗。

9. 安全防护与边界管控（Guardrails and Safety）

安全体系分为三层防护，覆盖Agent的全运行流程：输入防护拦截违规的初始指令，输出防护校验最终结果的合规性，工具防护管控每一次工具调用行为。

Anthropic采用了一种决策与执行分离的架构：模型只决定“尝试做什么”，而工具系统决定“允许做什么”。Claude Code对40多项工具能力进行了独立管控，通过项目初始化授信、调用前权限校验、高危操作人工确认三步机制，全方位规避风险。

10. 验证循环（Verification Loops）

验证循环是Agent落地的关键能力，用来解决模型输出失误、任务执行偏差等问题。行业主流采用三种校验方式：基于规则的自动化校验（测试、代码检测、类型校验）；可视化校验（对UI任务进行截图核验）；模型裁判校验（用独立子Agent评估输出结果）。

Claude Code的创始人曾提到一个数据：给Agent增加自主校验能力，可以直接把任务完成质量提升2-3倍。

11. 子Agent编排（Subagent Orchestration）

面对超复杂的任务，Harness支持把任务拆解成多个子任务，交给多个Agent协同执行。Claude Code提供了镜像复制、独立协作、隔离分支三种执行模式；OpenAI支持子任务专属Agent和任务全权移交两种协同方式；LangGraph则通过嵌套状态图实现子Agent管控，让复杂任务分层拆解、高效落地。

三、Agent Harness的完整运行流程

了解了各个组件，再来看看它们在实际运行中是怎么协同工作的。

Harness整合系统指令、工具规则、记忆信息、对话历史、用户当前指令，同时遵循“首尾重点信息优先”原则——把核心任务信息放在提示词的开头和结尾，避免信息在中间衰减。

组装好的提示词发送到大模型API，模型输出文本内容或工具调用请求。

如果没有工具调用，直接结束任务、输出结果；有工具调用就进入执行流程；如果存在任务移交需求，就更新Agent身份，重新启动循环。

Harness先校验工具参数、核对操作权限，然后在沙箱环境中执行工具调用。只读操作并行执行，修改性操作串行执行，避免数据冲突。

将工具运行结果标准化处理，捕获所有异常信息并封装成可读格式，反馈给模型——为模型的自我纠错提供依据。

将本轮运行结果录入对话历史。如果接近上下文窗口上限，自动触发信息压缩，精简冗余内容。

回到第一步重新启动流程，直到满足终止条件。任务终止的场景包括：无工具调用的最终输出、达到最大轮次、token资源耗尽、安全规则触发、用户主动中断等。

对于需要跨窗口的超长任务，Anthropic推出了双阶段Ralph循环模式：初始化阶段的Agent搭建运行环境、生成初始记录，后续会话的Agent读取历史进度、接续完成任务——依靠文件系统实现了跨上下文的任务连续性。

四、主流框架的Harness实现方案

目前主流的Agent框架都是基于Agent Harness核心逻辑搭建的，但实现方式各有侧重：

• Anthropic Claude Agent SDK
  ：通过一个query()函数暴露Harness，创建一个异步的循环并返回一个流式消息的迭代器。核心就是dumb loop——所有智能都在模型里，Harness只负责流程调度。Claude Code使用的是收集-行动-验证（Gather-Act-Verify）循环。

• OpenAI Agents SDK
  ：通过Runner类实现Harness，支持异步、同步和流式三种模式。核心理念是代码优先，工作流逻辑用原生Python表达。Codex Harness则采用三层架构，所有客户端共享同一个Harness——这也是为什么Codex模型在Codex界面上的体验比在通用聊天窗口里更好。

• LangGraph
  ：把Harness建模成一个显式的状态图。一个“LLM节点”和一个“工具节点”通过条件边连接起来。LangGraph是从LangChain早期被弃用的AgentExecutor演变而来，解决了它难以扩展和缺乏多智能体支持的问题。其Deep Agents明确使用了Agent Harness这个术语。

• CrewAI
  ：实现了一种基于角色的多Agent架构，通过Harness定义Agent的角色、目标、工具，再搭配流程管理层实现任务路由、结果校验，支撑多Agent自主协作。它的Flows层作为确定性骨干提供支持，在Crews处理自主协作的同时管理路由和验证。

五、Harness工程的七大核心选型

所有Harness架构设计，都需要在七大核心选型上做出权衡——它们直接决定了Agent的性能和落地适配性：

• 单/多Agent选型
  ：Anthropic和OpenAI都建议优先最大化单个Agent的能力。多Agent系统会带来额外开销——额外的LLM调用、交接时的上下文丢失。只有当工具数量过多（比如超过10个且功能重叠）或存在清晰独立的任务领域时，才考虑拆分。

• 运行循环选型
  ：ReAct循环灵活度高，但逐步迭代成本也高；规划-执行架构可以大幅提升运行速度，最高能实现3.6倍的效率提升。

• 上下文管理策略
  ：五种生产级策略包括基于时间的清除、对话总结、观察屏蔽、结构化笔记和子Agent委派。ACON的研究表明，通过优先保留推理轨迹而不是原始工具输出，可以减少26%-54%的token消耗，同时保持95%以上的准确率。

• 验证循环设计
  ：计算性验证（如测试、Linters）提供确定性的事实依据；推理性验证（LLM作为裁判）能捕捉语义问题，但会增加延迟。

• 安全权限策略
  ：根据场景选择宽松模式（高效但有风险）或严格模式（安全但效率低）。

• 工具范围管控
  ：遵循最小可用原则，精简工具数量、按需加载工具，避免工具过多导致模型决策混乱。

• Harness轻量化程度
  ：长期趋势是Harness越来越轻量——把核心决策能力交给模型，自己只保留基础调度、安全和校验能力。

六、小结

在大模型同质化越来越严重的今天，同样的模型，配上不同的Harness，做出来的Agent产品性能差距可以达到数十倍。

Agent Harness不是简单的封装工具，也不是标准化的通用组件——它是一套包含资源调度、误差修复、记忆管理、安全管控、自主校验的全套复杂工程体系。整个行业的长期趋势是Harness持续轻量化，因为模型本身在变得越来越强。但Harness本身不会消失——即使是最强大的模型，也仍然需要一个系统来管理它的上下文窗口、执行它的工具调用、持久化它的状态、验证它的工作成果。