零基础也能快速搭建的Deep Agents

[一、什么是 DeepAgent？](#一、什么是 DeepAgent？)
- 核心设计理念
二、环境准备与安装
- [2.1 前置条件](#2.1 前置条件)
- [2.2 安装依赖](#2.2 安装依赖)
- [2.3 配置环境变量](#2.3 配置环境变量)
[三、快速开始：你的第一个 DeepAgent](#三、快速开始：你的第一个 DeepAgent)
- [3.1 基础示例](#3.1 基础示例)
- [3.2 DeepAgent 工作原理](#3.2 DeepAgent 工作原理)
四、内置工具详解
- [4.1 任务管理工具](#4.1 任务管理工具)
- [4.2 文件系统工具（7个）](#4.2 文件系统工具（7个）)
- [4.3 子代理工具](#4.3 子代理工具)
五、子代理系统
- [5.1 为什么需要子代理？](#5.1 为什么需要子代理？)
- [5.2 创建子代理](#5.2 创建子代理)
- [5.3 SubAgent 类型规范](#5.3 SubAgent 类型规范)
六、中间件系统
- [6.1 FilesystemMiddleware](#6.1 FilesystemMiddleware)
- [6.2 SubAgentMiddleware](#6.2 SubAgentMiddleware)
七、后端系统
- [7.1 后端架构](#7.1 后端架构)
- [7.2 自定义后端策略](#7.2 自定义后端策略)
八、人机协作
- [8.1 配置中断点](#8.1 配置中断点)
- [8.2 子代理级别的中断配置](#8.2 子代理级别的中断配置)
[九、完整 API 参考](#九、完整 API 参考)
- [9.1 create_deep_agent 函数签名](#9.1 create_deep_agent 函数签名)
- [9.2 参数说明](#9.2 参数说明)
[十、Deep Research 能力实现机制](#十、Deep Research 能力实现机制)
- [10.1 自动规划与任务分解](#10.1 自动规划与任务分解)
- [10.2 上下文管理](#10.2 上下文管理)
- [10.3 子代理委派与上下文隔离](#10.3 子代理委派与上下文隔离)
- [10.4 长期记忆与持久化存储](#10.4 长期记忆与持久化存储)
- [10.5 Deep Research 完整工作流程](#10.5 Deep Research 完整工作流程)
- [10.6 关键设计模式总结](#10.6 关键设计模式总结)
十一、总结

一、什么是 DeepAgent？

DeepAgents 是 LangChain 推出的一个独立库，专门用于构建能够处理复杂、多步骤任务的 AI Agent。它基于 LangGraph 构建，灵感来源于 Claude Code、Deep Research 和 Manus 等应用。

核心设计理念

DeepAgent 的设计围绕以下三个核心能力展开：

内置规划能力 - Agent 可以自动将复杂任务分解为可执行的步骤
文件系统支持 - 通过文件系统工具进行上下文管理
子代理生成 - 能够启动专门的子代理来处理特定子任务

官方文档来源 ：Deep Agents Overview

二、环境准备与安装

2.1 前置条件

在开始使用 DeepAgent 之前，你需要准备以下内容：

要求	说明
API Key	至少需要一个模型提供商的 API Key（如 Anthropic 或 OpenAI）
Python 环境	Python 3.8+

2.2 安装依赖

bash 复制代码

# 使用 pip 安装
pip install deepagents tavily-python

# 或使用 uv
uv add deepagents tavily-python

# 或使用 poetry
poetry add deepagents tavily-python

2.3 配置环境变量

bash 复制代码

export ANTHROPIC_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

官方文档来源 ：DeepAgents Quickstart - Prerequisites

三、快速开始：你的第一个 DeepAgent

3.1 基础示例

让我们创建一个具有研究能力的 DeepAgent：

python 复制代码

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

# 初始化 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,
):
    """运行网络搜索"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

# 定义系统提示词
research_instructions = """你是一位专业的研究员。你的工作是进行深入研究，然后撰写一份结构清晰的报告。

你可以使用网络搜索工具作为收集信息的主要手段。

## `internet_search`

使用此工具运行网络搜索。你可以指定返回的最大结果数、搜索主题，以及是否包含原始内容。
"""

# 创建 DeepAgent
agent = create_deep_agent(
    tools=[internet_search],
    system_prompt=research_instructions
)

# 执行查询
result = agent.invoke({
    "messages": [{"role": "user", "content": "什么是 LangGraph？"}]
})

# 打印结果
print(result["messages"][-1].content)

官方文档来源 ：DeepAgents Quickstart

3.2 DeepAgent 工作原理

当上述代码执行时，DeepAgent 会经历以下步骤：

规划阶段 - Agent 使用内置的 write_todos 工具将任务分解为步骤
研究阶段 - 调用 internet_search 工具收集信息
上下文管理 - 使用文件系统工具（write_file、read_file）存储和检索大量搜索结果
综合阶段 - 将收集的信息整合成连贯的报告

四、内置工具详解

create_deep_agent 函数创建的 Agent 默认配备以下工具：

4.1 任务管理工具

工具名称	功能描述
`write_todos`	自动创建和管理待办事项列表，用于任务规划

4.2 文件系统工具（7个）

工具名称	功能描述
`ls`	列出目录内容，支持元数据查看
`read_file`	读取文件内容，支持行号和偏移量/限制参数
`write_file`	创建新文件或覆盖现有文件
`edit_file`	执行精确的字符串替换操作
`glob`	使用模式匹配查找文件
`grep`	搜索文件内容，支持多种输出模式
`execute`	运行 shell 命令（需要后端支持 SandboxBackendProtocol）

官方文档来源 ：create_deep_agent API Reference

4.3 子代理工具

工具名称	功能描述
`task`	启动专门的子代理来处理特定子任务

五、子代理系统

5.1 为什么需要子代理？

子代理的主要用途包括：

上下文隔离 - 将详细任务隔离到子代理中，保持主代理上下文清洁
专业化处理 - 为特定任务提供专门的指令

5.2 创建子代理

python 复制代码

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

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,
):
    """运行网络搜索"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

# 定义研究子代理
research_subagent = {
    "name": "research-agent",
    "description": "用于深入研究问题",
    "system_prompt": "你是一位优秀的研究员",
    "tools": [internet_search],
    "model": "openai:gpt-4o",
}

# 创建带有子代理的主 Agent
agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    subagents=[research_subagent],
    system_prompt="""...你的指令...

重要提示：对于复杂任务，使用 task() 工具委托给子代理。
这可以保持你的上下文清洁并提高结果质量。"""
)

官方文档来源 ：DeepAgents Subagents

5.3 SubAgent 类型规范

python 复制代码

# SubAgent 类型定义
name: str                                    # 子代理名称
description: str                             # 子代理描述
system_prompt: str                           # 系统提示词
tools: Sequence[BaseTool | Callable | dict]  # 工具列表
model: NotRequired[str | BaseChatModel]      # 可选：模型覆盖
middleware: NotRequired[list[AgentMiddleware]]  # 可选：中间件列表
interrupt_on: NotRequired[dict]              # 可选：中断配置

六、中间件系统

6.1 FilesystemMiddleware

文件系统中间件为 Agent 提供文件系统工具。

python 复制代码

from langchain.agents import create_agent
from deepagents.middleware.filesystem import FilesystemMiddleware

# 创建带有自定义文件系统中间件的 Agent
agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    middleware=[
        FilesystemMiddleware(
            backend=None,  # 可选：自定义后端（默认为 StateBackend）
            system_prompt="在需要时写入文件系统...",
            custom_tool_descriptions={
                "ls": "使用 ls 工具当...",
                "read_file": "使用 read_file 工具来..."
            }
        ),
    ],
)

官方文档来源 ：FilesystemMiddleware

6.2 SubAgentMiddleware

子代理中间件用于管理子代理。

python 复制代码

from langchain.tools import tool
from langchain.agents import create_agent
from deepagents.middleware.subagents import SubAgentMiddleware

@tool
def get_weather(city: str) -> str:
    """获取城市天气"""
    return f"{city} 的天气是晴天。"

agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    middleware=[
        SubAgentMiddleware(
            default_model="claude-sonnet-4-5-20250929",
            default_tools=[],
            subagents=[
                {
                    "name": "weather",
                    "description": "该子代理可以获取城市天气",
                    "system_prompt": "使用 get_weather 工具获取城市天气",
                    "tools": [get_weather],
                    "model": "gpt-4o",
                    "middleware": [],
                }
            ],
        )
    ],
)

官方文档来源 ：DeepAgents Middleware

七、后端系统

7.1 后端架构

DeepAgent 通过可插拔的后端架构提供文件系统功能。所有文件操作工具（ls、read_file、write_file、edit_file、glob、grep）都通过实现 BackendProtocol 的后端进行操作。

7.2 自定义后端策略

以下示例展示如何创建一个带有写入策略限制的后端包装器：

python 复制代码

from deepagents.backends.protocol import BackendProtocol, WriteResult, EditResult
from deepagents.backends.utils import FileInfo, GrepMatch

class PolicyWrapper(BackendProtocol):
    def __init__(self, inner: BackendProtocol, deny_prefixes: list[str] | None = None):
        self.inner = inner
        self.deny_prefixes = [p if p.endswith("/") else p + "/" for p in (deny_prefixes or [])]

    def _deny(self, path: str) -> bool:
        return any(path.startswith(p) for p in self.deny_prefixes)

    def ls_info(self, path: str) -> list[FileInfo]:
        return self.inner.ls_info(path)

    def read(self, file_path: str, offset: int = 0, limit: int = 2000) -> str:
        return self.inner.read(file_path, offset=offset, limit=limit)

    def grep_raw(self, pattern: str, path: str | None = None, glob: str | None = None) -> list[GrepMatch] | str:
        return self.inner.grep_raw(pattern, path, glob)

    def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
        return self.inner.glob_info(pattern, path)

    def write(self, file_path: str, content: str) -> WriteResult:
        if self._deny(file_path):
            return WriteResult(error=f"不允许在 {file_path} 下写入")
        return self.inner.write(file_path, content)

    def edit(self, file_path: str, old_string: str, new_string: str, replace_all: bool = False) -> EditResult:
        if self._deny(file_path):
            return EditResult(error=f"不允许在 {file_path} 下编辑")
        return self.inner.edit(file_path, old_string, new_string, replace_all)

官方文档来源 ：DeepAgents Backends

八、人机协作

8.1 配置中断点

你可以配置 Agent 在特定工具调用前等待人工确认：

python 复制代码

from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()

agent = create_deep_agent(
    tools=[delete_file, read_file],
    interrupt_on={
        "delete_file": True,   # 删除文件前需要确认
        "read_file": False,    # 读取文件不需要确认
    },
    checkpointer=checkpointer
)

8.2 子代理级别的中断配置

python 复制代码

agent = create_deep_agent(
    tools=[delete_file, read_file],
    interrupt_on={
        "delete_file": True,
        "read_file": False,
    },
    subagents=[
        {
            "name": "file-manager",
            "description": "管理文件操作",
            "system_prompt": "你是一个文件管理助手",
            "tools": [delete_file, read_file],
            "interrupt_on": {
                # 覆盖主代理设置：在此子代理中读取也需要确认
                "delete_file": True,
                "read_file": True,
            }
        }
    ],
    checkpointer=checkpointer
)

官方文档来源 ：DeepAgents Human-in-the-Loop

九、完整 API 参考

9.1 create_deep_agent 函数签名

python 复制代码

create_deep_agent(
    model: str | BaseChatModel | None = None,
    tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
    *,
    system_prompt: str | None = None,
    middleware: Sequence[AgentMiddleware] = (),
    subagents: list[SubAgent | CompiledSubAgent] | None = None,
    response_format: ResponseFormat | None = None,
    context_schema: type[Any] | None = None,
    checkpointer: Checkpointer | None = None,
    store: BaseStore | None = None,
    backend: BackendProtocol | BackendFactory | None = None,
    interrupt_on: dict[str, bool | InterruptOnConfig] | None = None,
    debug: bool = False,
    name: str | None = None,
    cache: BaseCache | None = None,
) -> CompiledStateGraph

9.2 参数说明

参数	类型	说明
`model`	str \| BaseChatModel	要使用的模型
`tools`	Sequence	自定义工具列表
`system_prompt`	str	系统提示词
`middleware`	Sequence	中间件列表
`subagents`	list	子代理列表
`response_format`	ResponseFormat	响应格式
`context_schema`	type	运行时上下文架构
`checkpointer`	Checkpointer	检查点（用于暂停/恢复）
`store`	BaseStore	持久化存储
`backend`	BackendProtocol	文件系统后端
`interrupt_on`	dict	工具中断配置
`debug`	bool	调试模式
`name`	str	Agent 名称
`cache`	BaseCache	缓存层

十、Deep Research 能力实现机制

DeepAgent 通过以下四个核心机制实现 Deep Research 能力，使其能够处理复杂的多步骤研究任务。

10.1 自动规划与任务分解

DeepAgent 内置 write_todos 工具，使其能够将复杂的研究任务自动分解为可管理的步骤。

机制说明：

Agent 在执行复杂任务前会自动创建待办事项列表
随着新信息的出现，可以动态调整和更新计划
保持对进度的可见性和跟踪能力

python 复制代码

from langchain.agents import create_agent
from langchain.agents.middleware import TodoListMiddleware

# 通过 TodoListMiddleware 获取规划能力
agent = create_agent(
    model="gpt-4o",
    tools=[read_file, write_file, run_tests],
    middleware=[TodoListMiddleware()],  # 自动提供 write_todos 工具
)

官方文档来源 ：Deep Agents - Planning and task decomposition

10.2 上下文管理

DeepAgent 通过文件系统工具将大量上下文"卸载"到内存中，防止上下文窗口溢出。

核心机制：

机制	说明
文件系统工具	`ls`、`read_file`、`write_file`、`edit_file` 用于存储中间结果
自动驱逐	当工具结果超过 20,000 tokens 时，自动写入文件而非保留在上下文中
按需读取	Agent 可以按需分批读取大文件

最佳实践示例：

python 复制代码

system_prompt="""When you gather large amounts of data:
1. Save raw data to /data/raw_results.txt
2. Process and analyze the data
3. Return only the analysis summary

This keeps context clean."""

官方文档来源 ：Deep Agents - Context management

10.3 子代理委派与上下文隔离

DeepAgent 使用 task 工具启动专门的子代理，实现上下文隔离和专业化处理。

上下文隔离优势：

子代理处理大量原始数据
结果保存到磁盘而非返回给主代理
主代理只收到简洁的分析摘要

多子代理研究工作流示例：

python 复制代码

from deepagents import create_deep_agent

# 定义三个专门的研究子代理
subagents = [
    {
        "name": "data-collector",
        "description": "从各种来源收集原始数据",
        "system_prompt": "全面收集有关该主题的数据",
        "tools": [web_search, api_call, database_query],
    },
    {
        "name": "data-analyzer",
        "description": "分析收集的数据以获取洞察",
        "system_prompt": "分析数据并提取关键洞察",
        "tools": [statistical_analysis],
    },
    {
        "name": "report-writer",
        "description": "根据分析撰写精心制作的报告",
        "system_prompt": "根据洞察创建专业报告",
        "tools": [format_document],
    },
]

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    system_prompt="你协调数据分析和报告工作。使用子代理处理专业任务。",
    subagents=subagents
)

官方文档来源 ：Deep Agents - Subagent spawning

10.4 长期记忆与持久化存储

DeepAgent 支持跨会话的长期记忆，使研究可以在多个会话之间继续。

python 复制代码

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

research_agent = create_deep_agent(
    store=InMemoryStore(),
    backend=lambda rt: CompositeBackend(
        default=StateBackend(rt),
        routes={"/memories/": StoreBackend(rt)}  # 持久化路径
    ),
    system_prompt="""你是一个研究助手。

将研究进度保存到 /memories/research/:
- /memories/research/sources.txt - 找到的来源列表
- /memories/research/notes.txt - 关键发现和笔记
- /memories/research/report.md - 最终报告草稿

这使研究可以在多个会话之间继续。"""
)

官方文档来源 ：Deep Agents - Long-term memory

10.5 Deep Research 完整工作流程

复制代码

┌─────────────────────────────────────────────────────────────────┐
│                        用户请求研究主题                          │
└────────────────────────┬────────────────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              1. 规划阶段 (write_todos 工具)                      │
│     - 将研究主题分解为多个子任务                                  │
│     - 创建可执行的待办事项列表                                    │
└────────────────────────┬────────────────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              2. 数据收集阶段 (子代理委派)                         │
│     - 启动 data-collector 子代理                                 │
│     - 调用 web_search、api_call 等工具                            │
│     - 大量数据自动保存到文件系统                                   │
└────────────────────────┬────────────────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              3. 分析阶段 (子代理委派)                            │
│     - 启动 data-analyzer 子代理                                  │
│     - 从文件系统读取收集的数据                                    │
│     - 执行统计分析，提取洞察                                      │
└────────────────────────┬────────────────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│              4. 综合阶段 (报告生成)                              │
│     - 启动 report-writer 子代理                                  │
│     - 整合所有分析结果                                           │
│     - 生成结构化的最终报告                                        │
└────────────────────────┬────────────────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                      返回最终研究报告                             │
└─────────────────────────────────────────────────────────────────┘

10.6 关键设计模式总结

能力	实现机制	核心工具/组件
任务规划	自动分解复杂任务	`write_todos` + `TodoListMiddleware`
上下文管理	卸载大结果到文件系统	文件系统工具 + 自动驱逐机制
专业化处理	上下文隔离的子代理	`task` 工具 + 子代理配置
持久化记忆	混合存储后端	`CompositeBackend` + `StoreBackend`
信息综合	Orchestrator-Worker 模式	LangGraph 工作流编排

十一、总结

LangChain DeepAgent 是一个功能强大的 Agent 框架，它通过以下特性简化了复杂 AI 应用的开发：

开箱即用的工具集 - 内置文件系统、任务管理、子代理调用等工具
灵活的架构 - 支持自定义工具、中间件、后端
强大的扩展性 - 子代理系统支持复杂任务的分解和委派
生产就绪 - 支持检查点、中断控制、缓存等生产级特性
Deep Research 能力 - 通过自动规划、上下文管理、子代理委派和长期记忆四大机制实现深度研究能力

参考资料：

零基础也能快速搭建的Deep Agents

目录

一、什么是 DeepAgent？

核心设计理念

二、环境准备与安装

2.1 前置条件

2.2 安装依赖

2.3 配置环境变量

三、快速开始：你的第一个 DeepAgent

3.1 基础示例

3.2 DeepAgent 工作原理

四、内置工具详解

4.1 任务管理工具

4.2 文件系统工具（7个）

4.3 子代理工具

五、子代理系统

5.1 为什么需要子代理？

5.2 创建子代理

5.3 SubAgent 类型规范

六、中间件系统

6.1 FilesystemMiddleware

6.2 SubAgentMiddleware

七、后端系统

7.1 后端架构

7.2 自定义后端策略

八、人机协作

8.1 配置中断点

8.2 子代理级别的中断配置

九、完整 API 参考

9.1 create_deep_agent 函数签名

9.2 参数说明

十、Deep Research 能力实现机制

10.1 自动规划与任务分解

10.2 上下文管理

10.3 子代理委派与上下文隔离

10.4 长期记忆与持久化存储

10.5 Deep Research 完整工作流程

10.6 关键设计模式总结

十一、总结