DeepAgents 源码中create_deep_agent 封装与增强机制

本文基于 deepagents/graph.py 源码，系统分析 DeepAgents 框架的设计思想，以及 create_deep_agent 相较于 LangChain 基础 create_agent 的架构升级与能力增强。

一、框架概述

DeepAgents 是一款独立的高阶智能体构建库，专注于处理复杂、多步骤、长周期的任务型智能体开发。

框架基于 LangGraph 构建，设计灵感借鉴 Claude Code、Deep Research、Manus 等前沿智能体应用，核心能力包括：

• 任务规划与自动拆解
• 基于文件系统的上下文持久化管理
• 支持派生子智能体实现上下文隔离
• 跨对话、跨线程的记忆持久化

适用场景

• 需要规划 + 分步执行的复杂任务
• 需要通过文件系统管理大量上下文
• 需要将任务委托给专业子智能体
• 需要在多轮对话间持久化记忆

简单场景可直接使用 LangChain create_agent 或自定义 LangGraph 工作流。

快速使用示例

from deepagents.graph import create_deep_agentagent = create_deep_agent(    tools=[your_search_tool],    system_prompt=your_research_instructions)

二、核心结论

create_deep_agent 本质是对 LangChain create_agent 的生产级超级封装。 它通过多层标准化中间件栈、自动化配置注入、主从式子智能体编排，将单层智能体升级为可处理复杂任务、支持上下文管理、可动态扩展的深度智能体系统。

三、函数签名与参数增强对比

3.1 基础 create_agent（LangChain 原生）

create_agent(    model,    system_prompt,    tools,    middleware,    response_format,    context_schema,    checkpointer,    store,    debug,    name,    cache)

3.2 create_deep_agent

defcreate_deep_agent(    model: str | BaseChatModel | None = None,    tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,    *,    system_prompt: str | SystemMessage | None = None,    middleware: Sequence[AgentMiddleware] = (),    subagents: list[SubAgent | CompiledSubAgent] | None = None,    skills: list[str] | None = None,    memory: list[str] | None = None,    response_format: ResponseFormat | None = None,    context_schema: type[Any] | None = None,    checkpointer: Checkpointer | None = None,    store: BaseStore | None = None,    backend: BackendProtocol | BackendFactory | None = None,    interrupt_on: dict[str, bool | InterruptOnConfig] | None = None,    debug: bool = False,    name: str | None = None,    cache: BaseCache | None = None,) -> CompiledStateGraph:

3.3 关键参数增强一览

create_deep_agent(    model,                    # 增强：支持 "provider:model" 字符串格式    tools,                    # 增强：自动注入至通用子智能体    system_prompt,            # 增强：与内置 BASE_AGENT_PROMPT 智能拼接    middleware,               # 增强：追加至标准中间件栈后    subagents,                # 新增：子智能体集群管理    skills,                   # 新增：技能文件加载    memory,                   # 新增：持久记忆加载    backend,                  # 新增：统一存储与执行引擎    interrupt_on,             # 新增：人工介入断点控制    ...)

四、核心封装逻辑详解

4.1 Backend 存储层初始化

backend = backend if backend isnotNoneelse StateBackend

• 支持自定义后端（文件系统、数据库、对象存储等）
• 未传入时默认使用 StateBackend
• 为文件系统、技能、记忆、子智能体提供统一存储底座

4.2 子智能体（SubAgent）构建机制

DeepAgents 采用主从架构，自动构建「通用子智能体 + 用户自定义子智能体」双层体系。

4.2.1 通用子智能体（General-Purpose Subagent）

gp_middleware: list[AgentMiddleware] = [    TodoListMiddleware(),                              # 待办事项管理    FilesystemMiddleware(backend=backend),             # 文件系统操作    _DeepAgentsSummarizationMiddleware(...),           # 上下文摘要压缩    AnthropicPromptCachingMiddleware(...),             # 提示词缓存优化    PatchToolCallsMiddleware(),                        # 工具调用兼容修复]# 可选技能注入if skills isnotNone:    gp_middleware.append(SkillsMiddleware(backend=backend, sources=skills))# 可选人工介入if interrupt_on isnotNone:    gp_middleware.append(HumanInTheLoopMiddleware(interrupt_on=interrupt_on))

• 工具、模型、backend 继承全局配置
• 开箱即用，无需用户配置基础能力

4.2.2 用户自定义子智能体处理

for spec in subagents or []:# 模型自动补全    subagent_model = spec.get("model", model)# 构建独立中间件栈    subagent_middleware = [        TodoListMiddleware(),        FilesystemMiddleware(backend=backend),        create_summarization_middleware(...),        AnthropicPromptCachingMiddleware(...),        PatchToolCallsMiddleware(),    ]# 子智能体专属技能if subagent_skills:        subagent_middleware.append(SkillsMiddleware(...))# 追加用户自定义中间件    subagent_middleware.extend(spec.get("middleware", []))

规则：

• 工具优先级：子智能体自有工具 > 全局工具
• 技能仅作用于当前子智能体，实现隔离
• 用户只需配置差异化部分，框架自动补全默认行为

通用目的子智能体和用户定义子智能体的示意图如下：

4.2.3 子智能体合并

all_subagents: list[SubAgent | CompiledSubAgent] = [general_purpose_spec, *processed_subagents]

4.3 主智能体中间件栈构建

主智能体通过有序中间件链实现完整调度能力：

deepagent_middleware: list[AgentMiddleware] = [    TodoListMiddleware(),  # 基础任务管理]# 可选持久化记忆if memory isnotNone:    deepagent_middleware.append(MemoryMiddleware(backend=backend, sources=memory))# 可选技能系统if skills isnotNone:    deepagent_middleware.append(SkillsMiddleware(backend=backend, sources=skills))# 核心调度链路deepagent_middleware.extend([    FilesystemMiddleware(backend=backend),              # 文件系统上下文    SubAgentMiddleware(                                 # 子智能体协调器        backend=backend,        subagents=all_subagents,    ),    create_summarization_middleware(...),            # 长上下文压缩    AnthropicPromptCachingMiddleware(...),              # 提示缓存优化    PatchToolCallsMiddleware(),                         # 工具调用修复])# 用户自定义中间件if middleware:    deepagent_middleware.extend(middleware)# 人工介入断点if interrupt_on isnotNone:    deepagent_middleware.append(HumanInTheLoopMiddleware(interrupt_on=interrupt_on))

中间件按从上到下顺序执行，构成完整任务调度闭环。

其执行顺序及说明如下图

4.4 系统提示词增强拼接

if system_prompt isNone:    final_system_prompt = BASE_AGENT_PROMPTelifisinstance(system_prompt, SystemMessage):    final_system_prompt = SystemMessage(...)else:    final_system_prompt = system_prompt + "\n\n" + BASE_AGENT_PROMPT

• 用户指令在前，框架内置调度规则在后
• 兼容字符串与 SystemMessage 两种格式
• 不破坏原有逻辑，自动增强智能体规划能力

4.5 最终调用 create_agent

return create_agent(    model,    system_prompt=final_system_prompt,    tools=tools,    middleware=deepagent_middleware,    response_format=response_format,    context_schema=context_schema,    checkpointer=checkpointer,    store=store,    debug=debug,    name=name,    cache=cache,).with_config({"recursion_limit": 1000})

• 透传所有基础参数
• 注入完整增强中间件栈
• 强制设置递归深度 1000，支持超长流程任务

• 返回可直接运行的 CompiledStateGraph

五、基础 Agent vs DeepAgents 对比表

六、总结

create_deep_agent 不是简单的语法糖，而是基于 LangGraph 构建的一套完整多智能体协作框架。

它通过：

• 自动化参数增强与兼容
• 标准化中间件栈编排
• 主从式子智能体调度
• 文件系统级上下文管理
• 企业级能力开箱即用

将基础智能体升级为可规划、可扩展、可持久、可监控、可人工介入的深度任务执行系统，是 LangChain 生态中面向复杂任务的生产级首选方案。