Deep Agents 框架：从入门到精通

HaiXCoder
1 阅读17分钟

一句话定义：Deep Agents 是 LangChain 团队开源的 Agent Harness（智能体脚手架），基于 LangChain + LangGraph 构建，开箱即用地提供规划、文件系统、子智能体、长期记忆等高级能力，专为复杂多步骤任务设计。

目录

一、Deep Agents 是什么

Deep Agents 是一款开箱即用的 LLM 智能体开发库，由 LangChain 团队于 2026 年初开源（MIT 协议）。

灵感来源：Claude Code、Deep Research、Manus 等产品的通用化抽象。

核心定位：

维度说明
性质Agent Harness（智能体脚手架）
底层依赖LangGraph（执行引擎）+ LangChain（组件库）
核心理念保留工具调用循环，内置规划/文件/子智能体/记忆
目标用户需要处理复杂、长运行任务的开发者
许可证MIT（100% 开源）

与普通 Agent 框架的本质区别：普通框架给你积木让你自己搭，Deep Agents 直接给你一辆配置齐全的越野车——你只需告诉它去哪，它自己会规划路线、加油、绕路。

二、核心架构与技术定位

2.1 LangChain 生态金字塔

┌─────────────────────────────────┐
│         Deep Agents             │  ← Agent Harness（开箱即用）
│   规划 / 文件系统 / 子智能体     │
├─────────────────────────────────┤
│         LangChain               │  ← 应用框架（组件 + 高级 API）
│   PromptTemplate / Tools / RAG  │
├─────────────────────────────────┤
│         LangGraph               │  ← 运行时引擎（图编排）
│   State / Graph / Checkpointer  │
└─────────────────────────────────┘
  • LangGraph：发动机——负责真正执行流程
  • LangChain：方向盘和仪表盘——提供丰富组件
  • Deep Agents：整车——开箱即用，自动规划路线

2.2 Deep Agents 内置能力一览

能力对应工具说明
任务规划write_todos自动拆解任务为 Todo List，动态调整
文件操作ls / read_file / write_file / edit_file虚拟文件系统，管理上下文
子智能体task派发子任务，上下文隔离
Shell 执行execute运行命令（支持沙箱）
上下文压缩自动摘要对话过长时自动压缩
长期记忆LangGraph Store跨线程持久化

三、环境准备与安装

3.1 系统要求

  • Python >= 3.11
  • 支持工具调用的 LLM（OpenAI、Anthropic 等）

3.2 安装

# 方式一：pip
pip install deepagents

# 方式二：uv（推荐）
uv add deepagents

# 可选：安装搜索工具
pip install tavily-python

3.3 API Key 配置

# 选择你的模型提供商
export ANTHROPIC_API_KEY="your-api-key"
# 或
export OPENAI_API_KEY="your-api-key"

四、快速入门：5 分钟构建第一个 Deep Agent

4.1 最简示例（零配置）

from deepagents import create_deep_agent

agent = create_deep_agent()

result = agent.invoke({
    "messages": [{"role": "user", "content": "研究 LangGraph 并写一份总结"}]
})

print(result["messages"][-1].content)

仅此一行 create_deep_agent()，你就获得了一个具备规划、文件管理、子智能体派发能力的完整 Agent。

4.2 带自定义工具的示例

from deepagents import create_deep_agent

# 定义一个简单的自定义工具
def get_weather(city: str) -> str:
    """获取指定城市的天气信息"""
    return f"{city} 今天天气晴朗，气温 25°C。"

# 创建带工具的智能体
agent = create_deep_agent(
    tools=[get_weather],
    system_prompt="你是一个友好的助手，擅长天气查询。"
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "北京天气怎么样？"}]
})

4.3 研究助手（完整示例）

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

# 1. 初始化搜索客户端
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

# 2. 定义搜索工具
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,
    )

# 3. 定义系统提示词
research_instructions = """你是一位专业研究员。你的工作是进行深入研究并撰写高质量报告。

你可以使用互联网搜索工具作为主要信息来源。

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

# 4. 创建研究智能体
agent = create_deep_agent(
    tools=[internet_search],
    system_prompt=research_instructions
)

# 5. 执行任务
result = agent.invoke({
    "messages": [{"role": "user", "content": "什么是 LangGraph？它解决了什么问题？"}]
})

print(result["messages"][-1].content)

执行过程中，Agent 自动完成了：

  1. 使用 write_todos 规划研究步骤
  2. 调用 internet_search 搜索信息
  3. 使用 write_file 将搜索结果保存到虚拟文件系统
  4. 使用 read_file 回顾已保存的信息
  5. 综合分析，生成最终报告

五、核心能力详解

5.1 任务规划与拆解

内置 write_todos 工具，Agent 可以自动将复杂任务分解为可执行的步骤列表。

工作原理：

用户请求："帮我分析三家公司的财报"
    ↓
Agent 调用 write_todos:
    ☐ 收集公司 A 的财报数据
    ☐ 收集公司 B 的财报数据
    ☐ 收集公司 C 的财报数据
    ☐ 对比分析三家公司
    ☐ 撰写总结报告
    ↓
逐步执行，动态更新进度

底层实现：由 TodoListMiddleware 提供，可自定义规划指令：

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

agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    middleware=[
        TodoListMiddleware(
            system_prompt="在处理复杂任务前，先用 write_todos 制定计划..."
        ),
    ],
)

5.2 上下文管理（文件系统）

这是 Deep Agents 的杀手级特性。传统 Agent 的致命问题是上下文窗口溢出——工具返回结果太长，很快就把 token 用完了。

Deep Agents 的解决方案：内置虚拟文件系统，Agent 可以把中间结果"卸载"到文件中。

# Agent 内部自动执行的操作流程：
# 1. 调用搜索工具 → 返回大量结果
# 2. 使用 write_file 将结果保存到文件
# 3. 后续需要时用 read_file 读取
# 4. 主上下文保持干净

可用工具：

工具功能
ls列出文件系统中的文件
read_file读取文件内容（支持指定行数）
write_file写入新文件
edit_file编辑已有文件

底层实现：由 FilesystemMiddleware 提供。

5.3 子智能体派发

通过 task 工具，主 Agent 可以动态生成子智能体来处理专项任务。

为什么需要子智能体？

  • 上下文隔离：子智能体有独立的上下文窗口，不会污染主 Agent
  • 并行执行：多个子任务可以同时进行
  • 专注深度：子智能体可以深入处理特定领域任务

配置子智能体：

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} 天气晴朗，25°C"

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": [],
                }
            ],
        )
    ],
)

使用预构建的 LangGraph 图作为子智能体：

from deepagents import CompiledSubAgent
from langgraph.graph import StateGraph

# 创建自定义 LangGraph 图
def create_weather_graph():
    workflow = StateGraph(...)
    # 构建你的自定义图
    return workflow.compile()

weather_graph = create_weather_graph()

# 包装为 CompiledSubAgent
weather_subagent = CompiledSubAgent(
    name="weather",
    description="查询城市天气的子智能体",
    runnable=weather_graph
)

agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    middleware=[
        SubAgentMiddleware(
            default_model="claude-sonnet-4-5-20250929",
            default_tools=[],
            subagents=[weather_subagent],
        )
    ],
)

注意：除了用户定义的子智能体外，主 Agent 始终可以访问一个 general-purpose（通用）子智能体，它拥有与主 Agent 相同的指令和工具，主要用于上下文隔离。

5.4 长期记忆

依托 LangGraph Store 实现跨线程、跨会话的持久记忆。

from langchain.agents import create_agent
from deepagents.middleware import FilesystemMiddleware
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    store=store,
    middleware=[
        FilesystemMiddleware(
            backend=lambda rt: CompositeBackend(
                default=StateBackend(rt),
                routes={"/memories/": StoreBackend(rt)}
            ),
        ),
    ],
)

工作原理：

  • 默认路径 → StateBackend（短期，随线程消亡）
  • /memories/ 路径 → StoreBackend（长期，跨线程持久化）

Agent 可以将重要信息写入 /memories/ 目录，下次对话时自动读取。

5.5 Shell 执行与沙箱

内置 execute 工具，Agent 可以运行 shell 命令。

安全模型：Deep Agents 采用"信任 LLM"模型——Agent 能做工具允许的任何事。安全边界应在工具/沙箱层面执行，而非期望模型自律。

支持的沙箱环境：

  • Modal
  • Daytona
  • Denno
  • 本地磁盘（开发用）

六、自定义配置进阶

6.1 自定义模型

默认使用 claude-sonnet-4-5-20250929，支持任意支持工具调用的 LLM：

from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

# 方式一：字符串指定
agent = create_deep_agent(model="gpt-4o")

# 方式二：LangChain 模型对象
model = init_chat_model(model="gpt-5")
agent = create_deep_agent(model=model)

6.2 自定义系统提示词

Deep Agents 内置了一套受 Claude Code 启发的系统提示词，包含规划、文件系统、子智能体的使用指令。你可以在此基础上追加：

from deepagents import create_deep_agent

agent = create_deep_agent(
    system_prompt="""你是一位资深数据分析师。
    你的工作流程：
    1. 先理解数据需求
    2. 制定分析计划
    3. 逐步执行分析
    4. 输出可视化报告
    """
)

6.3 自定义工具

from langchain.tools import tool
from deepagents import create_deep_agent

@tool
def query_database(sql: str) -> str:
    """执行 SQL 查询并返回结果"""
    # 你的数据库查询逻辑
    return f"查询结果: {sql}"

@tool
def send_email(to: str, subject: str, body: str) -> str:
    """发送邮件"""
    # 你的邮件发送逻辑
    return f"邮件已发送至 {to}"

agent = create_deep_agent(
    tools=[query_database, send_email],
    system_prompt="你是一个数据分析师，可以查询数据库并发送报告邮件。"
)

6.4 中间件架构

Deep Agents 采用模块化中间件架构，三大核心中间件可独立使用或自由组合：

create_deep_agent()
    ├── TodoListMiddleware    → 规划能力
    ├── FilesystemMiddleware  → 文件系统
    └── SubAgentMiddleware    → 子智能体

单独使用中间件：

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

# 只启用文件系统中间件
agent = create_agent(
    model="claude-sonnet-4-5-20250929",
    middleware=[FilesystemMiddleware()],
)

6.5 可插拔文件系统后端

虚拟文件系统支持灵活切换存储后端：

后端说明适用场景
StateBackend内存状态（默认）单次对话，临时数据
LocalBackend本地磁盘开发调试
StoreBackendLangGraph Store跨线程持久化
CompositeBackend组合路由混合存储策略
自定义后端实现 Backend 接口特殊需求
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

# /memories/ 路径走持久化存储，其他走内存
backend = CompositeBackend(
    default=StateBackend(rt),
    routes={
        "/memories/": StoreBackend(rt),
        "/outputs/": LocalBackend(path="/data/outputs"),
    }
)

七、Deep Agents CLI

Deep Agents 还提供了一个命令行编码智能体，类似 Claude Code 或 Cursor Agent：

# 安装 CLI
curl -LsSf https://raw.githubusercontent.com/langchain-ai/deepagents/main/libs/cli/scripts/install.sh | bash

# 交互式使用
deepagents

# 非交互式（CI/脚本）
deepagents --headless "分析这个项目的代码结构"

CLI 亮点：

  • 交互式 TUI（终端界面）
  • Web 搜索能力
  • Headless 模式（脚本/CI 集成）
  • 远程沙箱执行
  • 持久记忆
  • 自定义 Skills
  • Human-in-the-loop 审批

八、与 LangChain、LangGraph 的深度对比

8.1 三者关系全景图

                    抽象层级
                       ↑
    ┌──────────────────┼──────────────────┐
    │                  │                  │
    │  Deep Agents     │  LangChain       │  LangGraph
    │  (Agent Harness) │  (Framework)     │  (Runtime)
    │                  │                  │
    ├──────────────────┼──────────────────┤
    │ 一行代码创建     │ 组件 + 高级 API  │ 图编排引擎     │
    │ 完整智能体       │ 快速组装应用     │ 精细控制流程   │
    │                  │                  │
    │ 内置规划/文件/   │ Prompt/Tools/    │ State/Node/    │
    │ 子智能体/记忆    │ Memory/RAG       │ Edge/Checkpoint│
    │                  │                  │
    │ 返回编译后的     │ create_agent     │ StateGraph     │
    │ LangGraph 图     │ 底层也是图       │ 原始图构建     │
    └──────────────────┴──────────────────┘

关键认知：三者不是竞争关系，而是同一生态的三个抽象层级。create_deep_agent() 返回的就是编译后的 LangGraph 图。

8.2 核心差异对比表

维度LangGraphLangChainDeep Agents
定位运行时引擎应用框架Agent Harness
抽象层级最低中等最高
上手难度⭐⭐⭐⭐⭐⭐⭐
控制力⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
内置规划❌ 需自己实现❌ 需自己实现✅ write_todos
内置文件系统❌❌✅ ls/read/write/edit
内置子智能体需手动编排简单支持✅ task 工具
上下文管理手动手动✅ 自动压缩+文件卸载
长期记忆需配置 Store需配置✅ 开箱即用
Shell 执行需自己加工具需自己加工具✅ execute 工具
流式输出✅ 原生✅✅ 继承 LangGraph
状态持久化✅ Checkpointer✅ 通过 LangGraph✅ 继承 LangGraph
Human-in-the-loop✅ 原生 interrupt✅ 通过 LangGraph✅ 继承 LangGraph
LangSmith 集成✅✅✅ 原生支持
适用场景高度自定义工作流快速原型/RAG/聊天复杂多步骤长时任务
代码量多（需组装节点和边）中等少（一行创建）

8.3 同一任务的三种实现对比

任务：搜索某个话题，整理信息，生成报告。

方案 A：LangGraph（底层图编排）

from langgraph.graph import StateGraph, START, END
from langgraph.prebuilt import ToolNode
from langchain.chat_models import init_chat_model
from langchain_core.tools import tool

@tool
def search(query: str) -> str:
    """搜索信息"""
    return f"搜索结果: {query} 的相关信息..."

@tool
def write_report(content: str) -> str:
    """写入报告"""
    return "报告已保存。"

# 定义状态
class AgentState(TypedDict):
    messages: Annotated[list, add_messages]
    plan: list[str]
    search_results: list[str]

# 定义节点
def planner(state: AgentState):
    model = init_chat_model("claude-sonnet-4-5-20250929")
    response = model.invoke([
        {"role": "system", "content": "制定研究计划，输出步骤列表。"},
        *state["messages"]
    ])
    return {"plan": response.content.split("\n")}

def researcher(state: AgentState):
    model = init_chat_model("claude-sonnet-4-5-20250929").bind_tools([search])
    response = model.invoke(state["messages"])
    return {"messages": [response]}

def writer(state: AgentState):
    model = init_chat_model("claude-sonnet-4-5-20250929").bind_tools([write_report])
    response = model.invoke(state["messages"])
    return {"messages": [response]}

# 构建图
workflow = StateGraph(AgentState)
workflow.add_node("planner", planner)
workflow.add_node("researcher", researcher)
workflow.add_node("writer", writer)
workflow.add_node("tools", ToolNode([search, write_report]))

workflow.add_edge(START, "planner")
workflow.add_edge("planner", "researcher")
workflow.add_conditional_edges("researcher", tools_condition)
workflow.add_edge("tools", "researcher")
# ... 还需要定义何时从 researcher 转到 writer
workflow.add_conditional_edges("researcher", should_write)
workflow.add_conditional_edges("writer", tools_condition)
workflow.add_edge("tools", "writer")
workflow.add_conditional_edges("writer", should_end, {True: END, False: "writer"})

app = workflow.compile()

# 执行
result = app.invoke({"messages": [{"role": "user", "content": "研究 AI Agent 趋势"}]})

评价：完全控制，但代码量大，需要手动管理状态流转、工具调用循环、条件分支。

方案 B：LangChain（create_agent）

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain_core.tools import tool

@tool
def search(query: str) -> str:
    """搜索信息"""
    return f"搜索结果: {query} 的相关信息..."

@tool
def write_report(content: str) -> str:
    """写入报告"""
    return "报告已保存。"

model = init_chat_model("claude-sonnet-4-5-20250929")
agent = create_agent(
    model=model,
    tools=[search, write_report],
    prompt="你是一个研究员，搜索信息并撰写报告。"
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "研究 AI Agent 趋势"}]
})

评价：代码简洁，但缺乏规划能力、上下文管理。搜索结果多时容易 token 溢出，无法自动拆解复杂任务。

方案 C：Deep Agents（create_deep_agent）

from deepagents import create_deep_agent
from langchain_core.tools import tool

@tool
def search(query: str) -> str:
    """搜索信息"""
    return f"搜索结果: {query} 的相关信息..."

agent = create_deep_agent(
    tools=[search],
    system_prompt="你是一位专业研究员，搜索信息并撰写高质量报告。"
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "研究 AI Agent 趋势"}]
})

评价：代码最简洁，自动规划步骤、自动管理上下文（搜索结果存文件）、可派生子智能体深入子课题。同样的任务，Deep Agents 版本的 Agent 行为更像一个有经验的人类研究员。

三种方案对比总结

维度LangGraphLangChainDeep Agents
代码行数~50 行~15 行~8 行
规划能力需手动实现❌✅ 自动
上下文管理需手动实现❌✅ 自动
子任务派发需手动编排❌✅ 自动
灵活度最高中等中等
适合复杂度任意简单-中等中等-复杂

8.4 选型决策指南

你的任务是什么？
│
├── 简单工具调用 / RAG / 聊天机器人
│   └── → LangChain create_agent ✅
│
├── 需要精细控制流程 / 条件分支 / Multi-Agent 协作
│   └── → LangGraph StateGraph ✅
│
├── 复杂多步骤任务 / 需要规划 / 上下文很长
│   └── → Deep Agents create_deep_agent ✅
│
└── 极致自定义 + 高级能力
    └── → LangGraph 底层 + Deep Agents 中间件组合 ✅

一句话选型：

  • 想最快出结果 → LangChain
  • 想完全掌控 → LangGraph
  • 想处理复杂任务 → Deep Agents
  • 想兼顾掌控力和高级能力 → LangGraph + Deep Agents 中间件

九、实战案例：构建研究助手

以下是一个完整的研究助手实现，展示 Deep Agents 的核心能力：

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from deepagents.middleware import FilesystemMiddleware
from langgraph.store.memory import InMemoryStore

# ========== 1. 配置 ==========

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

# ========== 2. 工具定义 ==========

def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
) -> str:
    """在互联网上搜索信息"""
    results = tavily_client.search(
        query=query,
        max_results=max_results,
        topic=topic,
    )
    formatted = []
    for r in results["results"]:
        formatted.append(f"- {r['title']}: {r['content']}")
    return "\n".join(formatted)

# ========== 3. 创建 Agent ==========

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[internet_search],
    system_prompt="""你是一位资深行业研究员。

## 工作流程
1. 使用 write_todos 制定研究计划
2. 逐步搜索和收集信息
3. 将重要信息保存到文件系统
4. 综合分析并撰写报告
5. 将最终报告保存为文件

## 输出要求
- 报告结构清晰，包含摘要、正文、结论
- 引用信息来源
- 数据要有据可查
""",
    store=store,
    middleware=[
        FilesystemMiddleware(
            backend=lambda rt: CompositeBackend(
                default=StateBackend(rt),
                routes={"/memories/": StoreBackend(rt)}
            ),
        ),
    ],
)

# ========== 4. 执行研究任务 ==========

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "研究 2026 年 AI Agent 框架的发展趋势，包括主要玩家、技术方向和市场预测。"
    }]
})

print(result["messages"][-1].content)

这个 Agent 会自动：

  1. 制定研究计划（write_todos）
  2. 分步搜索不同维度的信息
  3. 将搜索结果保存到文件（write_file）
  4. 回顾已收集信息（read_file）
  5. 综合分析生成报告
  6. 将重要发现存入长期记忆（/memories/）

十、生产部署与可观测性

10.1 LangSmith 追踪

export LANGSMITH_TRACING="true"
export LANGSMITH_API_KEY="your-api-key"

Deep Agents 原生支持 LangSmith 追踪，可可视化观测：

  • 每一步工具调用
  • 子智能体的执行过程
  • 上下文管理操作
  • Token 消耗

10.2 流式输出

for event in agent.stream({
    "messages": [{"role": "user", "content": "研究 AI 趋势"}]
}):
    print(event)

10.3 部署

Deep Agents 应用可通过 LangSmith Deployment 部署到生产环境，支持：

  • API 服务
  • 自动扩缩容
  • 版本管理
  • A/B 测试

10.4 Human-in-the-loop

from deepagents import create_deep_agent

agent = create_deep_agent(interrupt_before=["execute"])
# 在执行 shell 命令前暂停，等待人工审批

十一、总结与学习路线

Deep Agents 的核心价值

价值说明
开发效率一行代码创建完整 Agent，从数天缩短到数分钟
任务处理能力内置规划+文件系统+子智能体，轻松应对复杂任务
上下文管理自动压缩+文件卸载，突破 token 窗口限制
生产就绪基于 LangGraph，继承流式、持久化、可观测等生产级特性
模型无关支持任何工具调用兼容的 LLM
完全开源MIT 协议，无供应商锁定

推荐学习路线

第 1 周：LangChain 基础
├── 组件概念（Prompt / Model / Tool / Memory）
├── LCEL 表达式
└── create_agent 快速上手

第 2-3 周：LangGraph 进阶
├── State / Node / Edge 概念
├── Checkpointer 持久化
├── 条件分支与循环
└── Human-in-the-loop

第 4 周：Deep Agents 上手
├── create_deep_agent 一行创建
├── 自定义工具和提示词
├── 中间件配置
└── 实战项目

持续深入：
├── 生产部署与监控
├── 自定义中间件开发
├── Multi-Agent 协作模式
└── 性能优化与成本控制

关键资源

最后的一句话：LangGraph 给你发动机，LangChain 给你方向盘和仪表盘，Deep Agents 直接给你一辆配置齐全、能自动规划路线的长途越野车。根据你的目的地选择合适的交通工具。

avatar
文章
阅读
粉丝