DeepAgents框架详解：让AI Agent具备任务规划与长期记忆能力！

DeepAgents是LangChain推出的开源Agent框架，基于LangGraph构建，专为处理复杂多步骤任务设计。它提供内置任务规划、灵活文件系统、子Agent委托、长期记忆和人机协同等核心功能。采用三层架构设计，通过中间件机制实现高度可扩展性。适合需要自主长期运行的复杂Agent场景，支持自定义系统提示和中间件，让开发者能构建类似Claude Code的强大AI应用。

AI劳模

652人浏览 · 2026-01-04 14:11:47

AI劳模 · 2026-01-04 14:11:47 发布

引言

随着AI Agent任务复杂度每7个月翻倍，传统的"LLM循环调用工具"模式开始显露出成本高、可靠性差的问题。LangChain DeepAgents应运而生——一个开源的Agent框架，让开发者能够构建类似Claude Code的强大Agent。

什么是DeepAgents？

DeepAgents是LangChain推出的一个Agent框架（agent harness），它基于LangGraph构建，专为处理复杂、多步骤、长时程任务而设计。它的核心理念源自行业领先的Agent应用，但完全开源且高度可定制。

核心特点一览

特性	说明
任务规划	内置TODO工具，能自动分解复杂任务
文件系统	虚拟或真实的文件系统后端，管理大量上下文
子Agent委托	可生成专门的子Agent处理特定子任务
长期记忆	支持跨会话的持久化存储
人机协同	敏感操作可暂停等待人工批准
高度可扩展	通过中间件机制轻松添加自定义功能

架构设计：三层构建哲学

DeepAgents采用了清晰的分层架构，让开发者可以在不同抽象层次上进行定制：

┌─────────────────────────────────┐│      DeepAgents (Agent Harness) │  ← 内置规划、文件系统、子Agent│                                 │├─────────────────────────────────┤│      LangChain (Agent Framework)│  ← Agent核心循环、工具抽象│                                 │├─────────────────────────────────┤│    LangGraph (Agent Runtime)    │  ← 图执行引擎、状态管理└─────────────────────────────────┘

三者的关系：

LangGraph: 提供底层的图执行和状态管理能力
LangChain: 提供Agent的基础循环逻辑和工具集成
DeepAgents: 在前两者基础上，提供开箱即用的高级能力（规划、文件系统、子Agent等）

何时选择DeepAgents？

场景	推荐框架
需要工作流与Agent混合	LangGraph
从零构建所有prompt和工具	LangChain
需要自主、长期运行的复杂Agent	DeepAgents

核心能力深度剖析

1. 智能任务规划

DeepAgents内置了write_todos和read_todos工具。有趣的是，这个工具本质上是个"no-op"（不执行实际操作），但它却能显著提升Agent的任务分解能力。

工作原理：

Agent在执行前先创建TODO列表
将复杂任务分解为离散步骤
跟踪进度并动态调整计划
在完成后标记任务

这种"自我规划"机制让Agent能够处理跨越数十次工具调用的长期任务。

2. 灵活的文件系统后端

DeepAgents支持多种文件系统后端，解决了上下文窗口溢出的难题：

后端类型	特点	适用场景
StateBackend	临时存储在Agent状态中	默认，适合短期任务
FilesystemBackend	真实的磁盘操作	需要持久化或访问本地文件
StoreBackend	基于LangGraph Store持久化	跨会话的长期记忆
CompositeBackend	混合路由不同后端	同时需要临时和持久存储

实战案例：

from deepagents import create_deep_agentfrom deepagents.backends import CompositeBackend, StateBackend, StoreBackend# 混合后端：工作文件临时，记忆持久化agent = create_deep_agent(    backend=CompositeBackend(        default=StateBackend(),  # 默认临时存储        routes={"/memories/": StoreBackend()}  # /memories/下持久化    ))

3. 子Agent委托机制

通过内置的task工具，主Agent可以生成专门的子Agent来处理特定子任务，实现上下文隔离和并行执行。

生命周期：

主Agent → 生成子Agent → 子Agent独立执行 → 返回结果 → 主Agent整合

自定义子Agent示例：

research_subagent = {    "name": "research-agent",    "description": "用于深度研究问题",    "system_prompt": "你是一个专业研究员...",    "tools": [internet_search],    "model": "openai:gpt-4o"  # 可选，默认使用主Agent模型}agent = create_deep_agent(subagents=[research_subagent])

4. 长期记忆能力

通过CompositeBackend和StoreBackend的组合，Agent可以跨会话保持记忆：

# 用户偏好持久化示例agent = create_deep_agent(    backend=CompositeBackend(        default=StateBackend(),        routes={            "/memories/": StoreBackend(store=InMemoryStore()),            "/preferences/": StoreBackend(),            "/knowledge/": StoreBackend()        }    ))

应用场景：

跨会话保存用户偏好
构建知识库
基于反馈自我改进
保持研究进展

内置工具矩阵

DeepAgents开箱即带12+个专业工具，全部由中间件自动注入：

工具名称	功能	提供者
`write_todos` / `read_todos`	任务规划与跟踪	TodoListMiddleware
`ls` / `read_file` / `write_file`	文件操作	FilesystemMiddleware
`edit_file`	精确字符串替换编辑	FilesystemMiddleware
`glob` / `grep`	文件搜索与内容查找	FilesystemMiddleware
`execute` *	执行Shell命令（需沙箱支持）	FilesystemMiddleware
`task`	委托给子Agent	SubAgentMiddleware

自动功能：

大结果（>20K tokens）自动保存到文件
上下文超170K自动摘要（保留最后6条消息）
Anthropic模型自动启用Prompt缓存

快速上手：5分钟构建研究Agent

# 1. 安装pip install deepagents tavily-python# 2. 定义工具import osfrom deepagents import create_deep_agentfrom tavily import TavilyClienttavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])def internet_search(query: str, max_results: int = 5):    """运行网络搜索"""    return tavily_client.search(query, max_results=max_results)# 3. 创建Agentagent = create_deep_agent(    tools=[internet_search],    system_prompt="进行深度研究并撰写专业报告。",)# 4. 执行任务result = agent.invoke({    "messages": [{"role": "user", "content": "LangGraph是什么？"}]})

就这么简单！Agent会自动：

规划研究步骤（使用TODO工具）
搜索多个来源
将大量结果保存到文件
必要时生成子Agent进行深度分析
最终整合成报告

高级定制技巧

自定义系统Prompt

DeepAgents的系统Prompt采用分层设计：

┌──────────────────────────────────┐│  中间件自动注入的默认指令         │  ← 工具使用说明、最佳实践├──────────────────────────────────┤│  你的自定义system_prompt          │  ← 领域特定工作流、示例└──────────────────────────────────┘

编写自定义Prompt的原则：

应该做：

定义特定领域的工作流（如研究方法论）
提供具体用例的示例
添加专业指导（如"将相似研究任务批处理到单个TODO"）
定义停止标准和资源限制
解释工具如何在你的工作流中协同

不应该做：

重复解释标准工具功能（已由中间件覆盖）
复制中间件已有的工具使用指令
与默认指令相矛盾

人机协同工作流

对于敏感操作（如文件删除、API调用），可配置人工审批：

@tooldef delete_file(path: str) -> str:    """删除文件"""    os.remove(path)    return f"已删除 {path}"agent = create_deep_agent(    tools=[delete_file],    interrupt_on={        "delete_file": {            "allowed_decisions": ["approve", "edit", "reject"]        }    })

Agent会在执行敏感工具前暂停，等待用户的approve/edit/reject决策。

自定义中间件

通过中间件扩展Agent能力：

from langchain_core.tools import toolfrom deepagents import create_deep_agentfrom langchain.agents.middleware import AgentMiddleware@tooldef get_weather(city: str) -> str:    """获取城市天气"""    returnf"{city}的天气晴朗。"class WeatherMiddleware(AgentMiddleware):    tools = [get_weather]        def before_call(self, state):        # 在每次LLM调用前执行        print("准备查询天气...")        return stateagent = create_deep_agent(middleware=[WeatherMiddleware()])

实战应用场景

1. 深度研究Agent

research_agent = create_deep_agent(    tools=[internet_search, web_fetch],    system_prompt="""    你是专业研究员。    1. 使用write_todos规划多步研究    2. 并行搜索多个来源    3. 将原始数据保存到/research/目录    4. 生成research-agent子Agent进行深度分析    5. 整合成结构化报告    """,    subagents=[deep_research_subagent])

2. 代码助手Agent

coding_agent = create_deep_agent(    backend=FilesystemBackend(root_dir="/workspace"),    tools=[run_tests, format_code],    system_prompt="""    你是高级编程助手。    - 使用ls和read_file理解项目结构    - 用edit_file进行精确代码修改    - 执行测试验证更改    - 在/workspace操作真实文件    """)

3. 数据分析Agent

analysis_agent = create_deep_agent(    tools=[query_database, plot_chart],    system_prompt="""    你是数据科学家。    1. 规划分析步骤（EDA → 建模 → 可视化）    2. 将中间结果保存到/data/目录    3. 生成可复现的分析报告    """)

与其他框架的对比

特性	DeepAgents	LangChain Agent	AutoGPT	CrewAI
任务规划	内置TODO	需自建	自动	内置
文件系统	多后端	无	真实文件	无
子Agent	灵活委托	无	无	角色协作
长期记忆	可配置	需自建	向量存储	有限
人机协同	内置	需自建	无	无
可扩展性	中间件	工具	有限	中等
学习曲线	中等	低	高	中等

技术亮点与设计哲学

1. 中间件驱动架构

DeepAgents的所有核心功能都通过中间件实现，这种设计带来了：

模块化: 每个功能独立，易于理解和维护
可组合性: 自由组合不同中间件
可扩展性: 第三方可轻松开发新中间件

2. "信任LLM"安全模型

与传统的"不信任LLM"方法不同，DeepAgents采用：

边界在工具层：安全检查在工具和沙箱层面实施
不期望LLM自我审查：LLM可执行任何工具允许的操作
适合受控环境：适用于企业内部、个人项目等可信场景

3. 上下文管理策略

通过三层机制解决上下文窗口限制：

文件系统卸载: 大结果自动保存到文件（>20K tokens）
自动摘要: 上下文超170K时压缩历史（保留最近6条）
子Agent隔离: 通过子Agent实现上下文分片

性能与成本优化

DeepAgents内置多项优化措施：

优化项	机制	效果
Prompt缓存	AnthropicPromptCachingMiddleware	Claude模型成本降低90%
自动摘要	SummarizationMiddleware	防止上下文溢出
并行执行	子Agent并发	研究类任务提速3-5倍
上下文卸载	自动保存大结果到文件	节省token消耗