最详细的 DeepAgents 实战拆解：一次看懂LangChain全新深度智能体框架

发布日期：2025-11-17 15:28:33 浏览次数： 5710

作者：AI大模型应用实践

微信搜一搜，关注“AI大模型应用实践”

前段时间LangChain 公司终于正式发布LangChain 1.0版本及其配套的LangGraph 1.0，标志着其通用 Agent 框架趋于成熟。在此基础上，LangChain 团队还推出了一个全新的开源项目DeepAgents，旨在进一步提升Agent 在复杂场景下的能力，用更少的代码完成更"Deep"的任务。

本文将为你带来 DeepAgents 的深入解读与实战体验。本文内容如下：

DeepAgents：框架定位与能力速览

用实例读懂 DeepAgents：三大核心机制
DeepAgents原理总结与未来展望

【本文源代码见文末】

DeepAgents：框架定位与能力速览

我们最熟悉的一种 Agent 形态，就是让 LLM 在推理循环中调用工具，并最终完成任务。但在复杂环境下，这类 Agent 往往会显得有些“脆弱”：任务步骤不合理、工具调用错误、上下文不断膨胀、甚至遗忘任务目标；缺乏主动规划步骤、管理中间变量、以及优化上下文的能力。

如果你在 LangChain 生态中开发，可以通过 LangGraph 从底层掌控工作流，例如：什么时候由 AI 决策、什么时候固化流程；使用 ReAct 还是 Plan-then-Execute 等范式 —— 但实现复杂度相对较高。

DeepAgents正是为了解决上述痛点而诞生。其出发点可用一句话概括：

让复杂、多步骤、长时间运行的Agent更容易开发与构建。

【DeepAgents是什么？】

DeepAgents 是 LangChain 公司在 LangGraph 与 LangChain 之后推出的第三个独立开源 Agent 框架，与前两者形成清晰分工：

在最新的LangChain 1.0版本中，这三者开发Agent的定位是：

LangGraph：提供持久化与可观测的Runtime，用于构建底层工作流与Agent。
LangChain：基于 LangGraph 的高层封装，提供更简洁的 Agent 接口（create_agent）与扩展中间件机制。
DeepAgents：在 LangChain 的高层接口 + LangGraph 的运行时之上，进一步封装形成“深度 Agent”框架。其核心方法 create_deep_agent，其实就是在 create_agent 之上增加了预置的系列中间件能力。

【DeepAgents增加了哪些能力？】

目前在复杂任务Agent领域最成功的有两类：编程智能体与深度研究智能体（也是笔者最常用的两类AI工具）。DeepAgents也受到这一类应用的启发 — 这些“深度 Agent”通过增加任务规划工具、子Agent、文件系统、详细提示等手段，在实践中突破了传统 Agent 的局限。

DeepAgents将这些经验抽象为通用框架，开箱即用地提供任务规划、文件系统、长期记忆、分工协作等能力：

稍后我们将用一个完整的实例来体验DeepAgents的这些独特能力。

【什么时候选择DeepAgents？】

理解了DeepAgents/LangChain/LangGraph三者的分层定位，这个问题可以简单的总结为：

当你需要构建复杂的多步骤、长时间运行的Agent；并希望拥有任务规划、文件系统、长期记忆等能力时，考虑DeepAgents。

而对于一些简单步骤的任务，直接使用 LangChain 提供的create_agent就已经足够。

通过 DeepAgents，开发者无需从零开始设计长流程 Agent，只需提供自定义工具和任务说明等，就能快速构建一个强大的“深度 Agent” 。

实例读懂DeepAgents：三大核心机制

我们将从构建一个最简单的Agent开始，并逐步细化与丰富其能力。在这个过程中你将可以清晰的看到：

DeepAgents是如何在LangGraph与LangChain的基础上“添砖加瓦”，以适应更复杂的任务环境。

首先设计一个简单的场景：

构建一个借助于搜索与金融数据接口等工具进行股票分析的Agent。

【初始版本构建】

最初这个Agent看上去是一个标准的ReAct范式Agent，唯一区别在于使用create_deep_agent而不是LangChain的create_agent（前身是LangGraph中的create_react_agent）：

...
# === 系统指令 ===
SYSTEM_PROMPT = """你是一个股票分析助手。
你的任务是帮助用户分析股票，使用 search 工具搜索相关信息。
* 工作流程：...
* 输出要求：...
"""
main_tools = [
    search, # 通用网络搜索工具
]

# === 创建 DeepAgent===
agent = create_deep_agent(
    model=f"openai:{OPENAI_MODEL}",
    tools=main_tools,
    system_prompt=SYSTEM_PROMPT,debug=True
).with_config({"recursion_limit": RECURSION_LIMIT})
...

为了更好的观测Agent运行，通过LangGraph命令行来部署与启动：

> langgraph dev

然后在出现的LangSmith Studio界面上输入消息：

请帮我分析贵州茅台这只股票。

你会发现它的运行过程与普通的Agent几乎没有区别。这是正常的，因为在没有触发“深度能力”的情况下，DeepAgents 与普通 Agent 的执行路径相同。

现在我们来触发DeepAgent的第一个特性：任务规划。

【任务规划：Planning Tool】

单纯依赖LLM完成复杂任务的长期规划与执行很容易发生偏离。各大模型厂商推出的“深度 Agent”（如 OpenAI Deep Research、Claude Code）背后除了训练特殊的Agent推理模型外，都采用了类似的策略：

在执行前先列步骤、做计划，然后逐一跟踪执行；并在必要时做调整

DeepAgents 中的任务规划能力是通过一个内置工具 write_todos 来实现的。它会在以下条件下触发：

任务目标比较复杂，特别是涉及较多的步骤
用户明确提示要求LLM先规划执行

每完成一个步骤，需要修订任务清单 - 标记状态或调整任务

现在让我们换个方式输入任务要求：

再次通过LangSmith Studio观察执行过程：

你会发现，这一次的工作循环有所不同！第一次的工具调用是write_todos，它会将LLM推理出的“代办事项”写入到State中。

而后续每完成一个步骤，该工具会再次被调用 - 标记状态（或修订计划）：

注意：如果你的任务过于简单，默认不会触发规划机制，以避免增加不必要的token和时间开销。

【文件系统：File System】

想象下，当领导交给你复杂任务时，你是不是需要一个笔记本来记录重要事项或工作成果，必要时可以翻阅？

DeepAgents的另一个重要特性 - “文件系统”，就类似这样的笔记本：

给Agent配备一套虚拟文件系统与读写工具，可随时记录、查询与持久化任务过程中的信息。

比如作为一个客服Agent，可以把与客户每次交互的摘要存放在这个虚拟文件系统（如：/memories/{user_id}/下），在客户下次来访可以调取。

虚拟文件系统由可插拔、可扩展的后端（Backend）来实现，架构如下：

StateBackend：Agent的State作为存储，仅在本次线程有效。可用来在一次对话中卸载临时的中间结果，优化上下文空间。
FileSystemBackend：本地文件系统目录作为存储，可长期保存。比如保存AI生成的创作文档或代码文件。
StoreBackend：Store是LangGraph实现跨线程持久记忆的机制（可以是Redis、Postgres等实现）。你可以配置Store作为虚拟文件系统。
CompositeBackend：复合后端。比如默认使用StateBackend；但存储到"/memories/"的数据则使用StoreBackend以实现跨线程持久。

此外，你可以编写自己的Backend，比如把虚拟文件系统映射到阿里云OSS；也可以扩展上述Backend，比如给FileSystemBackend增加安全检查。

现在我们继续用前面的Agent来体验该特性。

State作为Backend（默认）

首先不做任何代码修改，只对任务稍作修改：

观察执行过程，你将会看到write_file工具的调用：

由于没做任何指定，Agent会使用默认的StateBackend：将“文件”直接保存在State的Files字段。很显然，它并不是真实的文件，仅限本次线程有效。

本地文件系统作为Backend

现在给Agent更换另一个Backend的实现：

相同的输入任务下，你将不会在State看到Files字段，而是生成了真实的文件：

LangGraph Store作为Backend

这是非常重要的一项能力。它可以让Deep Agents能够像访问文件系统一样，直接操作底层LangGraph的持久装置（Store），从而获得跨线程、跨会话、带向量检索能力的持续记忆能力。

关于LangGraph Store的应用，可参考LangGraph官方文档详细了解。

继续修改我们的Agent，并同时演示CompositeBackend的能力：

...
def create_backend(runtime):
    return CompositeBackend(
        default=FilesystemBackend(root_dir="./fs", virtual_mode=True), 
        routes={
            "/memories/": StoreBackend(runtime) 
        }
    )

# === 创建 DeepAgent（无后端，无子智能体）===
agent = create_deep_agent(
    model=f"openai:{OPENAI_MODEL}",
    tools=main_tools,
    backend=create_backend,
    system_prompt=SYSTEM_PROMPT,debug=True
).with_config({"recursion_limit": RECURSION_LIMIT})

这里创建了一个复合的Backend：默认使用本地文件系统做后端；但如果路由路径是/memories/，则使用LangGraph Store作为后端（默认类型InMemoryStore)。

接着在系统提示中增加一些指令：

SYSTEM_PROMPT = """你是一个股票分析助手。
...
- 把股票分析结果保存成/reports下面的Markdown文件
- 把用户分析过的股票名称保存到/memories/my_stocks.md中，方便下次调用
"""

现在启动一个运行线程，并输入任务：

观察执行过程，可以看到如下的工具调用信息：

根据以上的设置：股票分析结果会被保存到本地文件系统；但分析过的股票名称将会被路由到LangGraph的持久记忆Store。所以你会在本地看到分析结果,但无法看到这里的my_stocks.md“文件”。

为了验证my_stocks中的“记忆”，我们开启一个新的线程任务：

此时Agent会调用read_file工具来读取Store，并输出：

实际应用中，该功能可以用来实现诸如用户偏好记忆、知识积累、研究结果保存，以在不同会话中共享。

以上是DeepAgents内置的几种虚拟文件系统Backend实现。如果仍然无法满足你的需求，也可以自行实现BackendProtocol这个接口，将虚拟文件系统映射到你的OSS、数据库、向量库等。

【子智能体：Subagents】

现实中复杂项目通常由多人分工合作完成：每个角色各司其职。DeepAgents 引入的 Subagent（子代理）机制，正是让 AI Agent 也具备类似的能力：

主Agent可以根据需要派生子Agent来负责特定的子任务。

这本质上是一种多智能体系统的机制。其主要的好处是：

上下文隔离：一个复杂Agent任务需要处理大量中间步骤和信息，快速膨胀的上下文很容易干扰主线思路。而引入子Agent，主Agent可以将具体工作“外包”后接收最终结果，自身则专注主线任务。
专长分离：不同的子Agent可以拥有不同的专业知识、提示词与工具集，为每种任务定制一个子Agent，会比一个Agent囊括所有技能更高效。

使用Subagents有两种方法：

直接定义Subagent的职责、提示词、可用工具等
新建或使用已有的LangGraph工作流作为Subagent

我们继续对上面的例子做增强 - 用子Agent来协助完成任务：

设置三个不同的"股票分析"专家Agent：

...
# 1. 基本面分析师 - 使用股票详细信息和财务报表工具
fundamental_analyst = {
    "name": subagents_config["fundamental_analyst"]["name"],
    "description": subagents_config["fundamental_analyst"]["description"],
    "system_prompt": subagents_config["fundamental_analyst"]["prompt"],
    "tools": [
        get_stock_detailed_info, # 公司详细信息（主营、概况、筹码、分红）
        get_financial_statements, # 财务报表（资产负债表、利润表、现金流量表）
    ],
    "model": f"openai:{OPENAI_MODEL}",
}

# 2. 技术面分析师 - 使用技术指标和股票价格工具
technical_analyst = {
    "name": subagents_config["technical_analyst"]["name"],
    "description": subagents_config["technical_analyst"]["description"],
    "system_prompt": subagents_config["technical_analyst"]["prompt"],
    "tools": [
        get_technical_indicators, # 技术指标 
        get_stock_price, # 股票历史价格数据
    ],
    "model": f"openai:{OPENAI_MODEL}",
}

# 3. 消息面分析师 - 使用新闻和研报查询工具
news_analyst = {
    "name": subagents_config["news_analyst"]["name"],
    "description": subagents_config["news_analyst"]["description"],
    "system_prompt": subagents_config["news_analyst"]["prompt"],
    "tools": [
        get_stock_news, # 个股新闻
        get_stock_research_report, # 机构研究报告
    ],
    "model": f"openai:{OPENAI_MODEL}",
}
...

这里通过subagents_config集中配置三个Subagent的提示词与工具集，这里不再通过搜索获取信息，而是借助第三方金融数据接口（具体参考源码）。

2. 对主Agent的提示词做修改。

清晰的说明如何使用Subagent来协助完成任务<略>。

3. 在创建主Agent时指定subagents参数：

...
subagents = [fundamental_analyst, technical_analyst, news_analyst]

agent = create_deep_agent(
...
    subagents=subagents
...
)

现在让Agent运行相同的任务，你将可以观察到子Agent的参与：

很显然，Subagents的内部机制是：主Agent根据需要使用名为“task”的工具，将不同的子任务派发给对应的Subagent来完成。

需要注意的是，当任务非常简单或需要全程共享上下文时，引入子Agent可能增加不必要的开销。但在多步骤复杂任务、需要不同专业知识或想保持主任务聚焦的场景下，子Agent无疑是强有力的工具。

DeepAgents原理总结与未来展望

在前面的示例中，我们已经体验了 DeepAgents 在复杂任务中的核心能力。那么，这些能力背后究竟依托什么机制？如果你打开 LangSmith Studio 查看 DeepAgent 的工作流图，就会发现：

DeepAgents流程似乎与普通ReAct Agent并无本质区别：其本质只是在LangChain的Agent基础上挂载了多个中间件（Middleware）扩展。

Middleware是在LangChain1.0引入的Agent扩展机制，简单理解为：

插入到Agent主循环各个阶段的“钩子”，以调整与扩展Agent的行为逻辑。比如你可以在LLM调用前后拦截消息、替换LLM请求、总结工具结果等。

而DeepAgents就是通过中间件给普通Agent插入了更多新能力：

TodoListMiddleware：为Agent提供任务规划能力
FilesystemMiddleware：给Agent增加虚拟文件系统与相关工具
SubAgentMiddleware：支持子Agent，增加分工协作的运行模式

这种方式让 DeepAgents 的内部清晰解耦：每个中间件关注一个功能点，通过标准接口协作。这意味着你也可以定制 DeepAgents 的行为 - 比如更换规划策略（定制TodoListMiddleware）等，而不需要修改整个Agent逻辑。

【未来展望】

DeepAgents 正处于快速迭代阶段（目前版本0.2)。官方也透露了一些未来值得期待的方向。例如：

系统提示的全面可定制
更灵活的多Agent协作模式
更高级的记忆检索与遗忘机制
与知识库和RAG技术的更深度融合等等
更丰富的中间件生态

随着社区参与度提升和官方持续投入，DeepAgents 很有机会成长为下一代“复杂任务智能体”的标准化框架。

53AI，企业落地大模型首选服务商

产品：场景落地咨询+大模型应用平台+行业解决方案

承诺：免费POC验证，效果达标后再合作。零风险落地应用大模型，已交付160+中大型企业