开源模型

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

2025 年 11 月 17 日

LangChain全新深度智能体框架DeepAgents实战解析，助你用更少代码实现复杂任务处理。核心内容： 1. DeepAgents框架定位与三大核心能力解析 2. 实战演示：如何用DeepAgents处理复杂多步骤任务 3. 框架设计原理与未来发展方向

前段时间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 很有机会成长为下一代“复杂任务智能体”的标准化框架。

立即咨询 JOTO

JOTO 提供覆盖企业智能体规划与搭建、AI 平台私有化部署、RAG 知识工程、AI 安全治理、FDE 驻场共创及持续运营优化的全周期 AI 落地服务，帮助企业把验证中的 AI 能力转化为安全、可控、可持续迭代的生产力。联系 JOTO 获取 AI 落地咨询

想把这些做法用到你的业务里?

留下你的场景和痛点,我们帮你判断从哪一步开始。

联系我们

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

立即咨询 JOTO

想把这些做法用到你的业务里?

开启企业级 AI 落地

填写需求单