万字讲透Agent Harness的十二大模块

Agent Harness这个词现在几乎是每日必见了。但Harness到底是什么？它凭什么能把一个普普通通的大语言模型（LLM）变成一个真正能干活的智能体？今天，咱们就深入拆解一下这个神秘的“框架”。

你可能已经搭过一个聊天机器人，还给它接了几个工具，搞了个ReAct循环。演示的时候跑得挺溜。但一旦想做成生产级的产品，各种问题就冒出来了：模型忘了三步之前自己干了啥，工具调用悄无声息地挂了，上下文窗口里塞满了垃圾信息。

问题不在于你的模型，而在于模型周围包裹的那层基础设施。这套基础设施，现在有了一个正式的名字：

。

这个术语在2026年初才被正式定义，但概念其实早就存在。所谓Harness，就是包裹LLM的一整套软件基础设施：编排循环、工具、记忆、上下文管理、状态持久化、错误处理和安全护栏。Anthropic的官方文档说得干脆：Claude Code SDK就是“驱动Claude Code的Agent Harness”。OpenAI的Codex团队也持相同观点，把“agent”和“harness”几乎划等号，指的都是让LLM真正能派上用场的非模型基础设施。

这里有个很容易把人绕晕的区别。“智能体 (Agent)”是一种“涌现行为”：有明确目标、会用工具、能自我纠正，是用户实际交互的对象。而Harness，是产生这种行为的机器。所以当有人说“我搭了一个agent”，他的潜台词其实是：我搭了一套Harness，然后把它指向了一个模型。

Beren Millidge在2023年的文章《Scaffolding for AI》里，把这个类比说得极其精准：一个裸的LLM，就像一台没有内存、没有硬盘、没有I/O的CPU。上下文窗口充当内存（快但容量有限），外部数据库充当硬盘存储（大但慢），工具集成充当设备驱动。而Harness，就是操作系统。正如Millidge所写：“我们重新发明了冯·诺依曼架构”，因为这是任何计算系统都绕不开的自然抽象。

围绕模型，有三层同心圆式的工程体系：

——精心打磨模型收到的指令；——管理模型在什么时候看到什么内容；——涵盖以上两者，再加上整个应用基础设施：工具编排、状态持久化、错误恢复、验证循环、安全强制执行和生命周期管理。Harness不是给提示套个壳子，它是让自主智能体行为成为可能的完整系统。

综合Anthropic、OpenAI、LangChain以及更广泛实践社区的经验，一个生产级的Agent Harness包含十二个独立组件。咱们一个一个来盘。

1. 编排循环 (Orchestration Loop) —— Agent的心跳

这就是agent的“心跳”。它实现了

，也就是我们常说的 。整个流程跑起来就像这样：组装提示词 → 呼叫大模型 → 解析输出 → 执行工具调用 → 把结果喂回去 → 重复，直到搞定收工。

从机械结构上看，它往往就是个 while 循环。真正的复杂度全藏在循环管理的那些“杂事”里，而不是循环本身。Anthropic把他们的运行时比作一个“

”——所有智商都长在模型身上，执行框架只管轮流转场。

2. 工具 (Tools) —— Agent的手

工具是agent的“手”。它们以

（名称、描述、参数类型）的形式定义好，再注入到LLM的上下文里，让模型知道自己手里有什么牌。工具层负责注册、Schema校验、参数提取、、结果捕获，以及把结果格式化成模型能读懂的。

Claude Code提供了六大类工具：文件操作、搜索、执行、网页访问、代码智能和

。OpenAI的Agents SDK支持函数工具（通过 ）、托管工具（WebSearch、CodeInterpreter、FileSearch）以及 。

3. 记忆 (Memory) —— 多个时间尺度的存档

记忆在多个时间尺度上同时运作。

就是单次会话里的对话历史。 则跨会话持久化：Anthropic用 claude.md 项目文件和自动生成的 .claude/ 文件；LangGraph用按命名空间组织的JSON Stores；OpenAI支持由SQLite或Redis支撑的Sessions。

Claude Code搞了一个三级层级：轻量级索引（每条约150字符，常驻内存）、详细主题文件（按需拉取）、原始Transcript（仅通过搜索访问）。一个关键设计原则：agent把自己的记忆当作“

”，行动前会先跟实际状态核对验证。

4. 上下文管理 (Context Management) —— 无声翻车的高发区

这是很多agent

的地方。核心问题是：当关键内容掉在窗口中间位置时，模型性能暴跌30%以上（Chroma的研究，与Stanford的“”发现相互印证）。哪怕是百万token的上下文窗口，随着内容膨胀，指令遵循能力也会下降。

生产环境的应对策略包括：

• 压缩 (Compaction)
  ：快满的时候对对话历史做摘要（Claude Code会保留架构决策和未解决的bug，扔掉冗余的工具输出）

• 观察屏蔽 (Observation Masking)
  ：JetBrains的Junie把旧的工具输出藏起来，但保留工具调用可见

• 即时检索 (Just-in-time Retrieval)
  ：维护轻量级标识符，动态加载数据（Claude Code用 grep、glob、head、tail，而不是加载完整文件）

• 子智能体委派 (Sub-agent Delegation)
  ：每个子智能体可以尽情探索，但只返回1,000到2,000 token的精简摘要

Anthropic的上下文工程指南点明了目标：找到最小的高信噪比token集合，最大化期望结果出现的概率。

5. 提示词组装 (Prompt Assembly) —— 模型此刻看到的世界

这一步组装模型在每一轮实际看到的东西。它是分层堆叠的：

、工具定义、记忆文件、对话历史，以及当前用户消息。

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

6. 工具调用与结构化输出 (Tool Calling & Structured Output)

现代的执行框架依赖

，模型返回结构化的 tool_calls 对象，而不是需要额外解析的自由文本。Harness检查逻辑很简单：有工具调用？执行它们并继续循环。没有工具调用？那就是最终答案。

对于

，OpenAI和LangChain都支持通过 进行Schema约束的响应。像 RetryWithErrorOutputParser 这样的遗留方案（把原始提示词、失败的补全和解析错误一起塞回模型）在边缘场景下仍然可用。

7. 状态与检查点 (State & Checkpointing)

LangGraph将状态建模为流经图节点的类型化字典，并通过 归约器 (Reducers) 来合并更新。检查点在 超级步骤 (Super-step) 边界处触发，这意味着中途被打断后可以无缝恢复，还能实现“时光倒流”般的调试。OpenAI提供了四种互斥的策略：应用内存、SDK会话 (SDK Sessions)、服务器端的 对话API (Conversations API)，或是轻量级的 previous_response_id 链式调用。Claude Code则另辟蹊径：用 git提交 (Git Commits) 作为检查点，用进度文件作为结构化的草稿本。

8. 错误处理 (Error Handling)

先说个让人警醒的事实：一个10步的流程，即便每步成功率高达99%，端到端的总成功率也只有约90.4%。错误会像滚雪球一样越滚越大。

LangGraph区分了四种错误类型：瞬时错误 (Transient)（带退避的重试）、LLM可恢复错误 (LLM-recoverable)（将错误包装成 工具消息 (ToolMessage) 返回给模型自行调整）、用户可修复错误 (User-fixable)（中断并等待人工输入），以及意外错误 (Unexpected)（直接抛出供调试）。Anthropic的做法是在工具处理器内部捕获失败，并将其作为错误结果返回，确保主循环不中断。Stripe的生产级Harness则将重试次数严格限制在两次以内。

9. 护栏 (Guardrails)

OpenAI的SDK实现了三层防护：输入护栏 (Input Guardrails)（在首个Agent上运行）、输出护栏 (Output Guardrails)（在最终输出上运行），以及工具护栏 (Tool Guardrails)（每次调用工具时都运行）。一旦触发“绊线”机制，Agent会立刻急刹车。

Anthropic在架构上将权限执行与模型推理彻底解耦。模型负责“想做什么”，工具系统负责“能做什么”。Claude Code独立管控着约40种离散的工具能力，分三个阶段把关：项目加载时建立信任、每次调用工具前检查权限、高风险操作必须获得用户明确确认。

10. 验证与反馈 (Verification & Feedback)

这是玩具演示和生产级Agent的分水岭。Anthropic推荐三种验证方式：基于规则的反馈 (Rules-based Feedback)（测试、Linter、类型检查器）、视觉反馈 (Visual Feedback)（通过Playwright截图检查UI任务），以及LLM当裁判 (LLM-as-judge)（用一个独立的子Agent来评估输出）。

Claude Code的创始人Boris Cherny指出，给模型一个验证自身工作的手段，能让质量提升2到3倍。

11. 子Agent编排 (Subagent Orchestration)

Claude Code支持三种执行模式：Fork（父上下文的字节级精确副本）、Teammate（独立的终端面板，通过文件邮箱通信），以及 Worktree（每个Agent拥有独立的 git工作树 (Git Worktree) 和隔离分支）。OpenAI的SDK支持 Agent作为工具 (Agents-as-Tools)（专家处理有边界的子任务）和交接 (Handoffs)（专家全面接管）。LangGraph则将子Agent实现为嵌套的状态图。

12. 初始化与环境搭建 (Initialization & Environment Setup)

现在你已经了解了各个组件，让我们追踪它们如何在一个完整周期中协同工作。

：Harness构建完整的输入：系统提示词 (System Prompt) + 工具模式 (Tool Schemas) + 记忆文件 + 对话历史 + 当前用户消息。重要的上下文会被放置在提示词的开头和结尾（这就是著名的“中间迷失”现象）。

：组装好的提示词被送往模型API。模型生成输出token：可能是纯文本、工具调用请求，或两者兼有。

：如果模型只生成了文本而没有工具调用，循环结束。如果请求了工具调用，则进入执行阶段。如果请求了交接，则更新当前Agent并重启。

：对于每个工具调用，Harness会验证参数、检查权限、在沙箱环境中执行，并捕获结果。只读操作可以并发执行；写操作则串行处理。

：工具结果被格式化为LLM可读的消息。错误会被捕获并作为错误结果返回，让模型能够自我修正。

：结果被追加到对话历史中。如果接近 上下文窗口 (Context Window) 上限，Harness会触发压缩。

：回到步骤1。重复直到终止。

终止条件是多层级的：模型产出了没有工具调用的回复、达到最大轮次限制、token 预算耗尽、护栏绊线被触发、用户主动中断、或返回了安全拒绝。一个简单问题可能只需1到2轮。一个复杂的重构任务则可能跨越多轮，串联数十个工具调用。

：初始化Agent (Initializer Agent) 先搭建环境（初始化脚本、进度文件、功能列表、首次git提交），然后每个后续会话中的编码Agent (Coding Agent) 会读取git日志和进度文件来定位自己，挑选最高优先级的未完成特性，开始工作，提交代码，并撰写摘要。文件系统跨越上下文窗口，提供了连续性。

现在，来看看几个主流框架的具体实现。

Anthropic的Claude Agent SDK通过一个 query() 函数暴露出整个 智能体框架 (Harness)，这个函数创建了智能体循环，并返回一个异步迭代器来流式传输消息。运行时就是一个“傻循环”——所有的智商都在模型里。Claude Code采用了一个 收集-执行-验证 (Gather-Act-Verify) 的循环：收集上下文 (Gather Context)（搜索文件、读取代码）、采取行动 (Take Action)（编辑文件、运行命令）、验证结果 (Verify Results)（跑测试、检查输出），然后周而复始。

OpenAI的Agents SDK则通过 Runner 类来实现这个框架，提供三种模式：异步 (Async)、同步 (Sync) 和流式 (Streamed)。这个SDK是“代码优先 (Code-first)”的：工作流逻辑用原生Python写，而不是用什么 图领域特定语言 (Graph DSLs)。Codex的框架在此基础上扩展成了三层架构：Codex Core（智能体代码 + 运行时）、App Server（双向 JSON-RPC API）、以及客户端界面 (Client Surfaces)（CLI、VS Code、网页应用）。所有界面共享同一个框架，这就是为什么“Codex模型在Codex的界面上用起来，比在一个通用聊天窗口里顺手得多”。

LangGraph把框架建模为一个显式的 状态图 (State Graph)。两个节点（llm_call 和 tool_node）通过一条条件边 (Conditional Edge)连接：如果存在 工具调用 (Tool Calls)，就路由到 tool_node；如果没有，就路由到END。LangGraph是从LangChain的 AgentExecutor 进化来的，后者在v0.2被废弃了，因为它难以扩展，而且不支持多智能体。LangChain的Deep Agents明确使用了“智能体框架 (Agent Harness)”这个词：内置工具、规划 (Planning)（write_todos 工具）、用于上下文管理的文件系统、子智能体生成 (Subagent Spawning)、以及持久化记忆 (Persistent Memory)。

CrewAI实现了一种基于角色的 多智能体架构 (Multi-agent Architecture)：智能体 (Agent)（围绕 LLM 的框架，由角色、目标、背景故事和工具定义）、任务 (Task)（工作单元）、以及团队 (Crew)（智能体的集合）。CrewAI的Flows层增加了一个“在关键之处注入智能的确定性骨架”，负责路由和验证，而Crews则处理自主协作。

AutoGen（正在演进为 Microsoft Agent Framework）开创了对话驱动编排 (Conversation-driven Orchestration) 的先河。它的三层架构（Core、AgentChat、Extensions）支持五种 编排模式 (Orchestration Patterns)：顺序 (Sequential)、并发 (Concurrent，扇出/扇入 (Fan-out/Fan-in))、群组聊天 (Group Chat)、交接 (Handoff)、以及 magentic（一个管理智能体维护着动态任务台账，协调各路专家）。

说到这里，必须提一个精准的比喻：

。建筑脚手架是临时基础设施，让工人能够够到原本够不到的地方去施工。它本身不干活，但没有它，工人就上不了高楼。

核心洞见在于：楼盖好了，脚手架就该拆了。模型越强，框架的复杂度就该越低。Manus在半年内重构了五次，每次重写都在做减法。复杂的工具定义变成了通用的 Shell执行 (Shell Execution)，“管理智能体 (Management Agents)”变成了简单的结构化交接 (Structured Handoffs)。

这指向了一个

：现在的模型在 后训练 (Post-trained) 时，会把特定的框架纳入训练循环。Claude Code的模型学会的是它训练时配对的那个特定框架。因为这种紧密耦合，改了工具实现反而可能导致性能下降。

框架设计的“面向未来的测试 (Future-proofing Test)”是：如果模型更强了，性能自然提升，而框架复杂度不需要增加，那这个设计就是靠谱的。

每个框架架构师都要面对七个抉择：

1. 单智能体 (Single-agent) vs. 多智能体 (Multi-agent)。
   Anthropic和OpenAI都说：先把单智能体榨干再说。多智能体系统有额外开销（路由要多调LLM、交接时会丢失上下文）。只有当工具重叠超过约10个，或者任务域明显分离时，才考虑拆分。

2. ReAct vs. 计划-执行 (Plan-and-Execute)。
   ReAct 每一步都把推理和行动搅在一起（灵活，但每步成本高）。计划-执行 把规划和执行分开。LLMCompiler 报告称，相比顺序 ReAct 有

   3.6倍
   的加速。

3. 上下文窗口 (Context Window) 管理策略。
   五种生产级方案：基于时间的清理、对话摘要、观察掩码 (Observation Masking)、结构化笔记 (Structured Note-taking)、以及子智能体委托 (Sub-agent Delegation)。ACON的研究表明，通过优先保留推理痕迹而非原始工具输出，可以在保持95%+准确率的同时，减少26%到54%的 token 消耗。

4. 验证循环 (Verification Loop) 设计。
   计算验证 (Computational Verification)（测试、代码检查器）提供确定性的真相。推理验证 (Inferential Verification)（LLM当裁判）能抓住语义问题，但会增加延迟。Martin Fowler的Thoughtworks团队把这叫 引导器 (Guides)（前馈，行动前引导）vs. 传感器 (Sensors)（反馈，行动后观察）。

5. 权限与安全架构 (Permission and Safety Architecture)。
   宽松模式（快但险，大部分操作自动批准）vs. 严格模式（安全但慢，每一步都要approval）。取决于部署场景。

6. 工具范围策略 (Tool Scoping Strategy)。
   工具越多，性能往往越差。Vercel从v0里砍掉了80%的工具，结果反而更好。Claude Code通过懒加载 (Lazy Loading) 实现了95%的上下文缩减。原则：当前这一步需要啥，就暴露啥，绝不多给。

7. 框架厚度 (Harness Thickness)。
   多少逻辑应该放在框架里，多少留给模型。Anthropic赌的是薄框架 (Thin Harnesses) + 模型进化。基于图的框架赌的是显式控制 (Explicit Control)。Anthropic会定期从Claude Code的框架里删掉规划步骤，因为新版本的模型已经把这个能力内化了。

两个产品用一模一样的模型，只因为框架设计不同，性能就可能天差地别。TerminalBench 的证据很明确：只改框架，就能让智能体的排名上下浮动

20多名

。

智能体框架不是什么已经解决的问题，也不是什么通用Commodity层。真正的硬工程就在这里：把上下文当稀缺资源来管理、设计能在错误滚雪球之前拦住它的验证循环、构建既保持连续性又不产生幻觉的记忆系统、以及赌一把——到底该搭多少脚手架，又该留给模型多少。

随着模型越来越强，行业正在往更薄的框架走。但框架本身不会消失。就算是最强的模型，也需要一个东西来管理它的上下文窗口、执行它的工具调用、持久化它的状态、以及验证它的产出。

下次你的智能体掉链子，别怪模型。看看它的框架。