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

Agent Harness这个词现在是天天见了，但是Harness的内涵究竟是什么，X上的这篇文章算是很好的科普：

原文： https://x.com/akshay_pachaar/status/2041146899319971922
作者： Akshay 🚀 (@akshay_pachaar)

你可能已经搭了一个聊天机器人。也许还给它接了几个工具，搞了个 ReAct 循环 (ReAct loop)。演示的时候跑得挺溜。但一旦想做成生产级的玩意儿，车就开始翻了：模型忘了三步之前自己干了啥，工具调用悄无声息地挂了，上下文窗口 (context window) 里塞满了垃圾信息。

问题不在你的模型，而在模型周围的那堆东西。

LangChain 早就验证过这一点——他们只改了包裹 大语言模型 (LLM) 的底层架构（模型没变，权重没变），结果在 TerminalBench 2.0 上直接从 30 名开外飙到了第 5。另一个研究项目更狠，让 大语言模型 (LLM) 自己去优化这套架构，通过率干到了 76.4%，吊打人工设计的系统。

这套架构现在有了个正式名字：智能体 harness (agent harness)。

这个词在 2026 年初才被正式定下来，但概念其实早就存在了。所谓 harness，就是包裹 大语言模型 (LLM) 的一整套软件基础设施：编排循环 (orchestration loop)、工具 (tools)、记忆 (memory)、上下文管理 (context management)、状态持久化 (state persistence)、错误处理 (error handling) 和 安全护栏 (guardrails)。Anthropic 的 Claude Code 文档说得干脆：SDK 就是"驱动 Claude Code 的 智能体 harness (agent harness)"。OpenAI 的 Codex 团队也是同一个路数，直接把 "agent" 和 "harness" 划等号，指的都是让 大语言模型 (LLM) 真正能派上用场的那套非模型基础设施。

我特别喜欢 LangChain 的 Vivek Trivedy 说的那句经典论断：

如果你不是模型，你就是 harness。

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

Agent 与 Harness 的 CPU 和 OS 类比

Beren Millidge 在 2023 年的文章《Scaffolding for AI》里，把这个类比说得极其精准：

一个裸的 大语言模型 (LLM)，就像一台没有内存、没有硬盘、没有 I/O 的 CPU。上下文窗口 (context window) 充当内存（快但容量有限），外部数据库充当硬盘存储（大但慢），工具集成充当设备驱动。而 harness 就是操作系统。正如 Millidge 所写："我们重新发明了 冯·诺依曼架构 (Von Neumann architecture)"，因为这是任何计算系统都绕不开的自然抽象。

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

• • 提示工程 (Prompt engineering)：精心打磨模型收到的指令。
• • 上下文工程 (Context engineering)：管理模型在什么时候看到什么内容。
• • Harness 工程 (Harness engineering)：涵盖以上两者，再加上整个应用基础设施——工具编排 (tool orchestration)、状态持久化 (state persistence)、错误恢复 (error recovery)、验证循环 (verification loops)、安全强制执行 (safety enforcement) 和 生命周期管理 (lifecycle management)。

Harness 不是给 提示 (prompt) 套个壳子。它是让 自主智能体 (autonomous agent) 行为成为可能的完整系统。

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

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

这就是 agent 的"心跳"。它实现了思考-行动-观察循环 (Thought-Action-Observation, TAO)，也就是我们常说的 ReAct 循环。整个流程跑起来就像这样：组装提示词 → 呼叫大模型 → 解析输出 → 执行工具调用 → 把结果喂回去 → 重复，直到搞定收工。

从机械结构上看，它往往就是个 while 循环。真正的复杂度全藏在循环管理的那些"杂事"里，而不是循环本身。Anthropic 把他们的运行时比作一个"笨循环 (dumb loop)"——所有智商都长在模型身上，执行框架 (harness) 只管轮流转场。

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

工具是 agent 的"手"。它们以 schema（名称、描述、参数类型）的形式定义好，再注入到大语言模型 (LLM) 的上下文里，让模型知道自己手里有什么牌。工具层 (tool layer) 负责注册、schema 校验、参数提取、沙箱执行 (sandboxed execution)、结果捕获，以及把结果格式化成模型能读懂的观察结果 (observations)。

Claude Code 提供了六大类工具：文件操作、搜索、执行、网页访问、代码智能和子智能体孵化 (subagent spawning)。OpenAI 的 Agents SDK 支持函数工具（通过 function calling）、托管工具（WebSearch、CodeInterpreter、FileSearch）以及 MCP 服务器工具 (MCP server tools)。

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

记忆在多个时间尺度上同时运作。短期记忆 (Short-term memory) 就是单次会话里的对话历史。长期记忆 (Long-term memory) 则跨会话持久化：Anthropic 用 claude.md 项目文件和自动生成的 .claude/ 文件；LangGraph 用按命名空间组织的 JSON Stores；OpenAI 支持由 SQLite 或 Redis 支撑的 Sessions。

Claude Code 搞了一个三级层级：轻量级索引（每条约 150 字符，常驻内存）、详细主题文件（按需拉取）、原始 transcript（仅通过搜索访问）。一个关键设计原则：agent 把自己的记忆当作"提示 (hint)"，行动前会先跟实际状态核对验证。

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

这是很多 agent 默默翻车的地方。核心问题是上下文腐烂 (context rot)：当关键内容掉在窗口中间位置时，模型性能暴跌 30% 以上（Chroma 的研究，与 Stanford 的"中间迷失 (Lost in the Middle)"发现相互印证）。哪怕是百万 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) —— 模型此刻看到的世界

这一步组装模型在每一轮实际看到的东西。它是分层堆叠的：系统提示词 (system prompt)、工具定义、记忆文件、对话历史，以及当前用户消息。

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

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

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

对于结构化输出 (structured outputs)，OpenAI 和 LangChain 都支持通过 Pydantic 模型 (Pydantic models) 进行 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)

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

步骤 1（提示词组装）：Harness 构建完整的输入：系统提示词 (system prompt) + 工具模式 (tool schemas) + 记忆文件 + 对话历史 + 当前用户消息。重要的上下文会被放置在提示词的开头和结尾（这就是著名的"中间迷失"现象）。

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

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

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

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

步骤 6（上下文更新）：结果被追加到对话历史中。如果接近 上下文窗口 (context window) 上限，Harness 会触发压缩。

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

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

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

Agent 执行周期

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（一个管理智能体维护着动态任务台账，协调各路专家）。

SDK 架构对比

脚手架 (scaffolding)的比喻不是装饰，它非常精确。建筑脚手架是临时基础设施，让工人能够够到原本够不到的地方去施工。它本身不干活，但没有它，工人就上不了高楼。

脚手架隐喻

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

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

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

共同进化原则

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

七个架构抉择

1. 1. 单智能体 (Single-agent) vs. 多智能体 (multi-agent)。 Anthropic 和 OpenAI 都说：先把单智能体榨干再说。多智能体系统有额外开销（路由要多调 LLM、交接时会丢失上下文）。只有当工具重叠超过约 10 个，或者任务域明显分离时，才考虑拆分。
2. 2. ReAct vs. 计划-执行 (plan-and-execute)。 ReAct 每一步都把推理和行动搅在一起（灵活，但每步成本高）。计划-执行 把规划和执行分开。LLMCompiler 报告称，相比顺序 ReAct 有 3.6 倍 的加速。
3. 3. 上下文窗口 (Context window) 管理策略。 五种生产级方案：基于时间的清理、对话摘要、观察掩码 (observation masking)、结构化笔记 (structured note-taking)、以及子智能体委托 (sub-agent delegation)。ACON 的研究表明，通过优先保留推理痕迹而非原始工具输出，可以在保持 95%+ 准确率的同时，减少 26% 到 54% 的 token 消耗。
4. 4. 验证循环 (Verification loop) 设计。 计算验证 (Computational verification)（测试、代码检查器）提供确定性的真相。推理验证 (Inferential verification)（LLM 当裁判）能抓住语义问题，但会增加延迟。Martin Fowler 的 Thoughtworks 团队把这叫 引导器 (guides)（前馈，行动前引导）vs. 传感器 (sensors)（反馈，行动后观察）。
5. 5. 权限与安全架构 (Permission and safety architecture)。 宽松模式（快但险，大部分操作自动批准）vs. 严格模式（安全但慢，每一步都要 approval）。取决于部署场景。
6. 6. 工具范围策略 (Tool scoping strategy)。 工具越多，性能往往越差。Vercel 从 v0 里砍掉了 80% 的工具，结果反而更好。Claude Code 通过懒加载 (lazy loading) 实现了 95% 的上下文缩减。原则：当前这一步需要啥，就暴露啥，绝不多给。
7. 7. 框架厚度 (Harness thickness)。 多少逻辑应该放在框架里，多少留给模型。Anthropic 赌的是薄框架 (thin harnesses) + 模型进化。基于图的框架赌的是显式控制 (explicit control)。Anthropic 会定期从 Claude Code 的框架里删掉规划步骤，因为新版本的模型已经把这个能力内化了。

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

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

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

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

收工！