Agent Harness 拆解

EN Markdown

来源：@akshay_pachaar on X · 2026-04-06

深入剖析 Anthropic、OpenAI、Perplexity、LangChain 实际在搭什么。从 orchestration loop、工具、记忆、上下文管理一路讲下来，看一个无状态 LLM 是怎么变成派得上用场的 agent 的。

你搭过聊天机器人。可能还接过一个带几个工具的 ReAct loop，跑 demo 没问题。然后你想做点生产级的东西——立刻翻车：模型忘了三步前自己干过什么，工具调用静默失败，上下文窗口被垃圾塞满。

问题不在你的模型，在模型周围那一圈东西。

LangChain 验证过这件事：他们只换了包 LLM 的基础设施（同一个模型、同一份权重），就在 TerminalBench 2.0 上从 30 名开外冲到第 5。另一项研究让 LLM 自己优化基础设施，跑出 76.4% 的通过率，超过人工手搓的系统。

这套基础设施现在有名字了：agent harness。

什么是 Agent Harness？

这个词 2026 年初才正式定义，但东西早就存在。Harness 是包住 LLM 的整套软件基础设施：orchestration loop（编排循环）、工具（Tools）、记忆（Memory）、上下文管理（Context Management）、状态持久化（State Management）、错误处理（Error Handling）、guardrails（护栏）。Anthropic 的 Claude Code 文档说得很直白：SDK 就是 "驱动 Claude Code 的 agent harness"。OpenAI 的 Codex 团队同一个说法，把 "agent" 和 "harness" 这两个词直接画等号，都指那层让 LLM 真正可用的非模型基础设施。

我特别喜欢 LangChain 的 Vivek Trivedy 那句经典公式："如果你不是模型，那你就是 harness。"

这里有个常被搞混的区别。"agent" 是涌现出来的行为：用户对话的对象，目标导向、会用工具、能自我纠错。Harness 才是产生这种行为的机器。当有人说"我做了个 agent"，他实际上是搭了一个 harness，然后把它指向某个模型。

Beren Millidge 在 2023 年那篇 《Scaffolded LLMs as Natural Language Computers》 把这个类比讲得很精确。一颗原始 LLM 就是一块没 RAM、没硬盘、没 I/O 的 CPU。上下文窗口当 RAM（快但容量小），外部数据库当硬盘（大但慢），工具集成相当于设备驱动。Harness 就是操作系统。 Millidge 写："我们重新发明了冯·诺依曼架构"——它对任何计算系统都是天然抽象。

三层工程

模型外面套着三层同心的工程：

  • Prompt engineering（提示工程） 打磨模型收到的指令。
  • Context engineering（上下文工程） 管理模型何时看到什么。
  • Harness engineering 涵盖前两者，再加上整套应用基础设施：工具编排、状态持久化、错误恢复、验证回路、安全执行、生命周期管理。

Harness 不是包在 prompt 外面的一层壳。它是让 agent 自主跑起来的整套系统。

生产级 Harness 的 12 个组件

把 Anthropic、OpenAI、LangChain 以及更广泛的实践者社区合在一起看，一个生产级 agent harness 有十二个独立组件。逐个看。

1. Orchestration Loop（编排循环）

这是心跳。它实现 Thought-Action-Observation（TAO）循环，也叫 ReAct loop。流程是：拼 prompt、调 LLM、解析输出、执行工具调用、把结果送回去、重复，到结束为止。

说白了，它常常就是个 while 循环。 复杂度不在循环本身，在循环管的那一堆东西里。Anthropic 把他们的运行时形容为 "dumb loop"——所有智能都活在模型里，harness 只负责管 turn。

2. Tools（工具）

工具是 agent 的双手。它们以 schema（名称、描述、参数类型）的形式注入 LLM 上下文，让模型知道有哪些工具可用。工具层负责注册、schema 校验、参数提取、沙箱执行、抓结果，再把结果格式化成 LLM 能读的 observation。

Claude Code 提供六类工具：文件操作、搜索、执行、网络访问、代码理解、subagent 派生。OpenAI 的 Agents SDK 支持 function tools（用 @function_tool）、托管工具（WebSearch、CodeInterpreter、FileSearch）、还有 MCP 服务器工具。

3. Memory（记忆）

记忆跑在多个时间尺度上。短期记忆是单次会话内的对话历史。长期记忆跨会话持久化：Anthropic 用 CLAUDE.md 项目文件加自动生成的 MEMORY.md；LangGraph 用按命名空间组织的 JSON Store；OpenAI 提供 SQLite 或 Redis 后端的 Sessions。

Claude Code 做了一套三层结构：轻量索引（每条约 150 字符，始终加载）、按需调入的详细主题文件、只能搜索访问的原始 transcript。一条关键设计原则：agent 把自己的记忆当"提示"看，行动前要先去验证真实状态。

4. Context Management（上下文管理）

很多 agent 静默失败的地方就在这。核心问题是 context rot：关键内容落在窗口中段时，模型性能掉 30% 以上（Chroma 的研究，被 Stanford 的 "Lost in the Middle"——重要信息埋在窗口中段会被遗忘——佐证）。哪怕是百万 token 窗口，随着上下文增长，指令遵循能力照样衰退。

生产环境里几种策略：

  • Compaction（压缩）：接近上限时对对话历史做摘要（Claude Code 保留架构决策和未解决的缺陷，丢掉重复的工具输出）
  • Observation masking（观测遮蔽）：JetBrains 的 Junie 把旧的工具输出藏起来，工具调用本身保持可见
  • Just-in-time retrieval（即时检索）：维护轻量标识符，按需动态加载（Claude Code 用 grep、glob、head、tail，而不是把整个文件读进来）
  • Sub-agent delegation（子 agent 委托）：每个子 agent 充分探索，只回传 1000 到 2000 token 的浓缩摘要

Anthropic 的上下文工程指南把目标说得很清楚：找一组高信号 token，能拉高期望结果的概率，但越小越好。

5. Prompt Construction（Prompt 构造）

这一步把模型每一步实际看到的东西拼出来。是分层的：系统 prompt、工具定义、记忆文件、对话历史、当前用户消息。

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

6. Output Parsing（输出解析）

现代 harness 靠原生工具调用，模型直接返回结构化的 tool_calls 对象，不再要正则去解析自由文本。Harness 的判断很简单：有工具调用？执行然后继续循环。没有？那就是最终答案。

要结构化输出，OpenAI 和 LangChain 都通过 Pydantic 模型支持 schema 约束。传统方案如 RetryWithErrorOutputParser（把原始 prompt、失败的补全、解析错误一起送回模型），在边角场景下还能用。

7. State Management（状态管理）

LangGraph 把状态建模成流经图节点的带类型字典，更新由 reducer 合并。检查点在 super-step（超步）边界产生，支持中断恢复和时间旅行式调试。OpenAI 提供四种互斥策略：应用层记忆、SDK sessions、服务端 Conversations API、轻量的 previous_response_id 链式接续。Claude Code 走另一条路：用 git commit 当检查点，用进度文件当结构化草稿本。

8. Error Handling（错误处理）

这件事为什么重要：10 步流程里每步成功率 99%，端到端也只有大约 90.4%。 错误复利得很快。

LangGraph 把错误分四类：transient（带退避的重试）、LLM-recoverable（包成 ToolMessage 返回，让模型自己调整）、user-fixable（中断等人类输入）、unexpected（往上抛出去调试用）。Anthropic 在工具处理器里捕到失败，把失败当错误结果返回，循环继续跑。Stripe 的生产 harness 把重试封顶在两次。

9. Guardrails and Safety（护栏与安全）

OpenAI 的 SDK 实现三层：input guardrail（在第一个 agent 上跑）、output guardrail（在最终输出上跑）、tool guardrail（每次工具调用都跑）。"tripwire（触发线）"一触发，agent 立刻停。

Anthropic 在架构上把权限执行和模型推理拆开。模型决定"想做什么"，工具系统决定"允许做什么"。Claude Code 把约 40 项独立工具能力分别设闸，分三个阶段：项目加载时建立信任、每次工具调用前做权限检查、对高风险操作要求用户明确确认。

10. Verification Loops（验证回路）

玩具 demo 和生产 agent 的分水岭就在这。Anthropic 推荐三种做法：基于规则的反馈（测试、linter、类型检查）、视觉反馈（UI 任务用 Playwright 截图）、LLM-as-judge（一个独立 subagent 来评判输出）。

Claude Code 作者 Boris Cherny 提到：给模型一条验证自己工作的途径，质量提升 2 到 3 倍。

11. Subagent Orchestration（Subagent 编排）

Claude Code 支持三种执行模型：Fork（按字节复制父级上下文）、Teammate(独立终端窗格，靠文件信箱通信)、Worktree（独占 git worktree，每个 agent 一条隔离分支）。OpenAI 的 SDK 支持 agents-as-tools（把 agent 当工具用，专家处理一个有界子任务）和 handoffs（交接，专家完全接手）。LangGraph 把 subagent 实现成嵌套的状态图。

Loop 在跑：一步步走

知道了组件，看它们在一个完整循环里怎么配合。

Step 1（Prompt 组装）：harness 拼出完整输入：系统 prompt + 工具 schema + 记忆文件 + 对话历史 + 当前用户消息。重要内容放在 prompt 开头和结尾（"Lost in the Middle" 的发现）。

Step 2（LLM 推理）：组装好的 prompt 送进模型 API。模型生成输出 token：文本、工具调用请求、或两者都有。

Step 3（输出分类）：模型只产生文本、没有工具调用，循环结束。请求了工具调用，进入执行阶段。请求了 handoff，更新当前 agent 然后重新开始。

Step 4（工具执行）：每个工具调用 harness 都要校验参数、检查权限、在沙箱里执行、抓结果。只读操作可以并发跑，会改状态的串行跑。

Step 5（结果打包）：工具结果格式化成 LLM 能读的消息。错误捕获后当错误结果返回，让模型可以自我纠正。

Step 6（上下文更新）：结果追加到对话历史。接近上下文窗口上限的话，harness 触发 compaction。

Step 7（循环）：回到 Step 1，重复到终止为止。

终止条件是分层的：模型给出不带工具调用的回复、达到最大 turn（轮次）数、token 预算耗尽、guardrail tripwire 触发、用户打断、返回了一次安全拒答。简单问题 1 到 2 个 turn 就完事，复杂的重构任务能在多个 turn 之间串起几十次工具调用。

跨多个上下文窗口的长任务，Anthropic 设计了一种两阶段的 "Ralph Loop" 模式：先来一个 Initializer Agent 把环境准备好（init 脚本、进度文件、特性列表、初始 git commit），之后每个会话里的 Coding Agent 都读 git log 和进度文件给自己定位，挑出优先级最高的未完成特性，干活、提交、写摘要。文件系统提供了跨上下文窗口的连续性。

真实框架怎么落这个范式

Anthropic 的 Claude Agent SDK 通过单个 query() 函数把 harness 暴露出来。这个函数启动 agentic loop，返回一个异步迭代器，消息流式吐出来。运行时是个 "dumb loop"——所有智能都在模型里。Claude Code 用 Gather-Act-Verify 循环：收集上下文（搜文件、读代码）、采取行动（编辑文件、跑命令）、验证结果（跑测试、看输出），重复。

OpenAI 的 Agents SDK 通过 Runner 类实现 harness，提供三种模式：异步、同步、流式。SDK 是 "code-first" 的：工作流逻辑用原生 Python 表达，不走图 DSL。Codex harness 在此之上加了三层架构：Codex Core（agent 代码 + 运行时）、App Server（双向 JSON-RPC API）、客户端表面（CLI、VS Code、Web app）。所有表面共享同一个 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 工具）、用于上下文管理的文件系统、subagent 派生、持久记忆。

CrewAI 做了一套基于角色的多 agent 架构：Agent（包 LLM 的 harness，由角色、目标、背景故事、工具定义）、Task（工作单元）、Crew（agent 集合）。CrewAI 的 Flows 层加了一条 "在该确定的地方确定，在该有智能的地方有智能" 的骨架，负责路由和校验，让 Crew 自由协作。

AutoGen（正在演变成 Microsoft Agent Framework）开创了对话驱动的编排范式。三层架构（Core、AgentChat、Extensions）支持五种编排模式：sequential、concurrent（fan-out / fan-in）、group chat、handoff、magentic（管理者 agent 维护一个动态任务账本协调专家——这是 AutoGen 自创的词，由 Magnetic + Agentic 拼成）。

脚手架的隐喻

脚手架这个比喻不是修辞，是精确的。施工脚手架是临时基础设施，让工人能够到他们原本够不到的地方去建造。脚手架本身不参与施工，但少了它，工人就上不了高层。

关键洞见：建筑完工，脚手架就拆掉。 模型变强，harness 复杂度就该往下降。Manus（国内的通用 agent 产品）在六个月里重写了五次，每次都在删复杂度。复杂的工具定义简化成通用 shell 执行。"管理 agent" 变成了简单的结构化 handoff。

这指向一个 co-evolution（共同进化）原则：模型现在是带着特定 harness 一起做后训练的。Claude Code 的模型只会用训练时配套的那套 harness。改动工具实现可能让性能下降，正是因为这种紧耦合。

Harness 设计的"未来兼容性测试"是这样的：性能能随着更强的模型一起放大、且不需要增加 harness 复杂度——设计就是稳的。

定义每个 Harness 的七个决策

每位 harness 架构师都要面对七个选择：

  1. 单 agent vs 多 agent。 Anthropic 和 OpenAI 都说：先把单 agent 拉到极致。多 agent 系统会带来开销（路由的额外 LLM 调用、handoff 时的上下文丢失）。只有当工具数量超过约 10 个并且互相重叠，或者任务领域明显分离时，才去拆。

  2. ReAct vs plan-and-execute。 ReAct 在每一步都把推理和行动交错（灵活但每步成本更高）。Plan-and-execute 把规划和执行分开。LLMCompiler 实测比串行 ReAct 快 3.6 倍。

  3. 上下文窗口管理策略。 五种生产级方案：基于时间的清空、对话摘要、observation masking、结构化笔记、子 agent 委托。ACON 的研究表明，优先保留推理轨迹而非原始工具输出，能砍掉 26% 到 54% 的 token，准确率还能保住 95% 以上。

  4. 验证回路设计。 计算式验证（测试、linter）给确定的真值。推断式验证（LLM-as-judge）抓得到语义问题，但延迟更高。Martin Fowler 在 Thoughtworks 的团队把这两者讲成 guides（前馈，行动前引导）和 sensors（反馈，行动后观察）。

  5. 权限与安全架构。 宽松（快但有风险，多数动作自动批准）vs 严格（安全但慢，每次动作都要审批）。怎么选取决于部署语境。

  6. 工具范围策略。 工具越多，性能往往越差。Vercel 把 v0 的工具砍掉了 80%，效果反而更好。Claude Code 通过 lazy loading（惰性加载）实现了 95% 的上下文压缩。 原则是：当前这一步，只暴露所需的最小工具集。

  7. Harness 厚度。 多少逻辑放 harness 里，多少留给模型。Anthropic 押注薄 harness 加上模型变强。基于图的框架押注显式控制。Anthropic 会随着新模型版本把 Claude Code harness 里的规划步骤删掉，因为模型已经把这个能力内化了。

Harness 才是产品

两个用同一个模型的产品，仅仅因为 harness 设计不同，性能可以天差地别。TerminalBench 的证据很清楚：仅替换 harness，agent 名次能挪 20 名以上。

Harness 不是已解决的问题，也不是商品化的层。它正是硬工程藏身的地方：把上下文当稀缺资源管、设计验证回路赶在错误复利前抓住失败、做记忆系统给得了连续性又不会幻觉、在"该搭多少脚手架"和"该把多少留给模型"之间下架构押注。

模型变强，整个领域往更薄的 harness 演进。但 harness 本身不会消失。哪怕最强的模型，也需要某个东西管它的上下文窗口、执行它的工具调用、持久化它的状态、验证它的工作。

下次你的 agent 出错时，别怪模型，看看 harness。

今天就到这。

如果你觉得这篇有用：

来这里找我 → @akshay_pachaar ✔️

我每天都会分享 AI、机器学习、vibe coding 的实践与教程。

原推文链接: https://x.com/akshay_pachaar/status/2041146899319971922