DeepAgents 框架深度解析：从理论到实践的智能代理架构

引言

在 AI 代理系统快速发展的今天，如何构建一个既能处理复杂任务，又具备良好扩展性的框架？DeepAgents 给出了一个优雅的答案。本文将深入解析 DeepAgents 框架的核心理论、架构设计和执行流程，帮助开发者理解这一强大的 AI 代理框架。

一、核心理论：什么是 DeepAgents？

1.1 框架定位

DeepAgents 是由 LangChain/LangGraph 团队开发的 AI 代理框架，专门用于构建能够处理多步骤复杂任务的智能代理系统。与简单的"一问一答"模式不同，DeepAgents 支持：

• 任务规划与分解：将复杂任务拆分为可执行的子任务

• 上下文管理：通过文件系统管理大量上下文信息

• 子代理委托：创建专门的子代理处理特定任务

• 状态持久化：支持跨会话的状态管理

1.2 设计理念

DeepAgents 的核心设计理念是中间件模式：

Agent（容器） + Middleware（功能模块） = 强大的代理系统

• Agent：作为核心容器，管理状态和执行流程

• Middleware：作为功能插件，提供工具、增强能力

• 组合式设计：通过组合不同的中间件，构建不同能力的 Agent

二、架构设计：三层抽象模型

2.1 整体架构

DeepAgents 采用三层抽象架构：

┌─────────────────────────────────────┐
│        用户层（应用层）              │
└─────────────────────────────────────┘           ↓
┌─────────────────────────────────────┐
│    DeepAgents 框架层                 │
│  ┌──────────────────────────────┐   │
│  │  Agent 实例（状态机）         │   │
│  │  - 状态管理                   │   │
│  │  - 执行流程                   │   │
│  │  - 工具调用                   │   │
│  └──────────────────────────────┘   │
│           ↑                          │
│  ┌──────────────────────────────┐   │
│  │  中间件层（Middleware）      │   │
│  │  - 注入工具                  │   │
│  │  - 增强提示词                │   │
│  │  - 扩展状态                  │   │
│  └──────────────────────────────┘   │
└─────────────────────────────────────┘
           ↓
┌─────────────────────────────────────┐
│        工具层 + 模型层               │
│  - 内置工具 / 自定义工具             │
│  - LLM 模型（Claude/GPT）           │
└─────────────────────────────────────┘

2.2 核心组件详解

Agent：状态机容器

Agent 是 DeepAgents 的核心，本质上是一个编译后的 LangGraph 状态机：

# Agent 内部结构（概念模型）class Agent:
    state = {"messages": [],    # 对话历史"todos": [],       # 任务列表"files": {},       # 文件系统状态}
    
    nodes = {"call_model": ...,      # 调用模型节点"execute_tool": ...,    # 执行工具节点"route": ...,          # 路由决策节点}

特点：

• 每个 Agent 实例独立，有自己的状态和配置

• 支持状态持久化（通过 Checkpointer）

• 基于 LangGraph 实现，支持复杂的工作流

Middleware：功能增强模块

中间件是 DeepAgents 的扩展机制，通过继承 AgentMiddleware 实现：

class AgentMiddleware:
    tools = []              # 注入的工具state_schema = {}       # 扩展的状态system_prompt = ""      # 增强的提示词def before_model(self, state, runtime):# 模型调用前的钩子passdef wrap_tool_call(self, request, handler):# 包装工具调用pass

内置中间件：

• TodoListMiddleware：提供任务规划能力（write_todos、read_todos）

• FilesystemMiddleware：提供文件系统能力（read_file、write_file 等）

• SubAgentMiddleware：提供子代理创建能力（task 工具）

Tools：能力实现

工具是 Agent 可以调用的函数，分为两类：

1. 内置工具：由中间件自动注入

2. 自定义工具：由开发者提供

from langchain_core.tools import tool@tooldef web_search(query: str) -> str:"""搜索网络信息"""# 实现搜索逻辑return results

2.3 系统提示词的组装机制

DeepAgents 的系统提示词采用分层组装机制：

最终提示词 = 基础提示词 + 用户自定义 + 中间件提示词

示例：

agent = create_deep_agent(
    system_prompt="你是一个研究助手",  # 用户自定义middleware=[TodoListMiddleware()]  # 中间件会添加任务规划说明)# 最终发送给模型的提示词：# 1. 框架基础提示词（所有 agent 共享）# 2. "你是一个研究助手"（agent 独有）# 3. TodoListMiddleware 添加的任务规划说明（agent 独有）

三、执行流程：从请求到响应

3.1 初始化阶段

sequenceDiagram
    participant Dev as 开发者
    participant Framework as DeepAgents 框架
    participant MW as 中间件
    participant Agent as Agent 实例
    
    Dev->>Framework: create_deep_agent()
    Framework->>MW: 加载中间件栈
    MW->>MW: 注入工具、状态、提示词
    MW->>Agent: 组装 Agent 配置
    Framework->>Agent: 创建 Agent 对象（状态机）
    Note over Agent: Agent 对象保存在内存中

关键点：

• Agent 对象在调用 create_deep_agent() 时创建

• 中间件在初始化时注入工具和增强提示词

• Agent 对象保存在内存中（可选的持久化）

3.2 运行时阶段

sequenceDiagram
    participant User as 用户
    participant Agent as Agent
    participant MW as 中间件
    participant LLM as LLM 模型
    participant Tools as 工具
    
    User->>Agent: 发送请求
    Agent->>MW: before_model 钩子
    MW->>Agent: 预处理完成
    
    Agent->>LLM: HTTP 请求<br/>包含：提示词 + 工具描述
    
    LLM->>LLM: 推理决策
    
    alt 需要调用工具
        LLM->>Agent: 返回工具调用（Function Calling）
        Agent->>MW: wrap_tool_call 钩子
        Agent->>Tools: 执行工具
        Tools->>Agent: 返回结果
        Agent->>LLM: 继续对话（包含工具结果）
        Note over LLM: 模型处理结果，决定下一步
    else 生成最终响应
        LLM->>Agent: 返回最终响应
    end
    
    Agent->>MW: after_model 钩子
    Agent->>User: 返回结果

3.3 关键决策点

模型如何选择工具？

1. 工具描述传递：框架将所有工具的描述（通过 MCP/Function Calling 格式）传递给模型

2. 模型推理：模型根据用户请求和工具描述，决定调用哪个工具

3. 工具执行：框架执行工具，返回结果给模型

4. 继续对话：模型处理工具结果，决定下一步操作

任务拆分是如何实现的？

• 不是中间件拆分：中间件只提供 write_todos 工具

• 是模型拆分：模型理解复杂任务后，主动调用 write_todos 来规划任务

• 框架支持：框架提供工具和提示词，模型负责决策

四、扩展机制：自定义中间件

4.1 创建自定义中间件

from langchain.agents.middleware import AgentMiddlewarefrom langchain_core.tools import tool@tooldef get_weather(city: str) -> str:"""获取城市天气"""return f"{city} 的天气是晴天"class WeatherMiddleware(AgentMiddleware):# 注入工具tools = [get_weather]    # 增强提示词system_prompt = """
    你可以使用 get_weather 工具查询天气。
    使用场景：当用户询问天气时。
    """# 生命周期钩子def before_model(self, state, runtime):# 模型调用前的处理return None

4.2 组合使用

agent = create_deep_agent(
    middleware=[
        TodoListMiddleware(),      # 任务规划FilesystemMiddleware(),    # 文件系统WeatherMiddleware(),       # 自定义天气工具]
)

五、技术要点总结

5.1 核心概念对比

5.2 关键设计模式

1. 中间件模式：通过组合中间件，灵活扩展 Agent 能力

2. 状态机模式：Agent 基于 LangGraph 状态机，管理复杂工作流

3. 策略模式：模型根据上下文动态选择工具

4. 模板方法模式：中间件通过钩子方法参与执行流程

5.3 优势与适用场景

优势：

• 可扩展性：通过中间件轻松扩展功能

• 模块化：工具、状态、提示词分离管理

• 灵活性：每个 Agent 可独立配置

• 标准化：基于 MCP 协议，工具可复用

适用场景：

• 复杂多步骤任务（研究、报告生成）

• 需要上下文管理的场景

• 需要任务分解和规划的场景

• 需要子代理委托的场景

六、总结

DeepAgents 框架通过中间件模式和状态机架构，构建了一个强大而灵活的 AI 代理系统。核心思想是：

1. Agent 作为容器：管理状态和执行流程

2. Middleware 作为插件：提供工具和增强能力

3. 模型作为决策者：根据上下文选择工具和执行策略

这种设计使得 DeepAgents 既能处理复杂的多步骤任务，又保持了良好的扩展性和可维护性。对于需要构建复杂 AI 代理系统的开发者来说，DeepAgents 提供了一个优秀的架构参考。

参考资料

• DeepAgents GitHub

• DeepAgents 官方文档

• LangGraph 文档

• MCP 协议规范