Agent Harness 解剖：智能体框架的完整剖析

公众号名称：科技巫师的魔法书

作者名称：科技巫师的魔法书

发布时间：2026-04-18 22:51

原文作者：Akshay Pachaar（ @akshay_pachaar）
原文链接：https://x.com/akshay\_pachaar/status/2041146899319971922
发布时间：2026-04-06

深入剖析 Anthropic、OpenAI、Perplexity 和 LangChain 正在构建的真实技术——涵盖编排循环、工具、记忆、上下文管理，以及将无状态 LLM 转变为强大智能体所需的一切。

你已经搭建过聊天机器人，也许还连接过几个工具实现了 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。上下文窗口充当 RAM（快速但容量有限），外部数据库扮演磁盘存储（大但慢），工具集成则是设备驱动程序。Harness 就是操作系统。正如 Millidge 所写：“我们重新发明了冯·诺依曼架构”——因为它是任何计算系统的自然抽象。

工程的三个层次

围绕模型，存在三个同心的工程层次：

Prompt Engineering（提示词工程）：构造传递给模型的指令
Context Engineering（上下文工程）：管理模型在何时看到什么
Harness Engineering（框架工程）：涵盖前两者，加上整个应用基础设施——工具编排、状态持久化、错误恢复、验证循环、安全执行和生命周期管理

Harness 不是对 prompt 的包装，而是使自主智能体行为成为可能的完整系统。

生产级 Harness 的 12 个组件

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

1. 编排循环（Orchestration Loop）

这是系统的心跳。它实现了 Thought-Action-Observation（思考-行动-观察，简称 TAO）循环，也称为 ReAct 循环。流程为：组装提示词、调用 LLM、解析输出、执行任何工具调用、将结果反馈回来、重复直到完成。

从机制上看，它通常只是一个 while 循环。复杂性存在于循环所管理的一切之中，而不是循环本身。Anthropic 将他们的运行时描述为一个“笨循环”——所有的智能都存在于模型中，harness 只负责管理轮次。

2. 工具（Tools）

工具是智能体的双手。它们被定义为模式（名称、描述、参数类型）并注入 LLM 的上下文，让模型知道有什么可用。工具层负责注册、模式验证、参数提取、沙箱执行、结果捕获，以及将结果格式化为 LLM 可读的观察内容。

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

3. 记忆（Memory）

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

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

4. 上下文管理（Context Management）

这里是许多智能体悄悄失败的地方。核心问题是上下文腐烂（Context Rot）：当关键内容位于窗口中段时，模型性能会下降 30% 以上（Chroma 的研究，斯坦福的“迷失在中间”研究也证实了这一点）。即使是百万 token 的窗口，也会随着上下文增长而出现指令遵循能力退化。

生产环境中的策略包括：

压缩（Compaction）：接近限制时对对话历史进行摘要（Claude Code 保留架构决策和未解决的 bug，同时丢弃冗余的工具输出）
观察掩码（Observation Masking）：JetBrains 的 Junie 隐藏旧的工具输出，但保留可见的工具调用
即时检索（Just-in-time Retrieval）：维护轻量标识符并动态加载数据（Claude Code 使用 grep、glob、head、tail，而不是加载整个文件）
子智能体委派：每个子智能体深入探索，但只返回 1000-2000 token 的浓缩摘要

Anthropic 的上下文工程指南阐明了目标：找到尽可能小的、高信噪比的 token 集合，使期望结果的可能性最大化。

5. 提示词构建（Prompt Construction）

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

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

6. 输出解析（Output Parsing）

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

对于结构化输出，OpenAI 和 LangChain 都通过 Pydantic 模型支持受模式约束的响应。对于边缘情况，像 RetryWithErrorOutputParser（将原始提示词、失败的补全和解析错误反馈给模型）这样的传统方法依然可用。

7. 状态管理（State Management）

LangGraph 将状态建模为流经图节点的类型化字典，通过 reducers 合并更新。检查点在超级步骤边界触发，使中断后恢复和时间旅行调试成为可能。OpenAI 提供四种互斥策略：应用记忆、SDK sessions、服务端 Conversations API，或轻量级的 previous_response_id 链式调用。Claude Code 则采取不同的路径：将 git commit 作为检查点，进度文件作为结构化暂存区。

8. 错误处理（Error Handling）

这一点至关重要：一个 10 步的流程，即使每步成功率 99%，端到端成功率也只有约 90.4%。错误会快速累积。

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

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

OpenAI 的 SDK 实现了三个层级：输入护栏（在首个智能体上运行）、输出护栏（在最终输出上运行）、工具护栏（在每次工具调用上运行）。“绊线”机制在触发时立即停止智能体。

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

10. 验证循环（Verification Loops）

这是区分玩具演示与生产级智能体的关键。Anthropic 推荐三种方法：基于规则的反馈（测试、linter、类型检查器）、视觉反馈（通过 Playwright 截图处理 UI 任务），以及 LLM 作为评判者（由独立的子智能体评估输出）。

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

11. 子智能体编排（Subagent Orchestration）

Claude Code 支持三种执行模型：

Fork：父上下文的字节级拷贝
Teammate：独立终端窗格，通过基于文件的邮箱通信
Worktree：每个智能体独占的 git worktree 和隔离分支

OpenAI 的 SDK 支持“agents-as-tools”（专家处理有限子任务）和“handoffs”（专家接管完全控制）。LangGraph 则将子智能体实现为嵌套的状态图。

循环的运作：一步步走完完整周期

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

第 1 步（提示词组装）：Harness 构造完整输入——系统提示词 + 工具模式 + 记忆文件 + 对话历史 + 当前用户消息。重要上下文被放置在提示词的开头和结尾（“迷失在中间”研究结论）。

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

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

第 4 步（工具执行）：对于每次工具调用，harness 验证参数、检查权限、在沙箱环境中执行并捕获结果。只读操作可并发运行，修改操作串行执行。

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

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

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

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

对于跨越多个上下文窗口的长时间任务，Anthropic 开发了两阶段“Ralph Loop”模式：一个 Initializer Agent 设置环境（初始化脚本、进度文件、功能列表、初始 git commit），然后每个后续会话中的 Coding Agent 读取 git log 和进度文件来定位自己，选择优先级最高的未完成功能，执行工作、提交，并编写摘要。文件系统为跨上下文窗口提供了连续性。

真实框架如何实现这一模式

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

OpenAI 的 Agents SDK 通过 Runner 类实现 harness，有三种模式：异步、同步和流式。SDK 是“代码优先”的——工作流逻辑用原生 Python 表达，而不是图 DSL。Codex harness 扩展了这一点，采用三层架构：Codex Core（智能体代码 + 运行时）、App Server（双向 JSON-RPC API）和客户端界面（CLI、VS Code、Web 应用）。所有界面共享同一个 harness，这就是“Codex 模型在 Codex 界面上的表现比通用聊天窗口更好”的原因。

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

CrewAI 实现基于角色的多智能体架构：Agent（包裹 LLM 的 harness，由角色、目标、背景故事和工具定义）、Task（工作单元）和 Crew（智能体集合）。CrewAI 的 Flows 层添加了“确定性骨干与需要智能之处的智能”，管理路由和验证，而 Crews 处理自主协作。

AutoGen（正演变为 Microsoft Agent Framework）开创了对话驱动的编排。其三层架构（Core、AgentChat、Extensions）支持五种编排模式：顺序、并发（fan-out/fan-in）、群聊、交接和 magentic（一个管理者智能体维护动态任务账本协调专家们）。

脚手架隐喻

脚手架这个比喻并非装饰性修辞，而是精确的描述。建筑脚手架是临时基础设施，让工人能够够到他们本来够不到的地方，建造本来无法建造的结构。脚手架本身不进行施工，但没有它，工人无法到达高层。

关键洞察：建筑完工后，脚手架会被拆除。随着模型能力的提升，harness 的复杂性应当降低。Manus 在六个月内被重写五次，每次重写都在削减复杂性。复杂的工具定义变成了通用的 shell 执行，“管理智能体”变成了简单的结构化交接。

这指向了协同进化原则：模型现在是在特定 harness 存在的情况下进行后训练的。Claude Code 的模型学会了使用它训练时所搭配的特定 harness。改变工具实现可能会降低性能——因为这种耦合非常紧密。

Harness 设计的**“面向未来测试”**：如果在不增加 harness 复杂性的情况下，性能能随更强大的模型而扩展，那么这个设计就是合理的。

定义每个 Harness 的七个决策

每个 harness 架构师都面临七项选择：

单智能体 vs. 多智能体：Anthropic 和 OpenAI 都建议：先将单智能体做到极致。多智能体系统增加开销（路由的额外 LLM 调用、交接时的上下文丢失）。只有当工具过载超过约 10 个重叠工具或存在明显分离的任务域时才拆分。
ReAct vs. Plan-and-Execute：ReAct 在每一步交错推理和行动（灵活但单步成本更高）。Plan-and-Execute 将规划与执行分离。LLMCompiler 报告比顺序 ReAct 快 3.6 倍。
上下文窗口管理策略：五种生产方法——基于时间的清理、对话摘要、观察掩码、结构化笔记、子智能体委派。ACON 研究表明，通过优先保留推理轨迹而非原始工具输出，可以在保持 95%+ 准确率的同时将 token 减少 26% 到 54%。
验证循环设计：计算验证（测试、linter）提供确定性的事实基础。推理验证（LLM 作为评判者）捕获语义问题但增加延迟。Martin Fowler 的 Thoughtworks 团队将其框定为“引导”（前馈，在行动前引导）与“传感器”（反馈，在行动后观察）的对比。
权限与安全架构：宽松（快但有风险，自动批准多数行动）vs. 严格（安全但慢，每次行动都需要批准）。取决于部署场景。
工具范围策略：工具更多往往意味着性能更差。Vercel 从 v0 中移除了 80% 的工具，获得了更好的结果。Claude Code 通过惰性加载实现了 95% 的上下文减少。原则：只暴露当前步骤所需的最小工具集。
Harness 的“厚度”：多少逻辑住在 harness 里，多少住在模型里。Anthropic 押注于薄 harness 和模型改进。基于图的框架押注于显式控制。Anthropic 定期从 Claude Code 的 harness 中删除规划步骤，因为新版模型已将该能力内化。

Harness 就是产品

使用相同模型的两个产品，可以仅因 harness 设计的不同而表现迥异。TerminalBench 的证据很清楚：仅改变 harness，就让智能体的排名变化了 20 多位。

Harness 不是已解决的问题，也不是商品化层。它是困难的工程实实在在存在的地方——将上下文作为稀缺资源进行管理、设计在失败累积之前就捕获它们的验证循环、构建提供连续性但不幻觉的记忆系统、并就“构建多少脚手架 vs. 交给模型多少”做出架构性的押注。

随着模型的进步，这个领域正朝着更薄的 harness 方向发展。但 harness 本身不会消失。即使是最强大的模型，也需要某种东西来管理它的上下文窗口、执行它的工具调用、持久化它的状态并验证它的工作。

下次你的智能体失败时，不要怪模型——看看你的 harness。

本文原作者：@akshay_pachaar，每天分享关于 AI、机器学习和氛围编码的教程与见解。

Original 科技巫师的魔法书科技巫师的魔法书

内容效果不满意？点此反馈