langchain deep-agents ai-agents context-engineering agent-architecture

为何长周期智能体需要工具集：深度智能体如何管理状态与上下文。

为何长时序智能体需要约束机制：LangChain Deep Agents如何通过四大支柱——中间件、文件系统后端以及隔离的子智能体——来应对上下文丢失问题。

发布者：REACTAPP.TOP加入本站 2026年10月28日阅读约 12 分钟2727 词

来源: The Deep Agents Architecture, Part 1: Understanding the Agent Harness

最基础的智能体设计就是围绕工具调用的循环。模型读取请求，选择工具并执行它，然后读取输出结果，再次做出选择并持续循环，直到停止调用工具为止。LangChain明确指出了这种设计的局限性：这类智能体较为“肤浅”，无法规划并处理漫长而复杂的任务。这并非某个框架独有的缺陷，而是由于在模型与不断扩展的上下文之间没有设置任何中间层所导致的后果。

证明天花板确实存在结构性限制的最有力证据来自三个从未相互协作的团队。Anthropic在开发Claude Code时遇到了这一问题，OpenAI在Deep Research项目中也遇到了，而Butterfly Effect遇到的问题更为严重，以至于Manus不得不被重新构建了四次。它们都指向相同的四个核心要素：规划工具、对子智能体的任务分配、文件系统访问权限以及详细的提示词。不同公司独立研发出的方案却都采用了相同的架构，这表明是问题本身决定了架构形式，而非任何人的个人偏好。

上下文失效才是真正的原因

人们很容易认为智能体长时间运行失败是因为上下文窗口被填满，但那并非真正的原因。

即使模型的上下文窗口仍有大量空余，进行长时间对话时的表现也会比进行短时间对话时更差。随着周围token数量的增加，每个token可获得的注意力资源会逐渐减少，而在窗口未满之前，不断下降的信噪比就已经会影响输出质量。这一现象有文献记载，并非个别案例：模型确实更难以从长上下文的中间部分获取信息，而更倾向于使用开头和结尾附近的token。

这改变了解决问题的思路。如果问题是容量不足，那么扩大窗口就能解决。但实际上问题在于信息稀释：模型本身仍具备相应能力，但它所需的信息被之前出现的所有内容所掩盖。这是信息组织问题而非容量问题，额外的窗口空间无法改善这种信息组织状况。

LangChain与LangGraph都无法填补的差距

LangGraph注重持久执行能力：通过检查点、流式处理、人工审核以及跨线程持久化机制来实现。它真正的对应框架是Temporal，而非其他智能体框架。该框架能确保智能体在崩溃后仍能继续运行，但并未说明四小时之后智能体是否仍能清晰思考。LangChain则处于更高层次，提供了工具调用循环、结构化内容处理以及自定义中间件等抽象功能。不过，基于这些抽象功能构建的默认循环仍属于上文所述的那种浅层循环。持久性及抽象化功能确实重要且不可或缺，但它们都无法说明模型的工作上下文是否保持整洁。

这可以通过各组件的连接方式来验证。Deep Agents声明的依赖项为langchain、langchain-core、langchain-anthropic、langchain-google-genai以及langsmith，LangGraph并不在列表中，它之所以出现只是因为LangChain依赖于它。这种结构是严格嵌套的，即Deep Agents依赖于LangChain，而LangChain又依赖于LangGraph，而非三个独立组件简单叠加。在运行时或框架层中根本不存在负责管理上下文状态的功能，因为本应承担此职责的层位于这两者之上。

核心观点：这是状态问题，而非推理问题

对于某一类特定且定义明确的复杂任务而言，其本质是状态管理问题，而非推理问题。

有一种简单的方法可以判断一项任务属于哪种类型的问题。想象一下，有一位技术娴熟的同事，但每隔十分钟就会失去所有记忆。如果这位同事无法完成工作，那说明这项工作依赖于状态记忆；而通过做好记录、合理分配任务以及针对记忆丧失情况建立相应的应对机制，就能解决这个问题。但如果是一个始终将整个问题牢记在心的人也会感到无从下手，那么即便记录了信息也无济于事，因为问题的难点从一开始就在于推理过程。

任务管理系统添加的每一项机制，无论是用于卸载任务的文件系统、用于隔离的子代理，还是用于跟踪进度的规划工具，都是为了解决遗忘问题。但这些机制并不会让任何单一的推理步骤变得更聪明。因此，状态管理并非推理的竞争对手，而是让推理能够通过多个步骤逐步推进、而不会在每一步都重置的基础。即便一个模型在每一步的推理都是正确的，如果第150步无法知晓第12步的决策结果，它依然可能无法完成需要200步的任务。问题并不出在推理本身，而在于它缺乏连贯性可供利用。

仅靠这一基础是不够的，若假装它足够，将会削弱整个论证的可靠性。在正确的完整历史记录显而易见的情况下仍坚持使用无效策略，纯粹是推理上的失误，而完美的状态管理也无法弥补这一缺陷。同样，即便真实记录完好且可获取，若模型对事件的描述与实际情况存在偏差，那也存在推理问题。该主张的合理表述应为：对于那些因超出单一有效上下文范围而退化的任务，状态管理是起主导作用的关键因素，而推理质量则是更难解决的剩余问题，框架结构无法对其产生影响。以下内容将介绍三个团队为发挥这一作用所构建的技术。

由多个部分构成的四大支柱

Deep Agents是什么

Deep Agents 以 MIT 许可证的开源 Python 包形式发布，可通过 pip 安装，当前版本为 0.7.5。此外还有对应的 TypeScript 版本、名为 deepagents-code 的终端 CLI，以及仍处于私有测试阶段的托管管理版。它并非 LangChain 和 LangGraph 的直接竞争对手。如前所述，它直接依赖 LangChain，仅通过 LangChain 来使用 LangGraph 功能。调用 create_deep_agent() 实际上会调用 LangChain 的 create_agent()，进而生成 LangGraph 图结构，因此该智能体的持久性完全取决于 LangChain 所传递的参数。

四大核心组件及其底层技术栈

根据LangChain的说法，要让一个智能体具备深度，需要四个要素：规划工具、子智能体委托、文件系统访问权限以及丰富的提示词。哈里森·蔡斯在注意到Claude Code、Deep Research和Manus中存在相同的结构后提出了这一框架。作为一种思维模型，它非常有效，因为这四个要素确实区分了简单的循环处理与能够完成复杂任务的智能体。

“四”只是一个初步描述，并非最终方案。create_deep_agent()会从一系列日益扩充的中间件中组合出各项功能，这些中间件可以自由搭配使用。该列表涵盖了文件处理、子智能体、内容总结、工具调用的修复、与特定服务提供商相关的各类提示词缓存机制、内存管理、技能应用以及人工审核功能，还包括开发者自行编写的任何自定义模块。这些核心要素定义了智能体能够实现的功能，而中间件堆栈则决定了这些功能的具体实现方式，且会持续变化。

在架构上，堆栈中仅有两个部分是必需的，而且这一点比数量更为重要。FilesystemMiddleware是必需的，因为它负责执行控制文件访问的权限规则，某段源代码注释将其称为安全保障。SubAgentMiddleware也是必需的，因为它是task工具所调用的组件。如果缺少其中任意一个，都会引发错误，而不会悄无声息地降级运行。其余所有部分均为可选，仅在需要时才会被整合进去。

现在任何在此基础上进行开发的人都应该知道，最初的四个类别中有两个已改为可选功能。根据弃用通知，从 v0.7.0 版本起，规划工具（write_todos）不再属于默认配置，基础系统提示也会为空。要恢复这些功能，每个都需要一行配置。只需调用一次简单的 create_deep_agent() 即可立即获得文件访问权限和子代理委托功能，而规划功能及详细提示则需主动请求才能启用。

利用配置文件——较新模型所不具备的调优层

在中间件之下有一个名为“harness profile”的独立调优机制。该配置文件会添加额外的系统提示文本，并根据传递给智能体的具体模型字符串来移除某些工具。请勿将其与负责控制模型对象构建方式的ProviderProfile混淆。HarnessProfile则是在模型构建完成后用于调整其行为的。

查询时需要使用完全匹配的已注册 provider:model 键，若不存在则以提供方通用的配置作为备选。默认情况下，已为 OpenAI 的 Codex 系列以及三款 Claude 机型提供了配置文件：Haiku 4.5、Sonnet 4.6 和 Opus 4.7。Sonnet 4.6 的配置文件并非简单的提示词建议，而是严格遵循 Anthropic 自己发布的指导方针，代码中的注释也明确说明了这一点；同时它刻意省略了针对 Opus 机型关于过度急切及大量使用子智能体的警告，因为这些内容被认为对 Sonnet 不适用。

在已注册版本之后发布的模型将无法获得任何配置。通过解析器查询后，claude-sonnet-5、anthropic:claude-sonnet-5以及单纯的anthropic均无法返回任何配置文件。由于没有精确匹配的结果，且也没有可供回退的整个Anthropic平台的条目（仅存在绑定到特定版本的配置文件），因此没有任何匹配项。这种缺失是完全无声无息的。根据解析器自身的文档，唯一的日志记录是在使用平台级回退机制时才会产生的调试信息；如果两次查询都失败，则根本不会生成任何日志。

因此，基于快速迭代系列中最新模型构建的智能体，其配置实际上与基于框架从未听说过的模型构建的智能体完全相同，也就是没有任何配置，而且也看不出存在这种情况。

运行机制

一切背后的统一抽象层

所有这些中间件都基于 LangChain 所提供的单一机制，而非 Deep Agents。LangChain 1.0 添加了多个执行点：在运行开始或结束时、每次模型调用前后以及每次工具调用时，这使得单个智能体循环能够支持多种不同的设计。前置钩子会按照注册顺序触发，而后置钩子则按相反顺序触发，这一机制与 Web 框架中中间件的嵌套方式类似。包装钩子可以重试调用、从缓存中获取数据或完全拦截该调用。监督器配置、集群、反射循环以及 Deep Agents 其实都是带有不同钩子的同一个循环，而 create_deep_agent() 仅仅是其中一种特定的选择方式。

文件：两种后端，两种保障

文件可以存储在两个位置，哪个位置处于活跃状态决定了智能体的写入操作实际意味着什么。

StateBackend 是默认选项，它将文件存储在 LangGraph 状态通道中——即带有自身合并规则的图数据，而非磁盘上。该模式仅在实时图计算过程中生效。文件内容能否在单次调用之后仍然存在，取决于是否存在检查点以及稳定的线程 ID。如果没有这些要素，每次调用都会从空白状态开始，这也解释了为何单纯的 create_deep_agent() 调用总会显示为空的工作目录。

FilesystemBackend会执行真正的磁盘读写操作，因此在带来持久存储功能的同时也带来了实际风险。其文档明确指出，它适用于本地开发及CI/CD流程，但不适合用于任何面向用户的场景，因为该代理可以读取其能够访问的任何内容，包括敏感信息，且其所做的修改无法撤销。在默认的virtual_mode=True设置下，访问操作会被限制在根目录内，无论是原始路径还是解析后的路径都不允许遍历，同时真实的绝对路径也会从代理的输出中隐藏，从而避免泄露根目录的位置。

一个权限系统可同时管理这两者。规则会将操作与路径模式以及三种模式之一关联起来：允许、拒绝或中断。删除操作会依据写入规则进行仔细评估。如果存在任何拒绝规则与目标节点下的任意部分重叠，而不仅仅是第一个匹配的规则，那么递归删除将被拒绝，因此，早期的宽泛允许规则无法授权删除后来为保护该内容而设定的更严格的规则所覆盖的内容。

按设计隔离的子代理

访问子代理的方式与访问其他工具相同。当模型调用task时，会启动一个完全独立的代理，它拥有自己的模型、工具和中间件。其模型设置可以接受provider:model字符串或已构建的模型对象，因此将子代理部署在与父代理不同的提供者上仅需一行配置代码，无需复杂的工程操作。

记忆不会自动延续。子代理的规格中没有记忆字段，用于传递权限的逻辑也没有对应处理记忆的机制。这种隔离且纯净的上下文是刻意设计的，这意味着除非子代理拥有自己的记忆中间件，否则通过父代理记忆保存的任何内容对其而言都是不可见的。

记忆可修改，而非权威依据

记忆文件一旦被加载，并不会直接进入系统提示语。它会以带有明确标记的块形式出现，同时附有框架添加的指令，告知模型该内容属于可能过时或由他人编写的参考资料，而非必须无条件遵循的命令。其可信度低于系统提示语，这也符合其设计初衷：作为代理在工作时可以阅读并修改的内容，而非开发者编写后期望具有完全权威性的规则手册。

缩放细节

对话状态依赖于一个名为 DeltaChannel 的自定义还原器，其设计使得随着对话长度的增加，检查点存储以线性方式增长，即 O(N)，而非二次方增长，即 O(N²)。

边界情况处理

在决定在生产环境中在多大程度上依赖子代理之前，有两点情况需要了解，这两点均已通过当前代码库进行了验证。

一次故障，多重损失（问题编号#694）。如果多个子任务同时运行，其中一个出现异常，其余任务也会随之被取消。整个批次要么全部成功，要么全部失败，各任务之间没有隔离机制。该报告出自2026年1月的早期版本，该问题此后已被关闭，但用于修复它的代码变更既不在子任务代码中，也不在LangChain的工具执行层中找到。即便如此，仍需做好相应规划：在正式部署的版本得到确认之前，应将任何独立的子任务视为可能部分失败的情况。

错误显示给了错误的接收者（#947）。通常情况下，当工具返回错误后，模型应重新尝试或进行调整。但在某些观测到的运行中，模型直接以本应用于内部修正的文本告知最终用户，导致某些人看到了本不应显示给他们的错误信息。检查时该问题仍未解决。另一份报告指出，在后续的框架更新后，某些工具异常会直接终止代理程序的运行，而不会将错误信息作为可重试的消息传递给模型，而在早期版本中则仍会继续处理这些异常。

同一领域内的两份较早报告已处理完毕：子代理忽略父代理的递归限制问题（#1698）以及编辑和拒绝决策时导致恢复流程中断的问题（#554）。递归限制的修复方案也已通过实际安装的源代码进行了验证。这些案例表明该领域的问题往往能很快得到解决，因此无需更改现有设计。

实际可行的替代方案

目前构建长周期智能体有三种实用选择：Deep Agents、Claude Agent SDK以及OpenAI Agents SDK。每种方案都体现了团队在自身负责的内容与对外提供的功能方面的不同选择，且彼此之间并非不完整的版本关系。

有一个区别比其他任何区别都更易被混淆，那就是交接与子代理之间的差异。三种方案中有两种采用相同的底层模式，只是由不同的团队独立实现；第三种则是完全不同的机制。

在它们之间进行选择时，关键在于两个问题而非排名，而且这两个问题都没有通用答案。只有结合特定系统的实际约束才能给出答案。

要点总结

长时序智能体需要框架支撑，因为在时间窗口填满之前，累积的上下文就已经削弱了信号强度。深度智能体则基于四项核心原则构建此类框架，并依靠不断变化的中间件组合来实现，其中包括文件系统、子智能体以及内存，它们各自具有特定的功能保障与缺陷。了解这些缺陷——比如新模型存在的静默特征缺失、子智能体无法访问的内存、全有或全无的并行处理故障，以及会传导给用户的工具错误——正是有意识地使用该框架与盲目依赖其默认设置之间的区别。