Agent Harness 解析：智能体架构深度拆解

这篇文章来自Akshay Pachaar，LightningAI前AI工程师、Daily Dose of DS联合创始人，长期专注于拆解LLM和AI Agent的底层逻辑。深度解析Anthropic、OpenAI、Perplexity和LangChain在构建什么——涵盖编排循环、工具调用、记忆机制、上下文管理，以及将一个无状态的LLM转变为有能力的Agent所需的全部要素，模型能力越来越强，但是Harness不会消失

你搭过一个聊天机器人，接入了ReAct循环，挂了几个工具，演示效果不错。

然后你尝试把它做成生产级产品，问题随之而来：模型记不住三步前做了什么，工具调用静默失败，上下文窗口被垃圾填满。

问题不在模型。在模型周围的一切。

LangChain用一个案例证明了这一点：只改了包裹LLM的基础设施，模型权重完全没动，在TerminalBench 2.0上的排名从30名开外直接跳到第5。另一个研究项目让LLM自己优化基础设施，通过率达到76.4%，超过了人工设计的系统。

这套基础设施现在有了一个正式的名字：Agent Harness。

什么是Agent Harness

这个概念在2026年初被正式命名，但早已存在。Harness是包裹LLM的完整软件基础设施：编排循环、工具、记忆、上下文管理、状态持久化、错误处理、安全护栏。

Anthropic在Claude Code文档里直接写明：SDK就是「驱动Claude Code的agent harness」。OpenAI的Codex团队也用同样的框架，把「agent」和「harness」视为等价概念，专指让LLM变得有用的非模型基础设施。

LangChain的Vivek Trivedy给出了一个清晰的定义：如果你不是模型本身，你就是harness。

很多人容易混淆的区分在这里：「agent」是涌现出来的行为，是用户交互的那个有目标、会用工具、能自我纠正的实体。Harness是产生这种行为的机器。当有人说「我做了一个agent」，他们其实是做了一个harness，然后把它对准了一个模型。

Beren Millidge在2023年的文章《作为自然语言计算机的脚手架LLM》里给了一个精准的类比：裸LLM是没有内存、没有硬盘、没有I/O的CPU。上下文窗口是内存，快但有限；外部数据库是硬盘，大但慢；工具集成是设备驱动；Harness是操作系统。正如Millidge所写：我们重新发明了冯·诺依曼架构，因为这是任何计算系统的自然抽象。

三个工程层级

围绕模型有三个同心圆层级：

提示词工程，负责设计模型接收的指令。

上下文工程，管理模型看到什么、什么时候看到。

Harness工程，包含前两者，再加上完整的应用基础设施：工具编排、状态持久化、错误恢复、验证循环、安全执行、生命周期管理。

Harness不是提示词的包装层，而是让自主agent行为成为可能的完整系统。

生产级Harness的12个组件

综合Anthropic、OpenAI、LangChain和更广泛的实践者社区，一个生产级agent harness有12个独立组件。

1. 编排循环

这是心跳所在。它实现思考-行动-观察（TAO）循环，也叫ReAct循环：组装提示词、调用LLM、解析输出、执行工具调用、把结果反馈回去、重复直到完成。

机制上，这往往只是一个while循环，复杂性藏在循环管理的所有东西里，而不是循环本身。Anthropic把他们的运行时描述为一个「笨循环」，所有智能都住在模型里，Harness只管理轮次。

2. 工具

工具是agent的手。它们以schema形式定义（名称、描述、参数类型），注入到LLM的上下文中，让模型知道有哪些可用。工具层负责注册、schema验证、参数提取、沙盒执行、结果捕获，以及把结果格式化成LLM可读的观察结果。

Claude Code提供六个类别的工具：文件操作、搜索、执行、网络访问、代码智能、以及子agent生成。OpenAI的Agents SDK支持函数工具（通过@function_tool）、托管工具（WebSearch、CodeInterpreter、FileSearch），以及MCP服务器工具。

3. 记忆

记忆在多个时间尺度上运作。短期记忆是单次会话内的对话历史。长期记忆跨会话持久化：Anthropic使用CLAUDE.md项目文件和自动生成的MEMORY.md文件；LangGraph使用命名空间组织的JSON Store；OpenAI支持由SQLite或Redis支持的Session。

Claude Code实现了三层层级：轻量级索引（每条约150字符，始终加载）、按需拉取的详细主题文件、以及只通过搜索访问的原始记录。一个关键设计原则：agent把自己的记忆视为「提示」，在行动前会对照实际状态进行验证。

4. 上下文管理

这是很多agent悄然失败的地方。核心问题是上下文腐烂：当关键内容落在窗口中间位置时，模型性能下降超过30%（Chroma研究结果，得到斯坦福「迷失在中间」论文的印证）。即使是百万token的窗口，随着上下文增长，指令遵循能力也会退化。

生产级策略包括：

压缩：在接近上限时对对话历史进行摘要（Claude Code在压缩时保留架构决策和未解决的bug，丢弃冗余的工具输出）；

观察屏蔽：JetBrains的Junie隐藏旧的工具输出，但保留工具调用可见；

即时检索：维护轻量级标识符，动态加载数据（Claude Code使用grep、glob、head、tail，而不是加载完整文件）；

子agent委托：每个子agent进行大范围探索，但只返回1000到2000 token的压缩摘要。

Anthropic的上下文工程指南明确了目标：找到能最大化期望结果概率的最小高信号token集合。

5. 提示词构建

这一步组装模型在每一步实际看到的内容，是分层的：系统提示、工具定义、记忆文件、对话历史、当前用户消息。

OpenAI的Codex使用严格的优先级栈：服务器控制的系统消息（最高优先级）、工具定义、开发者指令、用户指令（级联的AGENTS.md文件，32 KiB上限），然后是对话历史。

6. 输出解析

现代Harness依赖原生工具调用，模型返回结构化的tool_calls对象，而不是需要解析的自由文本。Harness检查：有工具调用吗？执行并循环。没有工具调用？那就是最终答案。

对于结构化输出，OpenAI和LangChain都支持通过Pydantic模型进行schema约束的响应。RetryWithErrorOutputParser等旧方法（把原始提示、失败的补全和解析错误反馈给模型）在边缘情况下仍然可用。

7. 状态管理

LangGraph将状态建模为流经图节点的类型字典，用reducer合并更新。检查点在超步边界处触发，支持中断后恢复和时间旅行调试。OpenAI提供四种互斥策略：应用内存、SDK session、服务端Conversations API，或轻量级previous_response_id链接。Claude Code采用不同的方式：git提交作为检查点，进度文件作为结构化草稿纸。

8. 错误处理

这一点很关键：一个每步成功率99%的10步流程，端到端成功率仍然只有约90.4%。错误会快速累积。

LangGraph区分四种错误类型：瞬时错误（带退避重试）、LLM可恢复错误（将错误作为ToolMessage返回让模型调整）、用户可修复错误（中断请求人工输入）、以及意外错误（向上冒泡用于调试）。Anthropic在工具处理程序内捕获失败，将其作为错误结果返回以保持循环运行。Stripe的生产Harness把重试次数上限设为两次。

9. 护栏与安全

OpenAI的SDK实现三个层级：输入护栏（运行在第一个agent上）、输出护栏（运行在最终输出上）、工具护栏（每次工具调用都运行）。一个「断路器」机制在触发时立即停止agent。

Anthropic在架构上将权限执行与模型推理分离：模型决定尝试什么，工具系统决定允许什么。Claude Code独立门控约40个离散工具能力，分三个阶段：项目加载时的信任建立、每次工具调用前的权限检查、以及高风险操作的明确用户确认。

10. 验证循环

这是玩具demo和生产agent的分水岭。Anthropic推荐三种方式：基于规则的反馈（测试、代码检查、类型检查器）、视觉反馈（通过Playwright截图用于UI任务）、以及LLM作为评判者（独立的子agent评估输出）。

Claude Code创建者Boris Cherny指出，给模型一种验证自身工作的方式能将质量提升2到3倍。

11. 子agent编排

Claude Code支持三种执行模型：Fork（父上下文的字节级复制），Teammate（独立终端面板，通过基于文件的邮箱通信），以及Worktree（每个agent拥有独立的git工作树和隔离分支）。OpenAI的SDK支持agent作为工具（专家处理有界子任务）和移交（专家接管完整控制权）。LangGraph将子agent实现为嵌套状态图。

（文章原文未单独列出第12个组件，按原文结构保留11个展开介绍。）

循环实际如何运转：逐步演练

了解了组件，再来看一个完整循环的运作方式。

第1步（提示词组装）： Harness构建完整输入：系统提示 + 工具schema + 记忆文件 + 对话历史 + 当前用户消息。重要上下文被放在提示词的开头和结尾（来自「迷失在中间」的发现）。

第2步（LLM推断）： 组装好的提示词发送给模型API，模型生成输出token：文本、工具调用请求，或两者都有。

第3步（输出分类）： 如果模型只输出文本且没有工具调用，循环结束。如果请求了工具调用，进入执行。如果请求了移交，更新当前agent并重新开始。

第4步（工具执行）： 对每个工具调用，Harness验证参数、检查权限、在沙盒环境中执行、捕获结果。只读操作可以并发运行；写入操作串行运行。

第5步（结果打包）： 工具结果被格式化为LLM可读的消息。错误被捕获并作为错误结果返回，让模型可以自我纠正。

第6步（上下文更新）： 结果追加到对话历史。如果接近上下文窗口限制，Harness触发压缩。

第7步（循环）： 返回第1步，重复直到终止。

终止条件是分层的：模型产生无工具调用的响应、超过最大轮次限制、token预算耗尽、护栏断路器触发、用户中断、或返回安全拒绝。一个简单问题可能只需1到2轮，一个复杂的重构任务可以在多轮中串联几十次工具调用。

对于跨越多个上下文窗口的长时间运行任务，Anthropic开发了一种两阶段「Ralph Loop」模式：初始化agent负责建立环境（初始化脚本、进度文件、功能列表、初始git提交），然后后续每个会话中的编码agent读取git日志和进度文件来定位自身，选择优先级最高的未完成功能，完成后提交并写入摘要。文件系统在上下文窗口之间提供连续性。

主流框架如何实现这一模式

Anthropic的Claude Agent SDK 通过单一的query()函数暴露Harness，创建agent循环并返回流式消息的异步迭代器。运行时是一个「笨循环」，所有智能住在模型里。Claude Code使用收集-行动-验证循环：收集上下文（搜索文件、阅读代码）、采取行动（编辑文件、运行命令）、验证结果（运行测试、检查输出），然后重复。

OpenAI的Agents SDK 通过Runner类实现Harness，支持三种模式：异步、同步、流式。SDK是「代码优先」的：工作流逻辑用原生Python表达，而不是图DSL。Codex Harness在此基础上扩展出三层架构：Codex Core（agent代码 + 运行时）、App Server（双向JSON-RPC API）、客户端界面（CLI、VS Code、网页应用）。所有界面共享同一个Harness，这就是「Codex模型在Codex界面上的表现优于通用聊天窗口」的原因。

LangGraph 将Harness建模为显式状态图。两个节点（llm_call和tool_node）通过条件边连接：如果有工具调用，路由到tool_node；如果没有，路由到END。LangGraph从LangChain的AgentExecutor演化而来，后者在v0.2中被弃用，原因是难以扩展且缺乏多agent支持。LangChain的Deep Agents明确使用了「agent harness」这个词：内置工具、规划（write_todos工具）、用于上下文管理的文件系统、子agent生成、以及持久记忆。

CrewAI 实现了基于角色的多agent架构：Agent（围绕LLM的Harness，由角色、目标、背景故事和工具定义）、Task（工作单元）和Crew（agent的集合）。CrewAI的Flows层增加了「关键位置有智能支撑的确定性骨架」，在Crew处理自主协作时管理路由和验证。

AutoGen（正在演化为微软Agent Framework）开创了对话驱动的编排方式。其三层架构（Core、AgentChat、Extensions）支持五种编排模式：顺序、并发（扇出/扇入）、群聊、移交，以及magentic（管理agent维护动态任务账本，协调各专家agent）。

脚手架比喻的精确含义

脚手架这个比喻不是装饰性的，它很精准。建筑脚手架是让工人能够到达他们否则无法触及位置的临时基础设施。它不负责建设，但没有它，工人上不了高层。

关键洞察：脚手架在建筑完工后会被拆除。随着模型改进，Harness的复杂性应该降低。Manus在六个月内重写了五次，每次重写都在去除复杂性。复杂的工具定义变成了通用的shell执行，「管理agent」变成了简单的结构化移交。

这指向了协同演化原则：模型现在与特定Harness一起在训练循环中进行后训练。Claude Code的模型学会了使用它被训练时配合的那个特定Harness。改变工具实现可能因为这种紧密耦合而降低性能。

Harness设计的「面向未来测试」是：如果随着模型能力提升，性能能够提升而不需要增加Harness复杂性，那么设计就是健全的。

每个Harness都面临的七个决策

单agent还是多agent： Anthropic和OpenAI都建议先把单agent做到极致。多agent系统增加开销（路由需要额外的LLM调用，移交时上下文会丢失）。只在工具数量超过约10个重叠工具、或存在明显独立的任务域时才拆分。

ReAct还是计划-执行： ReAct在每一步交织推理和行动（灵活但每步成本更高）。计划-执行将规划与执行分离。LLMCompiler报告比顺序ReAct快3.6倍。

上下文窗口管理策略： 五种生产方式：基于时间的清除、对话摘要、观察屏蔽、结构化笔记、子agent委托。ACON研究表明，通过优先保留推理轨迹而非原始工具输出，可以在保持95%以上准确率的同时减少26到54%的token用量。

验证循环设计： 计算验证（测试、代码检查器）提供确定性的基准真相。推断验证（LLM作为评判者）能捕获语义问题但增加延迟。Martin Fowler的Thoughtworks团队将其框架化为：指南（前馈，行动前引导）和传感器（反馈，行动后观察）。

权限和安全架构： 宽松型（快但有风险，自动批准大多数操作）还是限制型（安全但慢，每次操作都需要批准）。选择取决于部署场景。

工具范围策略： 更多工具往往意味着更差的性能。Vercel从v0中删除了80%的工具，结果更好了。Claude Code通过懒加载实现了95%的上下文减少。原则是：只暴露当前步骤所需的最小工具集。

Harness厚度： 多少逻辑住在Harness里，多少交给模型。Anthropic押注于薄Harness和模型改进。基于图的框架押注于显式控制。Anthropic随着新模型版本将那些能力内化，定期从Claude Code的Harness中删除规划步骤。

Harness就是产品

使用相同模型的两个产品，仅凭Harness设计就可以产生截然不同的性能。TerminalBench的证据很清楚：只改变Harness，就能让agent的排名移动20个以上的位次。

Harness不是一个已解决的问题，也不是一个商品化的层。它是真正硬核的工程所在：把上下文作为稀缺资源来管理，设计在失败累积之前就能捕获失败的验证循环，构建能提供连续性而不产生幻觉的记忆系统，以及在「要构建多少脚手架」与「留多少给模型」之间做出架构决策。

这个领域正在向更薄的Harness方向演进，因为模型在持续改进。但Harness本身不会消失。即使是最强大的模型，也需要某个东西来管理它的上下文窗口、执行它的工具调用、持久化它的状态、以及验证它的工作。

下次你的agent失败时，不要怪模型，看看Harness。