DeepAgents 概述

什么是 DeepAgents？

DeepAgents 是一个独立的 Python 库，专门用于构建能够处理复杂、多步骤任务的智能体（Agent）。它基于 LangGraph 构建，受 Claude Code、Deep Research 和 Manus 等应用的启发，提供了规划能力、文件系统用于上下文管理，以及生成子智能体的能力。

核心定位

DeepAgents 专注于解决传统智能体框架在处理复杂任务时的局限性，提供了以下核心能力：

• 规划与任务分解：内置的 write_todos 工具使智能体能够将复杂任务拆解为离散步骤，跟踪进度，并根据新信息调整计划
• 上下文管理：文件系统工具（ls、read_file、write_file、edit_file）允许智能体将大量上下文信息存储到内存中，防止上下文窗口溢出
• 子智能体生成：内置的 task 工具使智能体能够生成专门的子智能体，实现上下文隔离和任务委派
• 长期记忆：通过 LangGraph 的 Store，智能体可以在会话和线程之间持久保存和检索信息

主要作用

DeepAgents 的主要作用是：

1. 简化复杂任务处理：自动将复杂任务分解为可管理的步骤
2. 防止上下文溢出：通过文件系统工具管理大量上下文信息
3. 实现任务委派：通过子智能体实现上下文隔离和专业化处理
4. 增强长期记忆：在多个会话和线程之间保持记忆

应用场景

DeepAgents 特别适用于以下场景：

1. 深度研究与报告撰写

• 场景描述：用户提出复杂的研究课题，需要制定研究计划、分步收集信息、最终生成结构清晰的分析报告
• 典型应用：
  • 学术研究助手
  • 市场分析报告生成
  • 技术调研报告

2. 自动化代码生成与调试

• 场景描述：根据需求文档自动编写代码，遇到问题时调用搜索工具查找解决方案，或使用文件系统工具进行调试和修改
• 典型应用：
  • 代码生成工具
  • 自动化测试编写
  • 代码重构助手

3. 复杂任务规划与执行

• 场景描述：面对需要多个步骤才能完成的宏大任务，将大任务分解为多个子任务，并逐一执行或委托给专门的子智能体处理
• 典型应用：
  • 项目管理助手
  • 工作流自动化
  • 多步骤业务流程处理

4. 大量文档处理与分析

• 场景描述：需要处理大量文档，提取信息，进行综合分析
• 典型应用：
  • 法律文档分析
  • 合同审查
  • 技术文档整理

5. 多轮对话与上下文管理

• 场景描述：需要维护长期对话历史，在不同会话间保持记忆
• 典型应用：
  • 智能客服系统
  • 个人助手
  • 学习伙伴

不适用场景：

对于更简单的用例，建议使用 LangChain 的 create_agent 或构建自定义的 LangGraph 工作流，例如：

• 简单的问答系统
• 单一工具调用任务
• 不需要规划的单步骤任务

---

为什么需要 DeepAgents

LangChain 和 LangGraph 的局限性

虽然 LangChain 和 LangGraph 提供了构建智能体的基础设施，但在处理复杂、多步骤任务时存在以下局限性：

LangChain 的局限性

1. 缺乏内置规划能力：需要手动实现任务分解和进度跟踪
2. 上下文管理困难：大量上下文容易导致窗口溢出
3. 子智能体支持有限：需要手动实现子智能体的生成和管理
4. 长期记忆支持基础：跨会话记忆需要额外配置

LangGraph 的局限性

1. 需要手动构建工作流：复杂任务需要手动设计状态图和节点
2. 规划逻辑需要自行实现：没有内置的任务分解工具
3. 文件系统集成需要额外开发：上下文管理需要自己实现
4. 子智能体管理复杂：需要手动管理子智能体的生命周期

DeepAgents 的优势

DeepAgents 在 LangChain 和 LangGraph 的基础上，提供了以下关键优势：

1. 内置规划与任务分解

优势：

• 提供 write_todos 工具，自动将复杂任务拆解为可管理的步骤
• 智能体可以根据新信息动态调整计划
• 自动跟踪任务进度和完成状态

解决的问题：

• 复杂任务的自动规划
• 任务进度的可视化跟踪
• 动态调整计划的能力

2. 高级上下文管理

优势：

• 内置文件系统工具（ls、read_file、write_file、edit_file）
• 自动将大量上下文存储到文件中
• 防止上下文窗口溢出
• 支持处理可变长度的工具结果

解决的问题：

• 上下文窗口溢出问题
• 大量信息的有效管理
• 工具结果的持久化存储

3. 子智能体生成与管理

优势：

• 内置 task 工具，一键生成子智能体
• 自动实现上下文隔离
• 保持主智能体的上下文清晰
• 支持任务专业化委派

解决的问题：

• 上下文污染问题
• 任务专业化处理
• 复杂任务的并行处理

4. 长期记忆支持

优势：

• 集成 LangGraph 的 Store
• 在会话和线程之间持久存储记忆
• 自动保存和检索历史信息

解决的问题：

• 跨会话记忆丢失
• 历史信息的有效利用
• 个性化体验的维护

DeepAgents 解决的核心问题

问题 1：复杂任务的规划与执行

传统方式：

# 需要手动规划任务步骤
steps = [
    "步骤1：收集信息",
    "步骤2：分析数据",
    "步骤3：生成报告"
]
# 手动跟踪进度
for step in steps:
    execute(step)
    update_progress(step)

DeepAgents 方式：

# 智能体自动规划并执行
response = agent.invoke({
    "messages": [{"role": "user", "content": "研究量子计算并撰写报告"}]
})
# 智能体自动使用 write_todos 工具规划任务
# 自动跟踪进度并调整计划

问题 2：上下文窗口溢出

传统方式：

# 大量上下文导致溢出
context = load_all_documents()  # 可能超过上下文限制
response = llm.invoke(context + user_query)  # 错误！

DeepAgents 方式：

# 自动将上下文存储到文件
agent.write_file("research_context.txt", large_context)
# 需要时读取
context = agent.read_file("research_context.txt")
# 不会溢出

问题 3：任务委派与上下文隔离

传统方式：

# 所有任务在同一上下文中执行，容易污染
main_agent.process_task1()  # 上下文被污染
main_agent.process_task2()  # 受到 task1 的影响

DeepAgents 方式：

# 自动创建子智能体，上下文隔离
agent.task("处理子任务1")  # 独立的子智能体
agent.task("处理子任务2")  # 独立的子智能体
# 主智能体上下文保持清晰

---

DeepAgents 核心组件

DeepAgents 采用模块化的中间件架构，主要由以下核心组件组成：

1. 规划工具（To-do List Middleware）

功能描述

规划工具提供 write_todos 工具，使智能体能够：

• 将复杂任务拆解为离散步骤
• 跟踪每个步骤的进度
• 根据新信息动态调整计划
• 标记任务的完成状态

核心工具

write_todos：

• 功能：创建、更新和管理任务列表
• 输入：任务描述、步骤列表、优先级
• 输出：任务列表状态
• 特点：支持动态调整、进度跟踪

使用示例

# 智能体自动使用 write_todos 工具
# 用户请求：研究量子计算并撰写报告
# 智能体内部执行：
agent.write_todos([
    {"task": "收集量子计算最新研究", "status": "pending"},
    {"task": "分析关键技术突破", "status": "pending"},
    {"task": "撰写研究报告", "status": "pending"}
])

2. 文件系统工具（Filesystem Middleware）

功能描述

文件系统工具提供完整的文件操作能力，使智能体能够：

• 管理大量上下文信息
• 防止上下文窗口溢出
• 持久化存储中间结果
• 处理可变长度的工具结果

核心工具

ls：

• 功能：列出目录内容
• 输入：目录路径
• 输出：文件列表

read_file：

• 功能：读取文件内容
• 输入：文件路径
• 输出：文件内容

write_file：

• 功能：写入文件内容
• 输入：文件路径、内容
• 输出：写入状态

edit_file：

• 功能：编辑文件内容
• 输入：文件路径、编辑指令
• 输出：编辑后的内容

使用示例

# 智能体自动使用文件系统工具
# 存储大量研究数据
agent.write_file("research_data.txt", large_research_content)

# 读取存储的数据
content = agent.read_file("research_data.txt")

# 编辑文件
agent.edit_file("report.md", "在第3段添加新的分析结果")

3. 子智能体工具（SubAgent Middleware）

功能描述

子智能体工具提供 task 工具，使智能体能够：

• 生成专门的子智能体
• 实现上下文隔离
• 委派特定任务
• 保持主智能体上下文清晰

核心工具

task：

• 功能：创建并执行子智能体任务
• 输入：任务描述、子智能体配置
• 输出：任务执行结果
• 特点：自动上下文隔离、独立执行

使用示例

# 智能体自动创建子智能体处理特定任务
# 主智能体执行：
result = agent.task(
    description="深入研究量子纠缠理论",
    tools=[quantum_search_tool],
    system_prompt="你是量子物理专家"
)
# 子智能体在独立上下文中执行，不影响主智能体

4. 长期记忆（Long-term Memory）

功能描述

长期记忆通过集成 LangGraph 的 Store，使智能体能够：

• 在会话之间持久存储记忆
• 在多个线程之间共享信息
• 检索历史对话信息
• 维护个性化体验

核心特性

• 持久化存储：使用 LangGraph Store 持久化状态
• 跨会话记忆：在不同会话间保持记忆
• 线程隔离：支持多线程并发执行
• 自动检索：智能检索相关历史信息

使用示例

# 智能体自动使用长期记忆
# 第一次对话
response1 = agent.invoke({
    "messages": [{"role": "user", "content": "我喜欢Python编程"}]
})
# 记忆被保存

# 第二次对话（新会话）
response2 = agent.invoke({
    "messages": [{"role": "user", "content": "推荐一些学习资源"}]
})
# 智能体自动检索之前的偏好，推荐Python相关资源

5. Agent Harness（智能体框架）

功能描述

Agent Harness 是 DeepAgents 的核心执行框架，提供：

• 智能体的创建和管理
• 工具调用的协调
• 中间件的集成
• 执行流程的控制

6. Backends（后端支持）

功能描述

Backends 提供不同的执行后端：

• 内存后端：用于开发和测试
• 持久化后端：用于生产环境
• 分布式后端：用于大规模部署

7. Human-in-the-Loop（人机交互）

功能描述

Human-in-the-Loop 支持在关键步骤引入人工审批：

• 在执行可能具有破坏性的操作时暂停
• 等待人工确认后继续执行
• 确保智能体的操作符合预期

---

DeepAgents 工作原理

核心原理概述

DeepAgents 的工作原理可以用一个简单的比喻来理解：它就像一个智能的项目经理，能够自动规划任务、管理资源、委派工作，并记住所有重要信息。

1. 中间件架构（Middleware Architecture）

通俗理解：DeepAgents 采用"中间件"设计，就像工厂的流水线，每个中间件负责一个特定环节的处理。

• 规划中间件：负责制定工作计划（类似项目经理做任务分解）
• 文件系统中间件：负责管理文档和资料（类似文件柜管理员）
• 子智能体中间件：负责委派任务给专门人员（类似项目经理分配工作给不同部门）
• 记忆中间件：负责记住重要信息（类似会议记录员）

当用户提出一个任务时，这些中间件会依次处理，每个中间件完成自己的职责后，将结果传递给下一个中间件。

2. 状态管理机制

通俗理解：DeepAgents 使用 LangGraph 的状态管理，就像游戏中的"存档系统"。

• 状态保存：智能体在执行过程中会定期保存当前状态（类似游戏存档）
• 状态恢复：如果执行中断，可以从上次保存的状态继续（类似游戏读档）
• 状态共享：不同会话可以共享某些状态（类似多人在线游戏的共享数据）

这确保了智能体可以处理长时间运行的任务，即使中途出现问题也能恢复。

3. 工具调用机制

通俗理解：DeepAgents 的工具调用就像给智能体配备各种"工具箱"。

• 工具注册：开发者提供工具（如搜索、文件操作等）
• 智能选择：智能体根据任务需求自动选择合适的工具
• 结果处理：工具执行结果会被智能体理解和利用

智能体就像一个多才多艺的助手，会根据任务需要自动选择和使用合适的工具。

4. 上下文隔离机制

通俗理解：当智能体创建子智能体时，就像给每个子任务分配一个独立的"工作间"。

• 主智能体：保持清晰的上下文，专注于整体规划
• 子智能体：在独立上下文中工作，不会污染主智能体的记忆
• 结果汇总：子智能体完成任务后，将结果返回给主智能体

这就像公司里，CEO（主智能体）负责整体规划，各个部门（子智能体）在各自领域独立工作，最后向CEO汇报。

DeepAgents 数据流

下面的图表展示了 DeepAgents 处理任务时的数据流动过程：

数据流说明：

1. 输入阶段：用户输入任务，Agent Harness 接收并初始化
2. 规划阶段：如果需要，规划中间件将任务分解为步骤
3. 处理阶段：LLM 模型分析任务并决定下一步行动
4. 工具调用阶段：根据需求调用相应工具（文件系统、子智能体、自定义工具）
5. 结果处理阶段：工具执行结果返回，更新状态
6. 记忆阶段：重要信息保存到长期记忆
7. 循环判断：检查任务是否完成，未完成则继续处理
8. 输出阶段：生成最终响应返回给用户

DeepAgents 运转流程

下面的图表展示了 DeepAgents 的完整执行流程，包括各个组件如何协作：

运转流程说明：

1. 初始化阶段

   • 用户提交任务请求
   • Agent Harness 接收并初始化
   • 规划中间件检查是否需要任务分解

2. 规划阶段

   • 如果需要，规划中间件使用 write_todos 将任务分解为步骤
   • 生成任务列表并返回给 Harness

3. 执行循环（核心循环）

   • LLM 分析：LLM 模型分析当前状态和任务，决定下一步行动
   • 工具调用：根据需求调用相应工具
     • 文件操作：文件系统中间件处理
     • 子任务：子智能体中间件创建并执行子智能体
     • 自定义工具：调用开发者提供的工具
   • 记忆更新：重要信息保存到长期记忆
   • 状态更新：更新执行状态
   • 循环判断：检查任务是否完成

4. 完成阶段

   • 所有任务完成后，返回最终结果给用户

关键机制详解

1. 任务规划机制

工作原理：

• 智能体接收到复杂任务后，首先使用 write_todos 工具创建任务列表
• 任务列表存储在状态中，智能体可以随时查看和更新
• 智能体按照任务列表逐步执行，每完成一个任务就更新状态
• 如果发现新信息需要调整计划，智能体可以动态修改任务列表

类比：就像项目经理制定项目计划，然后按计划执行，遇到变化时调整计划。

2. 上下文管理机制

工作原理：

• 当上下文信息过多时，智能体自动使用 write_file 将信息存储到文件
• 需要时使用 read_file 读取文件内容
• 文件系统作为"外部记忆"，不占用 LLM 的上下文窗口
• 智能体可以管理多个文件，组织信息结构

类比：就像把重要资料存到文件柜，需要时再取出来，而不是把所有资料都放在桌子上。

3. 子智能体机制

工作原理：

• 主智能体使用 task 工具创建子智能体
• 子智能体在完全独立的上下文中运行
• 子智能体可以有自己的工具和系统提示
• 子智能体完成任务后，将结果返回给主智能体
• 主智能体的上下文不受子智能体影响

类比：就像 CEO 把任务分配给各个部门，各部门独立工作，最后向 CEO 汇报结果。

4. 长期记忆机制

工作原理：

• 使用 LangGraph 的 Store 持久化状态
• 每个会话有唯一的 thread_id
• 智能体可以检索历史对话和状态
• 记忆可以跨会话共享（如果使用相同的 thread_id）

类比：就像公司的知识库，记录所有重要信息，需要时可以随时查阅。

执行示例：研究任务

让我们通过一个具体例子来理解 DeepAgents 的工作原理：

用户请求：“研究量子计算的最新进展并撰写报告”

执行过程：

1. 接收任务

   Agent Harness: 收到任务"研究量子计算..."
   

2. 任务规划

   规划中间件: 使用 write_todos 创建任务列表
   - [ ] 搜索量子计算最新研究
   - [ ] 分析关键技术突破
   - [ ] 总结应用场景
   - [ ] 撰写研究报告
   

3. 执行第一个任务

   LLM: 需要搜索信息，调用 internet_search 工具
   工具: 执行搜索，返回结果
   LLM: 结果太多，使用 write_file 保存到 research_data.txt
   

4. 执行第二个任务

   LLM: 需要分析数据，读取 research_data.txt
   文件系统: 返回文件内容
   LLM: 分析数据，提取关键信息
   

5. 执行第三个任务

   LLM: 需要深入研究某个技术点，创建子智能体
   子智能体中间件: 创建子智能体
   子智能体: 独立研究，返回结果
   

6. 执行第四个任务

   LLM: 需要撰写报告，读取所有收集的信息
   LLM: 生成报告，使用 write_file 保存
   

7. 完成任务

   Agent Harness: 所有任务完成，返回报告给用户
   

性能优化机制

1. 并行处理

• 多个子智能体可以并行执行
• 文件操作可以异步进行
• 工具调用可以并发处理

2. 缓存机制

• 工具结果可以缓存
• 文件内容可以缓存
• 减少重复计算

3. 流式输出

• 支持流式输出响应
• 用户可以实时看到处理进度
• 提升用户体验

---

环境安装与配置

安装 DeepAgents

完整安装

# 安装 DeepAgents 及其依赖
pip install deepagents langchain langgraph

# 安装模型提供商集成（按需选择）
pip install langchain-openai      # OpenAI
pip install langchain-anthropic   # Anthropic
pip install langchain-google-genai # Google

# 安装可选工具
pip install tavily-python         # 互联网搜索
pip install langsmith              # 监控和调试

环境变量配置

创建 .env 文件或在系统环境变量中设置：

# Anthropic（DeepAgents 默认使用 Claude）
export ANTHROPIC_API_KEY="your-anthropic-api-key"

# OpenAI（可选）
export OPENAI_API_KEY="your-openai-api-key"

# Google（可选）
export GOOGLE_API_KEY="your-google-api-key"

# Tavily（用于互联网搜索，可选）
export TAVILY_API_KEY="your-tavily-api-key"

# LangSmith（用于监控和调试，可选）
export LANGCHAIN_TRACING_V2="true"
export LANGCHAIN_API_KEY="your-langsmith-api-key"
export LANGCHAIN_PROJECT="your-project-name"

验证安装

import deepagents
print(f"DeepAgents 版本: {deepagents.__version__}")

# 测试导入
from deepagents import create_deep_agent
print("DeepAgents 安装成功！")

版本要求

• Python: 3.10 或更高版本
• LangChain: 0.3.0 或更高版本
• LangGraph: 0.2.0 或更高版本

---

完整示例代码

示例 1：基础研究智能体

这是一个完整的研究智能体示例，展示 DeepAgents 的核心功能：

import os
from typing import Literal
from deepagents import create_deep_agent
from tavily import TavilyClient

# 设置 API 密钥
os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-api-key"
os.environ["TAVILY_API_KEY"] = "your-tavily-api-key"

# 初始化 Tavily 客户端（用于互联网搜索）
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

# 定义互联网搜索工具
def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
) -> dict:
    """
    使用 Tavily 进行互联网搜索
    
    Args:
        query: 搜索查询
        max_results: 最大结果数量
        topic: 搜索主题类型
        include_raw_content: 是否包含原始内容
    
    Returns:
        搜索结果字典
    """
    results = tavily_client.search(
        query=query,
        max_results=max_results,
        topic=topic,
        include_raw_content=include_raw_content,
    )
    return results

# 创建 DeepAgent
agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",  # 或使用 "gpt-4o" 等
    tools=[internet_search],
    system_prompt="""你是一位专家研究员。你的任务是进行深入研究并撰写报告。
    
    你可以使用以下能力：
    1. 使用 internet_search 工具搜索最新信息
    2. 使用 write_todos 工具规划研究步骤
    3. 使用文件系统工具（write_file, read_file）管理研究内容
    4. 使用 task 工具创建子智能体处理特定研究任务
    
    请确保你的研究报告结构清晰、内容详实、引用准确。"""
)

# 运行智能体
if __name__ == "__main__":
    response = agent.invoke({"messages": [{"role": "user", "content": "请研究量子计算的最新进展，包括主要技术突破、应用场景和未来发展趋势，并撰写一份详细的研究报告。"}]})

    print(response)

示例 2：代码生成与调试智能体

这个示例展示如何使用 DeepAgents 进行代码生成和调试：

import os
from deepagents import create_deep_agent
from langchain_core.tools import tool

# 设置 API 密钥
os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-api-key"

# 定义代码执行工具（示例，实际使用需要安全考虑）
@tool
def execute_python_code(code: str) -> str:
    """
    执行 Python 代码并返回结果
    
    Args:
        code: 要执行的 Python 代码
    
    Returns:
        执行结果
    """
    try:
        # 注意：实际应用中需要沙箱环境
        exec_globals = {}
        exec(code, exec_globals)
        return "代码执行成功"
    except Exception as e:
        return f"执行错误: {str(e)}"

# 创建代码生成智能体
agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[execute_python_code],
    system_prompt="""你是一位专业的 Python 开发工程师。你的任务是：
    
    1. 根据需求生成高质量的 Python 代码
    2. 使用 write_file 工具保存代码到文件
    3. 使用 execute_python_code 工具测试代码
    4. 使用 edit_file 工具修复发现的错误
    5. 使用 write_todos 工具规划开发任务
    
    请确保代码符合最佳实践，包含适当的注释和错误处理。"""
)

# 运行智能体
if __name__ == "__main__":
    response = agent.invoke({
        "messages": [{
            "role": "user",
            "content": """
            请创建一个 Python 类，实现一个简单的计算器，支持加减乘除运算。
            要求：
            1. 使用面向对象设计
            2. 包含错误处理
            3. 添加单元测试
            4. 保存为 calculator.py
            """
        }]
    })
    print(response)

示例 3：多步骤任务处理智能体

这个示例展示 DeepAgents 如何处理复杂的多步骤任务：

import os
from deepagents import create_deep_agent
from langchain_core.tools import tool

# 设置 API 密钥
os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-api-key"

# 定义业务工具
@tool
def search_product(name: str) -> str:
    """搜索产品信息"""
    # 模拟产品搜索
    products = {
        "iPhone": "iPhone 15 Pro, 价格: 8999元",
        "MacBook": "MacBook Pro M3, 价格: 12999元"
    }
    return products.get(name, f"未找到产品: {name}")

@tool
def check_inventory(product_id: str) -> str:
    """检查产品库存"""
    # 模拟库存检查
    return f"产品 {product_id} 当前库存: 50件"

@tool
def create_order(product_id: str, quantity: int) -> str:
    """创建订单"""
    return f"订单已创建: 产品 {product_id}, 数量 {quantity}"

# 创建业务处理智能体
agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[search_product, check_inventory, create_order],
    system_prompt="""你是一个订单处理助手。你的任务是：
    
    1. 使用 write_todos 工具规划订单处理步骤
    2. 搜索产品信息
    3. 检查库存状态
    4. 如果库存充足，创建订单
    5. 使用文件系统工具记录处理过程
    
    请确保每个步骤都正确执行，并记录处理结果。"""
)

# 运行智能体
if __name__ == "__main__":
    response = agent.invoke({
        "messages": [{
            "role": "user",
            "content": """
            请处理以下订单请求：
            1. 搜索产品 'iPhone'
            2. 检查库存
            3. 如果库存充足，创建一个数量为 2 的订单
            4. 将处理结果保存到 order_result.txt
            """
        }]
    })
    print(response)

示例 4：带长期记忆的对话智能体

这个示例展示如何使用 DeepAgents 的长期记忆功能：

import os
from deepagents import create_deep_agent
from langgraph.checkpoint import MemorySaver

# 设置 API 密钥
os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-api-key"

# 创建带记忆的智能体
memory = MemorySaver()

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[],
    system_prompt="""你是一个友好的个人助手。你会记住用户的偏好和历史对话。
    
    请根据之前的对话内容，提供个性化的建议和帮助。""",
    checkpointer=memory,  # 启用长期记忆
)

# 第一次对话
if __name__ == "__main__":
    thread_id = "user-123"  # 用户线程ID，用于跨会话记忆
    
    # 第一次对话
    response1 = agent.invoke({
        "messages": [{"role": "user", "content": "我喜欢 Python 编程和机器学习"}]
    }, config={"configurable": {"thread_id": thread_id}})
    print("第一次对话:", response1)
    
    # 第二次对话（会记住之前的偏好）
    response2 = agent.invoke({
        "messages": [{"role": "user", "content": "推荐一些学习资源"}]
    }, config={"configurable": {"thread_id": thread_id}})
    print("第二次对话:", response2)
    
    # 第三次对话（继续记忆）
    response3 = agent.invoke({
        "messages": [{"role": "user", "content": "我之前提到的兴趣是什么？"}]
    }, config={"configurable": {"thread_id": thread_id}})
    print("第三次对话:", response3)

---

与 LangChain 1.x 和 LangGraph 对比

功能对比表

特性	LangChain 1.x	LangGraph	DeepAgents
定位	高级抽象和组件库	低级别编排框架	高级智能体框架
任务规划	需要手动实现	需要手动实现	✅ 内置 write_todos
上下文管理	基础支持	需要手动实现	✅ 内置文件系统工具
子智能体	需要手动实现	需要手动实现	✅ 内置 task 工具
长期记忆	基础支持	✅ 强大的 Store	✅ 集成 LangGraph Store
学习曲线	中等	较陡	中等
适用场景	快速构建智能体	复杂工作流编排	复杂多步骤任务
代码复杂度	低	高	中等

代码对比示例

场景：研究任务并生成报告

LangChain 1.x 实现

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool

@tool
def search_web(query: str) -> str:
    """搜索网络信息"""
    return f"关于 '{query}' 的搜索结果"

# 创建智能体
agent = create_agent(
    model=ChatOpenAI(model="gpt-4o"),
    tools=[search_web],
    system_prompt="你是一个研究员",
)

# 需要手动规划任务步骤
response = agent.invoke({
    "messages": [{
        "role": "user",
        "content": """
        请按以下步骤进行研究：
        1. 搜索量子计算最新进展
        2. 搜索应用场景
        3. 生成报告
        """
    }]
})

# 问题：
# - 需要手动规划步骤
# - 上下文管理需要额外处理
# - 大量信息可能导致上下文溢出

LangGraph 实现

from langgraph.graph import StateGraph, END
from langchain_openai import ChatOpenAI
from typing import TypedDict, Annotated
import operator

class ResearchState(TypedDict):
    messages: Annotated[list, operator.add]
    research_data: dict
    report: str

def search_step(state: ResearchState):
    """搜索步骤"""
    llm = ChatOpenAI(model="gpt-4o")
    # 执行搜索...
    return {"research_data": {...}}

def analyze_step(state: ResearchState):
    """分析步骤"""
    # 分析数据...
    return {"report": "..."}

def generate_report_step(state: ResearchState):
    """生成报告步骤"""
    # 生成报告...
    return {"report": "完整报告"}

# 构建图
workflow = StateGraph(ResearchState)
workflow.add_node("search", search_step)
workflow.add_node("analyze", analyze_step)
workflow.add_node("generate", generate_report_step)
workflow.set_entry_point("search")
workflow.add_edge("search", "analyze")
workflow.add_edge("analyze", "generate")
workflow.add_edge("generate", END)

app = workflow.compile()

# 问题：
# - 需要手动设计整个工作流
# - 需要手动管理状态
# - 文件系统集成需要额外开发
# - 子智能体需要手动实现

DeepAgents 实现

from deepagents import create_deep_agent
from tavily import TavilyClient

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def internet_search(query: str, max_results: int = 5):
    return tavily_client.search(query=query, max_results=max_results)

# 创建智能体
agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[internet_search],
    system_prompt="你是一位专家研究员",
)

# 一行代码完成所有任务
response = agent.invoke({
    "messages": [{"role": "user", "content": "请研究量子计算的最新进展并撰写报告"}]
})

# 优势：
# - 自动规划任务步骤（使用 write_todos）
# - 自动管理上下文（使用文件系统工具）
# - 可以创建子智能体处理特定任务（使用 task）
# - 代码简洁，功能强大

详细功能对比

1. 任务规划能力

LangChain 1.x：

# 需要手动规划
steps = ["步骤1", "步骤2", "步骤3"]
for step in steps:
    agent.invoke({"messages": [{"role": "user", "content": step}]})

LangGraph：

# 需要手动设计状态图
workflow.add_node("step1", step1_function)
workflow.add_node("step2", step2_function)
# 需要手动定义边和条件

DeepAgents：

# 自动规划
response = agent.invoke({
    "messages": [{"role": "user", "content": "复杂任务"}]
})  # 智能体自动使用 write_todos 规划

2. 上下文管理

LangChain 1.x：

# 需要手动管理上下文
context = load_all_data()  # 可能溢出
messages = [{"role": "user", "content": context + query}]

LangGraph：

# 需要手动在状态中管理
class State(TypedDict):
    context: str  # 手动管理

DeepAgents：

# 自动使用文件系统管理
agent.write_file("context.txt", large_data)  # 自动存储
content = agent.read_file("context.txt")  # 需要时读取

3. 子智能体生成

LangChain 1.x：

# 需要手动创建和管理
sub_agent = create_agent(...)
result = sub_agent.invoke(...)
# 需要手动管理上下文隔离

LangGraph：

# 需要手动设计子图
sub_graph = StateGraph(SubState)
# 需要手动管理子图执行

DeepAgents：

# 一行代码创建子智能体
result = agent.task("子任务描述", tools=[...])
# 自动上下文隔离

如何选择

使用 LangChain 1.x 当：

• ✅ 需要快速构建简单的智能体
• ✅ 任务相对简单，不需要复杂规划
• ✅ 上下文量较小
• ✅ 不需要子智能体

使用 LangGraph 当：

• ✅ 需要完全控制工作流
• ✅ 需要复杂的条件分支和循环
• ✅ 需要自定义状态管理
• ✅ 需要持久化执行

使用 DeepAgents 当：

• ✅ 需要处理复杂、多步骤任务
• ✅ 需要自动任务规划
• ✅ 需要管理大量上下文
• ✅ 需要子智能体支持
• ✅ 需要长期记忆
• ✅ 希望代码简洁但功能强大

---

高级特性与最佳实践

1. 自定义中间件

DeepAgents 采用模块化的中间件架构，允许自定义中间件：

from deepagents import create_deep_agent
from deepagents.middleware import Middleware

class CustomMiddleware(Middleware):
    """自定义中间件示例"""
    
    def process_tool_call(self, tool_name, args):
        """处理工具调用"""
        print(f"调用工具: {tool_name}")
        return args
    
    def process_response(self, response):
        """处理响应"""
        print(f"收到响应: {response}")
        return response

# 使用自定义中间件
agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[...],
    middleware=[CustomMiddleware()],
)

2. 人机交互（Human-in-the-Loop）

在关键步骤引入人工审批：

from deepagents import create_deep_agent
from langgraph.checkpoint import MemorySaver

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[...],
    checkpointer=MemorySaver(),
    interrupt_before=["write_file", "edit_file"],  # 在执行这些工具前暂停
)

# 运行时会暂停等待人工确认
response = agent.invoke({
    "messages": [{"role": "user", "content": "执行可能具有破坏性的操作"}]
})

3. 性能优化

使用流式处理

# 流式输出响应
for chunk in agent.stream({
    "messages": [{"role": "user", "content": "复杂任务"}]
}):
    print(chunk, end="", flush=True)

并发执行子任务

# DeepAgents 自动支持子智能体的并发执行
results = agent.task("任务1")  # 可以并行执行多个任务
results = agent.task("任务2")

4. 错误处理

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[...],
    max_iterations=50,  # 限制最大迭代次数
    max_execution_time=300,  # 限制最大执行时间（秒）
)

try:
    response = agent.invoke({
        "messages": [{"role": "user", "content": "复杂任务"}]
    })
except Exception as e:
    print(f"执行错误: {e}")
    # DeepAgents 会自动保存执行状态，可以恢复

5. 监控与调试

使用 LangSmith 监控

import os
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "your-api-key"
os.environ["LANGCHAIN_PROJECT"] = "deepagents-project"

# 所有执行会自动记录到 LangSmith
agent.invoke({
    "messages": [{"role": "user", "content": "任务"}]
})

本地调试

# 启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[...],
    verbose=True,  # 启用详细输出
)

最佳实践

1. 合理使用文件系统工具

   • 将大量上下文存储到文件
   • 定期清理不需要的文件
   • 使用有意义的文件名

2. 有效规划任务

   • 让智能体自动规划，但可以引导
   • 定期检查任务进度
   • 根据新信息调整计划

3. 子智能体设计

   • 为特定任务创建专门的子智能体
   • 保持子智能体的职责单一
   • 合理配置子智能体的工具

4. 长期记忆管理

   • 使用有意义的 thread_id
   • 定期清理过期的记忆
   • 合理使用记忆检索

5. 错误处理

   • 设置合理的执行限制
   • 实现错误恢复机制
   • 记录详细的执行日志

---

应用场景与案例

案例 1：学术研究助手

场景：帮助研究人员进行文献调研和报告撰写

实现：

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[internet_search, academic_search],
    system_prompt="你是学术研究助手，擅长文献调研和报告撰写",
)

response = agent.invoke({
    "messages": [{
        "role": "user",
        "content": """
        研究主题：Transformer 架构在自然语言处理中的应用
        要求：
        1. 收集最新研究论文
        2. 分析关键技术突破
        3. 总结应用场景
        4. 撰写学术报告
        """
    }]
})

优势：

• 自动规划研究步骤
• 管理大量文献资料
• 生成结构化报告

案例 2：代码审查助手

场景：自动审查代码并提供改进建议

实现：

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[read_file, edit_file, code_analysis],
    system_prompt="你是代码审查专家",
)

response = agent.invoke({
    "messages": [{
        "role": "user",
        "content": """
        审查项目代码：
        1. 读取所有 Python 文件
        2. 分析代码质量
        3. 识别潜在问题
        4. 提供改进建议
        5. 生成审查报告
        """
    }]
})

优势：

• 处理大量代码文件
• 自动生成审查报告
• 提供具体改进建议

案例 3：智能客服系统

场景：处理复杂的客户咨询，维护对话历史

实现：

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[search_knowledge_base, create_ticket],
    checkpointer=MemorySaver(),
    system_prompt="你是专业的客服助手",
)

# 第一次对话
response1 = agent.invoke({
    "messages": [{"role": "user", "content": "我想了解产品A的功能"}]
}, config={"configurable": {"thread_id": "customer-123"}})

# 后续对话（记住历史）
response2 = agent.invoke({
    "messages": [{"role": "user", "content": "刚才提到的产品价格是多少？"}]
}, config={"configurable": {"thread_id": "customer-123"}})

优势：

• 维护长期对话记忆
• 自动检索相关知识
• 提供个性化服务

---

总结与选择指南

DeepAgents 核心价值

DeepAgents 在 LangChain 和 LangGraph 的基础上，提供了：

1. 开箱即用的高级功能：规划、上下文管理、子智能体、长期记忆
2. 简化的开发体验：一行代码创建强大的智能体
3. 生产级特性：持久化、监控、错误处理
4. 灵活的架构：模块化中间件，易于扩展

技术栈关系

LangChain (基础组件)
    ↓
LangGraph (编排框架)
    ↓
DeepAgents (高级智能体框架)

• LangChain 提供基础组件（模型、工具、提示词等）
• LangGraph 提供编排能力（状态管理、工作流）
• DeepAgents 提供高级智能体能力（规划、上下文管理、子智能体）

选择建议

选择 DeepAgents 当：

✅ 复杂任务处理

• 需要处理多步骤、复杂任务
• 需要自动任务规划
• 需要动态调整计划

✅ 上下文管理

• 需要处理大量上下文信息
• 需要防止上下文窗口溢出
• 需要持久化中间结果

✅ 任务委派

• 需要创建子智能体
• 需要上下文隔离
• 需要专业化处理

✅ 长期记忆

• 需要跨会话记忆
• 需要个性化体验
• 需要历史信息检索

选择 LangChain 1.x 当：

✅ 简单任务，不需要复杂规划
✅ 快速原型开发
✅ 上下文量较小

选择 LangGraph 当：

✅ 需要完全控制工作流
✅ 需要复杂的条件分支
✅ 需要自定义状态管理