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

探索如何通过中间件模式构建可扩展的 AI 代理系统

引言

在 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):
        # 模型调用前的钩子
        pass
    
    def 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

@tool
def 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 请求
包含：提示词 + 工具描述 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 AgentMiddleware
from langchain_core.tools import tool

@tool
def 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 核心概念对比

概念	定位	职责
Agent	容器/编排器	管理状态、执行流程、调用模型
Middleware	功能插件	注入工具、增强提示词、扩展状态
Tools	能力实现	提供具体功能（搜索、计算、文件操作等）
MCP	协议标准	定义工具通信格式（JSON-RPC 2.0）
Function Calling	调用协议	模型调用工具的通信方式

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 协议规范