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

DeepAgents 是由 LangChain/LangGraph 团队开发的 AI 代理框架，专门用于构建能够处理多步骤复杂任务的智能代理系统。任务规划与分解：将复杂任务拆分为可执行的子任务上下文管理：通过文件系统管理大量上下文信息子代理委托：创建专门的子代理处理特定任务状态持久化：支持跨会话的状态管理@tool"""获取城市天气"""return f"{city} 的天气是晴天"# 注入工具#

程序员小橙

541人浏览 · 2026-01-28 11:02:53

程序员小橙 · 2026-01-28 11:02:53 发布

引言

在 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 可以调用的函数，分为两类：

内置工具：由中间件自动注入
自定义工具：由开发者提供

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 初始化阶段

关键点：

Agent 对象在调用 create_deep_agent() 时创建
中间件在初始化时注入工具和增强提示词
Agent 对象保存在内存中（可选的持久化）

3.2 运行时阶段

3.3 关键决策点

模型如何选择工具？

工具描述传递：框架将所有工具的描述（通过 MCP/Function Calling 格式）传递给模型
模型推理：模型根据用户请求和工具描述，决定调用哪个工具
工具执行：框架执行工具，返回结果给模型
继续对话：模型处理工具结果，决定下一步操作

任务拆分是如何实现的？

不是中间件拆分：中间件只提供 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	调用协议	模型调用工具的通信方式