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): # 模型调用前的钩子 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 初始化阶段

关键点：

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

3.2 运行时阶段

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

5.2 关键设计模式

1. 中间件模式：通过组合中间件，灵活扩展 Agent 能力
2. 状态机模式：Agent 基于 LangGraph 状态机，管理复杂工作流
3. 策略模式：模型根据上下文动态选择工具
4. 模板方法模式：中间件通过钩子方法参与执行流程

5.3 优势与适用场景

优势：

• 可扩展性：通过中间件轻松扩展功能
• 模块化：工具、状态、提示词分离管理
• 灵活性：每个 Agent 可独立配置
• 标准化：基于 MCP 协议，工具可复用

适用场景：

• 复杂多步骤任务（研究、报告生成）
• 需要上下文管理的场景
• 需要任务分解和规划的场景
• 需要子代理委托的场景

六、总结

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

1. Agent 作为容器：管理状态和执行流程
2. Middleware 作为插件：提供工具和增强能力
3. 模型作为决策者：根据上下文选择工具和执行策略

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

学习资源推荐

如果你想更深入地学习大模型，以下是一些非常有价值的学习资源，这些资源将帮助你从不同角度学习大模型，提升你的实践能力。

一、全套AGI大模型学习路线

AI大模型时代的学习之旅：从基础到前沿，掌握人工智能的核心技能！​

因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获取

二、640套AI大模型报告合集

这套包含640份报告的合集，涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师，还是对AI大模型感兴趣的爱好者，这套报告合集都将为您提供宝贵的信息和启示

​因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获取

三、AI大模型经典PDF籍

随着人工智能技术的飞速发展，AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型，如GPT-3、BERT、XLNet等，以其强大的语言理解和生成能力，正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。

因篇幅有限，仅展示部分资料，需要点击文章最下方名片即可前往获取

四、AI大模型商业化落地方案

作为普通人，入局大模型时代需要持续学习和实践，不断提高自己的技能和认知水平，同时也需要有责任感和伦理意识，为人工智能的健康发展贡献力量。