# 代理工具的解剖结构
**作者**: Akshay
**日期**: 2026-04-06T13:31:58.000Z
**来源**: [https://x.com/akshay_pachaar/status/2041146899319971922](https://x.com/akshay_pachaar/status/2041146899319971922)
---
深入剖析 Anthropic、OpenAI、Perplexity 和 LangChain 的实际构建过程。内容涵盖编排循环、工具、内存、上下文管理以及其他所有将无状态逻辑逻辑模型 (LLM) 转变为功能强大的智能体的要素。
你已经构建了一个聊天机器人。也许你已经用一些工具连接了一个 ReAct 循环。它在演示中运行良好。然后你尝试构建生产级应用，结果却一团糟：模型忘记了三步之前的操作，工具调用静默失败，上下文窗口也充满了乱码。
问题不在于你的模型，而在于模型周围的一切。
LangChain 证明了这一点，他们只改变了 LLM 的底层架构（模型相同，权重相同），就从 TerminalBench 2.0 的前 30 名之外跃升至第 5 名。另一个研究项目通过让 LLM 优化底层架构本身，达到了 76.4% 的通过率，超过了手工设计的系统。
该基础设施现在有了名字： 代理框架 。
什么是代理线束？
该术语于 2026 年初正式确立，但其概念早在之前就已存在。“harness”（框架）指的是封装 LLM（逻辑逻辑模型）的完整软件基础设施：包括编排循环、工具、内存、上下文管理、状态持久化、错误处理和防护机制。Anthropic 的 Claude Code 文档对此进行了简洁的描述：SDK 是“为 Claude Code 提供支持的代理框架”。OpenAI 代理 ”和“harness 这两个术语等同起来， 指代使 LLM 发挥作用的
我非常喜欢 LangChain 的 Vivek Trivedy 提出的经典公式：“如果你不是模特，你就是束缚者。”
这里有个容易让人困惑的区别。“代理”指的是涌现行为：它是用户与之交互的、目标导向的、使用工具的、能够自我纠正的实体。“装置”则是产生这种行为的机制。当有人说“我构建了一个代理”时，他们的意思是他们构建了一个装置并将其与一个模型连接起来。
贝伦·米利奇在他 2023 年的文章中对此类比进行了精确的阐述。 脚手架式语言学习模型作为自然语言计算机。 原始的 LLM（逻辑逻辑模块）就是一个没有 RAM、没有磁盘、也没有 I/O 的 CPU。上下文窗口充当 RAM（速度快但容量有限）。外部数据库充当磁盘存储（容量大但速度慢）。工具集成充当设备驱动程序。操作系统就是框架。正如 Millidge 所写：“我们重新发明了冯·诺依曼架构”， 因为它对任何计算系统来说都是一种自然的抽象。
工程的三个层次
模型周围环绕着三个同心层的工程结构：
- 即时工程设计模型接收的指令。
- 上下文工程管理模型看到的内容以及何时看到的内容。
- 工具工程涵盖了以上两点，以及整个应用程序基础架构：工具编排、状态持久化、错误恢复、验证循环、安全强制执行和生命周期管理。
该组件并非对提示的简单封装，而是一个完整的系统，它使智能体能够实现自主行为。
生产线束的 12 个组成部分
综合 Anthropic、OpenAI、LangChain 以及更广泛的实践者社区的经验，一个生产代理框架包含十二个不同的组件。让我们逐一了解。
## 1. 编曲循环
这是核心机制。它实现了“思考-行动-观察”（TAO）循环，也称为“反应循环”。该循环的运行过程如下：组装提示符、调用 LLM、解析输出、执行任何工具调用、反馈结果，重复此过程直至完成。
从机制上看，它通常只是一个 while 循环。 复杂性在于循环所管理的一切 ，而非循环本身。Anthropic 将他们的运行时描述为一个“哑循环”，所有智能都存在于模型中。框架只负责管理转弯。
## 2. 工具
工具是智能体的双手。它们被定义为模式（名称、描述、参数类型），并注入到 LLM 的上下文中，以便模型了解哪些资源可用。工具层负责注册、模式验证、参数提取、沙盒执行、结果捕获以及将结果格式化为 LLM 可读的观测数据。
Claude Code 提供六大类工具：文件操作、搜索、执行、Web 访问、代码智能和子代理生成。OpenAI 的 Agents SDK 支持函数工具（通过）。@function_tool）、托管工具（WebSearch、CodeInterpreter、FileSearch）和 MCP 服务器工具。
## 3. 内存
记忆以多种时间尺度运作。 短期记忆是指单次会话中的对话历史。 长期记忆则跨越多个会话持续存在：人类学用途 CLAUDE.md 项目文件和自动生成的内存.md 文件；LangGraph 使用命名空间组织的 JSON 存储；OpenAI 支持由 SQLite 或 Redis 支持的会话。
Claude Code 采用三层架构：轻量级索引（每个条目约 150 个字符，始终加载）、按需加载的详细主题文件，以及仅可通过搜索访问的原始文本记录。一个关键的设计原则是： 代理将自身记忆视为“提示”，并在采取行动前将其与实际状态进行比对 。
## 4. 情境管理
很多智能体就是在这里悄无声息地失败的。核心问题在于上下文腐化： 当关键内容出现在窗口中间位置时，模型性能会下降 30%以上 （Chroma 的研究，以及斯坦福大学“迷失在中间”的研究结果都证实了这一点）。即使是百万级的窗口，随着上下文的增长，其指令执行能力也会下降。
生产策略包括：
- 压缩 ：在接近限制时总结对话历史记录（Claude Code 保留架构决策和未解决的错误，同时丢弃冗余的工具输出）
- 观察掩码 ：JetBrains 的 Junie 可以隐藏旧的工具输出，同时保持工具调用可见。
- 即时检索 ：维护轻量级标识符并动态加载数据（Claude Code 使用 grep、glob、head、tail 而不是加载整个文件）
- 子代理委托 ：每个子代理进行广泛探索，但仅返回 1,000 到 2,000 个令牌精简摘要。
Anthropic 的上下文工程指南指出，其目标是：找到尽可能小的高信号令牌集， 以最大限度地提高预期结果的可能性。
## 5. 快速施工
这汇总了模型在每个步骤中实际看到的内容。它是分层结构的：系统提示、工具定义、内存文件、对话历史记录和当前用户消息。
OpenAI 的 Codex 使用严格的优先级顺序：服务器控制系统消息（最高优先级）、工具定义、开发者指令、用户指令（级联）。 代理商.md 文件（32 KiB 限制），然后是对话历史记录。
## 6. 输出解析
现代工具框架依赖于原生工具调用，其模型返回的是结构化的 `tool_calls` 对象，而不是需要解析的自由文本。工具框架会检查：是否存在工具调用？如果存在，则执行它们并循环。如果没有工具调用？那就是最终结果。
对于结构化输出，OpenAI 和 LangChain 都支持通过 Pydantic 模型生成受模式约束的响应。诸如 RetryWithErrorOutputParser 之类的传统方法（它会将原始提示、失败的补全结果和解析错误反馈给模型）仍然可用于处理特殊情况。
## 7. 状态管理
LangGraph 模型的状态以类型化字典的形式在图节点间流动，reducer 负责合并更新。检查点设置在超级步骤边界，支持中断后恢复和时间旅行调试。OpenAI 提供了四种互斥的策略：应用程序内存、SDK 会话、服务器端 Conversations API 或轻量级的 previous_response_id 链。Claude Code 则采用了不同的方法： 使用 git 提交作为检查点，并将进度文件作为结构化的草稿 。
## 8. 错误处理
原因如下： 一个包含 10 个步骤的流程，即使每个步骤的成功率达到 99%，最终的成功率也只有约 90.4%。错误会迅速累积。
LangGraph 区分四种错误类型：瞬态错误（使用回退机制重试）、LLM 可恢复错误（将错误作为 ToolMessage 返回，以便模型进行调整）、用户可修复错误（中断以进行人工干预）和意外错误（向上冒泡以进行调试）。Anthropic 会在工具处理程序中捕获故障，并将其作为错误结果返回，以保持循环运行。Stripe 的生产环境将重试次数限制为两次。
## 9. 护栏和安全
OpenAI 的 SDK 实现了三个层级的防护机制：输入防护（在首次运行的智能体上执行）、输出防护（在最终输出上执行）和工具防护（在每次工具调用上执行）。“触发机制”会在触发时立即停止智能体的运行。
Anthropic 在架构上将权限执行与模型推理分离。模型决定尝试什么操作；工具系统决定允许什么操作。ClaudeCode 独立地控制着大约 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（代理代码 + 运行时）、应用服务器（双向 JSON-RPC API）和客户端界面（CLI、VS Code、Web 应用）。所有界面共享同一个框架，因此“Codex 模型在 Codex 界面上的体验优于通用聊天窗口”。
LangGraph 将代理组件建模为一个显式状态图。两个节点（llm_call 和 tool_node）通过一条条件边连接：如果存在工具调用，则路由到 tool_node；如果不存在，则路由到 END。LangGraph 由 LangChain 的 AgentExecutor 演变而来，后者在 v0.2 版本中被弃用，因为它难以扩展且缺乏多代理支持。LangChain 的深度代理明确使用了“代理组件”这一术语：内置工具、规划（write_todos 工具）、用于上下文管理的文件系统、子代理生成以及持久内存。
CrewAI 采用基于角色的多智能体架构：智能体（围绕 LLM 构建的框架，由角色、目标、背景故事和工具定义）、任务（工作单元）和团队（智能体的集合）。CrewAI 的流程层添加了“在关键之处赋予智能的确定性骨干”，负责管理路由和验证，而团队则负责自主协作。
AutoGen（后来发展成为 Microsoft Agent Framework）开创了对话驱动型编排的先河。其三层架构（核心、AgentChat、扩展）支持五种编排模式：顺序、并发（扇出/扇入）、群聊、交接和 Magentic（管理代理维护动态任务账簿以协调专家）。
脚手架隐喻
用脚手架作比喻并非花哨，而是十分贴切。建筑脚手架是一种临时性基础设施，它使工人能够建造原本无法到达的结构。脚手架本身并不进行建造，但如果没有它，工人就无法到达楼上。
关键洞见：脚手架会在建筑竣工后拆除。 随着模型的改进，工具的复杂性也应随之降低。Manus 在六个月内重建了五次，每次重写都降低了复杂性。复杂的工具定义简化为通用的 shell 执行。“管理代理”简化为结构化的交接流程。
这体现了协同进化原则 ：模型现在会在训练后使用特定的工具进行迭代。克劳德·科德的模型学会了如何使用它训练时使用的特定工具。由于这种紧密耦合，更改工具实现可能会降低性能。
线束设计的“面向未来的测试”：如果性能能够随着更强大的型号而提升，而无需增加线束的复杂性，则该设计是合理的。
决定每份安全带的七个关键决策
每位安全带设计人员都面临七种选择：
单智能体与多智能体。Anthropologie 和 OpenAI 都认为：应优先优化单智能体。多智能体系统会增加开销（额外的 LLM 调用用于路由，以及交接过程中上下文信息的丢失）。只有当工具过载超过约 10 个重叠工具，或者存在明显不同的任务领域时，才应考虑使用多智能体。
ReAct 与计划执行的比较。ReAct 在每一步都交错进行推理和执行（灵活但每步成本较高）。计划执行则将计划与执行分离。LLMCompiler 报告称，执行的速度提高了 3.6 倍 。
上下文窗口管理策略。 五种生成方法：基于时间的清除、对话摘要、观察掩蔽、结构化笔记和子代理委托。ACON 研究表明， 通过优先考虑推理轨迹而非原始工具输出，可以在保持 95% 以上准确率的同时，减少 26% 到 54% 的词元数量 。
验证循环设计。 计算验证（测试、代码检查工具）提供确定性的真实值。推理验证（LLM 作为评判者）可以发现语义问题，但会增加延迟。Martin Fowler 的 Thoughtworks 团队将其定义为指导 （前馈，行动前引导）与传感器 （反馈，行动后观察）。
权限和安全架构。 宽松型（速度快但风险高，大多数操作自动批准）与限制型（安全但速度慢，每个操作都需要批准）。选择哪种架构取决于部署环境。
工具范围策略。 工具越多，性能往往越差。Vercel 从 v0 版本中移除了 80% 的工具 ，并获得了更好的结果。Claude Code 通过延迟加载实现了 95% 的上下文缩减 。其原则是：仅暴露当前步骤所需的最小工具集。
框架厚度。 框架中包含的逻辑量与模型中包含的逻辑量之比。Anthropic 致力于构建精简的框架并不断改进模型。而基于图的框架则侧重于显式控制。随着新模型版本内部化该功能，Anthropic 会定期从 Claude Code 的框架中删除规划步骤。
安全带就是产品
两款使用相同模型的产品，仅因线束设计不同，性能就可能截然不同。TerminalBench 的数据清楚地表明：仅仅更换线束就能使代理的排名提升 20 位以上。
框架并非已解决的问题或通用层。它体现了真正的工程技术：将上下文作为一种稀缺资源进行管理，设计验证循环以在故障扩散之前将其捕获，构建提供连续性而不产生幻觉的内存系统，以及在架构上权衡构建多少框架以及将多少留给模型。
随着模型不断改进，该领域正朝着更轻量级的框架发展。但框架本身并不会消失。即使是最强大的模型也需要某种机制来管理其上下文窗口、执行工具调用、持久化状态并验证其运行结果。
下次你的代理出现故障时，不要责怪模型，而应该检查其底层架构。
拍摄结束！
如果您喜欢这篇文章：
找到我 →@akshay_pachaar ✔️
我每天都会分享关于人工智能、机器学习和 Vibe 编码最佳实践的教程和见解。
## 相关链接
- [Akshay](https://x.com/akshay_pachaar)
- [@akshay_pachaar](https://x.com/akshay_pachaar)
- [15K](https://x.com/akshay_pachaar/status/2041146899319971922/analytics)
- [脚手架式语言学习模型作为自然语言计算机。](https://www.beren.io/2023-04-11-Scaffolded-LLMs-natural-language-computers/)
- [@function_tool](https://x.com/@function_tool)
- [CLAUDE.md](http://claude.md/)
- [内存.md](http://memory.md/)
- [代理商.md](http://agents.md/)
- [针对跨越多个上下文窗口的长时间运行任务，Anthropic 开发了一种两阶段的“Ralph Loop”模式。](https://www.anthropic.com/research/long-running-Claude)
- [@akshay_pachaar](https://x.com/@akshay_pachaar)
- [升级至高级版](https://x.com/i/premium_sign_up)
- [9:31 PM · Apr 6, 2026](https://x.com/akshay_pachaar/status/2041146899319971922)
- [15.3K Views](https://x.com/akshay_pachaar/status/2041146899319971922/analytics)
- [View quotes](https://x.com/akshay_pachaar/status/2041146899319971922/quotes)
---
*导出时间: 2026/4/7 00:39:37*