当前位置：首页 > news >正文

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

news 2026/7/3 0:28:15

引言

在 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	调用协议	模型调用工具的通信方式