智能体框架剖析
生产级AI智能体的成败不在模型本身，而在包裹模型的完整基础设施——即“智能体框架”（agent harness）——它才是承载硬核工程、决定性能上限的关键。
深入剖析Anthropic、OpenAI、Perplexity和LangChain实际构建的内容。涵盖编排循环、工具、记忆、上下文管理，以及所有将无状态LLM转变为强大智能体的其他要素。
你已经构建了一个聊天机器人。也许你已用几个工具搭建了一个ReAct循环。它在演示中表现良好。但当你尝试构建生产级应用时，问题接踵而至：模型忘记了三步前的操作，工具调用悄然失败，上下文窗口被垃圾信息填满。
问题不在于你的模型，而在于模型周围的一切。
LangChain证明了这一点：他们仅更改了包裹LLM的基础设施（相同模型、相同权重），就在TerminalBench 2.0上从30名开外跃升至第5名。另一项独立研究项目通过让LLM自行优化基础设施，达到了76.4%的通过率，超越了手工设计的系统。
这种基础设施如今有了名字：智能体框架。
什么是 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 年的文章“Scaffolded LLMs as Natural Language Computers.”中精确阐述了这个类比。原始 LLM 是一个没有 RAM、没有磁盘、没有 I/O 的 CPU。上下文窗口充当 RAM（快速但有限）。外部数据库充当磁盘存储（大但慢）。工具集成充当设备驱动程序。Harness 是操作系统。正如 Millidge 所写：“我们重新发明了冯·诺依曼架构”，因为这是任何计算系统的自然抽象。
工程的三个层次
围绕模型，工程分为三个同心层次：
- 提示工程 精心设计模型接收的指令。
- 上下文工程 管理模型所见内容及其时机。
- 框架工程 涵盖上述两者，外加整个应用基础设施：工具编排、状态持久化、错误恢复、验证循环、安全执行及生命周期管理。
框架并非提示的简单包装。它是使自主智能体行为成为可能的完整系统。
生产级框架的12个组件
综合Anthropic、OpenAI、LangChain及更广泛的实践者社区的经验，生产级智能体框架包含十二个不同组件。让我们逐一探讨。
1. 编排循环
这是系统的心脏。它实现思考-行动-观察（TAO）循环，亦称ReAct循环。循环运行流程为：组装提示、调用LLM、解析输出、执行任何工具调用、将结果反馈，如此重复直至完成。
机制上，它往往只是一个while循环。复杂性蕴含于循环所管理的方方面面，而非循环本身。Anthropic将其运行时描述为傻瓜循环，所有智能都存在于模型中。框架仅负责管理轮次。
2. 工具
工具是代理的双手。它们被定义为模式（名称、描述、参数类型），注入到LLM的上下文中，使模型知晓可用资源。工具层负责注册、模式验证、参数提取、沙箱执行、结果捕获，以及将结果格式化回LLM可读的观察信息。
Claude Code提供六大类工具：文件操作、搜索、执行、网页访问、代码智能和子代理生成。OpenAI的Agents SDK支持函数工具（通过@function_tool）、托管工具（WebSearch、CodeInterpreter、FileSearch）以及MCP服务器工具。
3. 记忆
记忆在多个时间尺度上运作。短期记忆是单次会话内的对话历史。长期记忆跨会话持久存在：Anthropic使用CLAUDE.md项目文件和自动生成的MEMORY.md文件；LangGraph使用按命名空间组织的JSON存储；OpenAI支持由SQLite或Redis支撑的会话。
Claude Code实现了三层级结构：轻量索引（每条约150字符，始终加载）、按需拉取的详细主题文件，以及仅通过搜索访问的原始转录。一个关键设计原则：代理将其自身记忆视为提示，并在行动前对照实际状态进行验证。
4. 上下文管理
这是许多代理悄然失败之处。核心问题在于上下文腐化：当关键内容落在窗口中部位置时，模型性能下降超过30%（Chroma研究，与斯坦福大学的“迷失在中间”发现相印证）。即便是百万级令牌的窗口，随着上下文增长，指令遵循能力也会退化。
生产环境中的策略包括：
- 压缩：在接近限制时总结对话历史（Claude Code保留架构决策和未解决的bug，同时丢弃冗余的工具输出）
- 观察遮蔽：JetBrains的Junie隐藏旧工具输出，同时保持工具调用可见
- 即时检索：维护轻量级标识符，动态加载数据（Claude Code使用grep、glob、head、tail而非加载完整文件）
- 子代理委派：每个子代理广泛探索，但仅返回1000至2000个令牌的浓缩摘要
Anthropic的上下文工程指南阐述了目标：找到最小可能的高信号令牌集合，以最大化期望结果的可能性。
5. 提示构建
这一步整合了模型在每个步骤中实际看到的内容。其结构是分层的：系统提示、工具定义、记忆文件、对话历史以及当前用户消息。
OpenAI 的 Codex 采用严格的优先级堆栈：服务器控制的系统消息（最高优先级）、工具定义、开发者指令、用户指令（级联的 AGENTS.md 文件，限制为 32 KiB），然后是对话历史。
6. 输出解析
现代框架依赖原生工具调用，即模型返回结构化的 tool_calls 对象，而非需要解析的自由文本。框架会检查：是否存在工具调用？若有，则执行并循环；若无，则视为最终答案。
对于结构化输出，OpenAI 和 LangChain 均支持通过 Pydantic 模型进行模式约束的响应。传统方法如 RetryWithErrorOutputParser（将原始提示、失败的完成结果及解析错误反馈给模型）仍可用于处理边缘情况。
7. 状态管理
LangGraph 将状态建模为流经图节点的类型化字典，并通过归约器合并更新。检查点发生在超级步骤边界，使得中断后恢复和时光倒流式调试成为可能。OpenAI 提供了四种互斥的策略：应用内存、SDK 会话、服务器端对话 API，或轻量级的 previous_response_id 链式调用。Claude Code 则采取了不同的方法：将 git 提交作为检查点，并将进度文件作为结构化的暂存笔记。
8. 错误处理
这就是关键所在：一个包含 10 个步骤、每步成功率 99% 的流程，其端到端成功率仍只有约 90.4%。错误会迅速累积。
LangGraph 区分了四种错误类型：瞬时错误（通过退避重试）、LLM 可恢复错误（将错误作为 ToolMessage 返回，以便模型进行调整）、用户可修复错误（中断以等待人工输入）以及意外错误（向上抛出以便调试）。Anthropic 在工具处理器内捕获失败，并将其作为错误结果返回，以保持循环持续运行。Stripe 的生产环境将重试次数上限设定为两次。
9. 护栏与安全
OpenAI的SDK实现了三个层级：输入护栏（在首个智能体上运行）、输出护栏（在最终输出上运行）以及工具护栏（在每次工具调用时运行）。一种“绊线”机制在触发时立即中止智能体。
Anthropic在架构上将权限执行与模型推理分离。模型决定尝试什么；工具系统决定允许什么。Claude Code独立门控约40种离散工具能力，分为三个阶段：项目加载时建立信任，每次工具调用前进行权限检查，以及高风险操作需用户明确确认。
10. 验证循环
这是区分玩具演示与生产级智能体的关键。Anthropic推荐三种方法：基于规则的反馈（测试、代码检查器、类型检查器）、视觉反馈（通过Playwright进行UI任务的截图）以及LLM作为评审（一个独立的子智能体评估输出）。
Claude Code的创造者Boris Cherny指出，让模型能够验证其工作可将质量提升2至3倍。
11. 子代理编排
Claude Code支持三种执行模式：Fork（父上下文的字节级相同副本）、Teammate（独立终端面板，基于文件的邮箱通信）和Worktree（每个代理拥有独立的git工作树和分支）。OpenAI的SDK支持代理即工具（专家处理有限子任务）和交接（专家完全接管）。LangGraph将子代理实现为嵌套状态图。
循环运行：逐步详解
既然你已经了解了各个组件，让我们追踪它们在单个周期中如何协同工作。
步骤1（提示组装）：框架构建完整输入：系统提示 + 工具模式 + 记忆文件 + 对话历史 + 当前用户消息。重要上下文被放置在提示的开头和结尾（“迷失在中间”发现）。
步骤2（LLM推理）：组装好的提示发送至模型API。模型生成输出令牌：文本、工具调用请求，或两者兼有。
步骤3（输出分类）：如果模型生成的是无工具调用的文本，循环结束。如果请求了工具调用，则进入执行阶段。如果请求了交接，则更新当前代理并重新开始。
步骤4（工具执行）：对于每个工具调用，框架验证参数、检查权限、在沙盒环境中执行并捕获结果。只读操作可并发运行；修改操作串行执行。
步骤5（结果打包）：工具结果被格式化为LLM可读的消息。错误被捕获并作为错误结果返回，以便模型自我纠正。
步骤6（上下文更新）：结果被追加到对话历史中。如果接近上下文窗口限制，框架触发压缩。
步骤7（循环）：返回步骤1。重复直到终止。
终止条件是分层的：模型生成无工具调用的响应、超过最大轮次限制、令牌预算耗尽、触发护栏绊线、用户中断，或返回安全拒绝。一个简单的问题可能只需1到2轮。而复杂的重构任务则可能跨多轮串联数十次工具调用。
对于跨越多个上下文窗口的长时任务，Anthropic 开发了一种两阶段的“Ralph Loop”模式：一个初始化代理负责搭建环境（初始化脚本、进度文件、功能列表、初始 git 提交），随后在每一个后续会话中，编码代理通过读取 git 日志和进度文件来定位自身状态，挑选优先级最高的未完成功能，进行开发、提交并撰写摘要。文件系统为跨上下文窗口提供了连续性。
实际框架如何实现该模式
Anthropic 的 Claude Agent SDK 通过一个单一的 query() 函数暴露了执行框架，该函数创建代理循环并返回一个异步迭代器以流式传输消息。运行时是一个“简单循环”。所有智能都存在于模型中。Claude Code 采用“收集-行动-验证”循环：收集上下文（搜索文件、读取代码）、采取行动（编辑文件、运行命令）、验证结果（运行测试、检查输出），然后重复。
OpenAI 的 Agents SDK 通过 Runner 类实现执行框架，提供三种模式：异步、同步和流式。该 SDK 是“代码优先”的：工作流逻辑用原生 Python 表达，而非图 DSL。Codex 执行框架在此基础上扩展为三层架构：Codex Core（代理代码 + 运行时）、App Server（双向 JSON-RPC API）和客户端界面（CLI、VS Code、Web 应用）。所有界面共享同一执行框架，这正是“Codex 模型在 Codex 界面上比在通用聊天窗口中体验更好”的原因。
LangGraph 将执行框架建模为显式的状态图。两个节点（llm_call 和 tool_node）通过条件边连接：若存在工具调用，则路由至 tool_node；否则路由至 END。LangGraph 源自 LangChain 的 AgentExecutor，后者因难以扩展且缺乏多智能体支持而在 v0.2 中被弃用。LangChain 的 Deep Agents 明确使用智能体执行框架这一术语：内置工具、规划（write_todos 工具）、用于上下文管理的文件系统、子智能体生成以及持久化记忆。
CrewAI 实现了基于角色的多智能体架构：Agent（围绕 LLM 的执行框架，由角色、目标、背景故事和工具定义）、Task（工作单元）以及 Crew（智能体集合）。CrewAI 的 Flows 层增加了“在关键处具备智能的确定性主干”，管理路由和验证，而 Crews 则负责自主协作。
AutoGen（正演进为 Microsoft Agent Framework）开创了对话驱动的编排方式。其三层架构（Core、AgentChat、Extensions）支持五种编排模式：顺序、并发（扇出/扇入）、群聊、交接以及 magentic（一个管理者智能体维护动态任务台账，协调各专家智能体）。
脚手架隐喻
脚手架隐喻并非装饰性的，而是精确的。建筑脚手架是临时性基础设施，让工人能够建造他们原本无法触及的结构。它本身不参与建造，但没有它，工人便无法到达更高的楼层。
关键洞见：建筑完工时，脚手架会被拆除。随着模型能力的提升，工具链的复杂度应当下降。Manus 在六个月内被重建了五次，每一次重写都在削减复杂度。复杂的工具定义演变为通用的 shell 执行方式。“管理型智能体”变成了简单的结构化交接。
这指向了协同进化原则：如今，模型在训练后阶段会将特定工具链纳入循环。Claude Code 的模型学会了使用其训练时所配套的特定工具链。由于这种紧密耦合，更改工具实现可能会导致性能下降。
工具链设计的面向未来测试是：如果性能能随更强大的模型而提升，且无需增加工具链复杂度，那么该设计就是稳健的。
定义每个 Harness 的七个决策
每位 Harness 架构师都面临七个选择：
- 单代理 vs. 多代理。 Anthropic 和 OpenAI 都表示：优先最大化单个代理。多代理系统会增加开销（路由需要额外的 LLM 调用，交接过程中会丢失上下文）。仅在工具过载超过约 10 个重叠工具或存在明确分离的任务域时才拆分。
- ReAct vs. 计划-执行。 ReAct 在每一步都将推理和行动交织在一起（灵活但每步成本更高）。计划-执行将规划与执行分离。LLMCompiler 报告称，相比顺序 ReAct，其速度提升了 3.6 倍。
- 上下文窗口管理策略。 五种生产级方法：基于时间的清理、对话摘要、观察掩蔽、结构化笔记和子代理委派。ACON 研究表明，通过优先考虑推理轨迹而非原始工具输出，token 减少 26% 至 54%，同时保持 95% 以上的准确率。
- 验证循环设计。 计算验证（测试、linter）提供确定性的基础事实。推断验证（LLM 作为评判者）能捕捉语义问题，但会增加延迟。Martin Fowler 的 Thoughtworks 团队将其框架化为指南（前馈，在行动前引导）与传感器（反馈，在行动后观察）。
- 权限与安全架构。 宽松型（快速但有风险，自动批准大多数操作）与严格型（安全但缓慢，每个操作都需批准）。选择取决于部署环境。
- 工具范围界定策略。 工具越多往往意味着性能越差。Vercel 从 v0 中移除了 80% 的工具，结果反而更好。Claude Code 通过懒加载实现了 95% 的上下文缩减。原则是：仅暴露当前步骤所需的最小工具集。
- 工具层厚度。 有多少逻辑存在于工具层中，又有多少留给了模型本身。Anthropic 倾向于薄工具层与模型改进。基于图结构的框架则倾向于显式控制。Anthropic 会随着新模型版本内化某些能力，定期从 Claude Code 的工具层中删除规划步骤。
工具层即产品
使用相同模型的两个产品，仅因工具层设计不同，性能可能天差地别。TerminalBench 的证据清晰明了：仅改变工具层，就让智能体的排名移动了 20 多位。
工具层并非已解决的问题，也不是一个通用层。它承载着硬核工程：将上下文视为稀缺资源进行管理，设计能在错误累积前捕获它们的验证循环，构建既能提供连续性又不产生幻觉的记忆系统，以及做出关于该构建多少脚手架、又该留多少给模型的架构决策。
随着模型能力的提升，该领域正朝着更薄的工具层发展。但工具层本身不会消失。即使是最强大的模型，也需要某种东西来管理其上下文窗口、执行工具调用、持久化状态并验证其工作。
下次你的智能体失败时，别怪模型。看看工具层。
这就是全部内容！