Deep Agent

什么是 Deep Agents复制标题链接

Deep Agents 是 LangChain 生态中一个"开箱即用"（batteries-included）的 Agent Harness（智能体框架），能够构建处理复杂多步骤任务的智能体，内置了任务规划、虚拟文件系统、子智能体（subagent）派发、长期记忆等能力。

核心定位：Agent = Model + Harness。Harness 是模型循环之外的一切——prompt、工具、中间件。

官方推荐新需求优先使用 Deep Agents，除非你需要完全自定义的 Agent（此时用 create_agent）或混合确定性/智能体工作流（此时用 LangGraph）。

在 LangChain 生态中的位置复制标题链接

各组件之间的关系复制标题链接

• LangGraph 是底层运行时，为上层提供持久化执行、流式处理等基础能力
• LangChain (create_agent) 在 LangGraph 之上构建 Tool Calling Harness
• Deep Agents 在 LangChain 之上构建，是最高层抽象，内置子智能体、文件系统等能力
• LangSmith 横向覆盖所有框架（虚线表示可观测，非依赖），提供追踪、调试、评估

核心能力总览复制标题链接

Deep Agents 提供六大内置能力：

快速入门复制标题链接

安装复制标题链接

pip install deepagents

最小示例复制标题链接

from deepagents import create_deep_agent


def get_weather(city: str) -> str:
    """获取指定城市的天气"""
    return f"{city} 现在晴天，25°C"


# 创建 Agent
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[get_weather],
    system_prompt="你是一个有用的助手",
)

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

model 参数使用 provider:model 格式，支持 Google、OpenAI、Anthropic、Ollama 等多种模型。

执行环境复制标题链接

执行环境是 Agent 执行操作的场所，包含四层：

工具与 MCP复制标题链接

通过 tools= 参数传入自定义函数、LangChain Tools 或任何 MCP Server 的工具。Deep Agents 完全支持 Model Context Protocol (MCP)。

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[search, fetch_page, run_query],
)

虚拟文件系统复制标题链接

Harness 提供可配置的虚拟文件系统，支持多种可插拔后端：

内置文件系统工具：

文件权限复制标题链接

支持声明式权限规则，控制 Agent 对文件/目录的读写访问：

from deepagents import create_deep_agent
from deepagents.permissions import FilesystemPermission

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    permissions=[
        # 允许读写工作区
        FilesystemPermission(operations=["read", "write"], paths=["/workspace/**"], mode="allow"),
        # 拒绝读写敏感文件
        FilesystemPermission(operations=["read", "write"], paths=[".env", "credentials/**"], mode="deny"),
    ],
)

规则从上到下求值，第一条匹配的规则生效（first-match-wins）。

代码执行复制标题链接

Deep Agents 支持两种代码执行方式：

流式输出复制标题链接

通过类型化事件流追踪 Agent 运行：

• stream.messages — 消息流
• stream.tool_calls — 工具调用流
• stream.values — 值流
• stream.subagents — 子智能体独立流

上下文管理复制标题链接

技能（Skills）复制标题链接

技能用于打包专用工作流、领域知识和自定义指令。每个技能遵循 Agent Skills 标准，存放在含 SKILL.md 文件的目录中。

Deep Agents 采用**"渐进式披露"**加载技能：启动时读取 SKILL.md 前置元数据，任务需要时才读取完整内容。

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    skills=["./skills/"],  # 技能目录路径
)

记忆（Memory）复制标题链接

记忆用于在对话间保持持久上下文——代码风格、偏好、约定、项目指南。

使用 AGENTS.md 文件，通过 memory= 参数传入：

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    memory=["./AGENTS.md"],
)

与技能（按需加载）不同，记忆文件在启动时始终加载，且 Agent 可根据交互更新记忆。

摘要与上下文卸载复制标题链接

Harness 管理上下文以支持长运行任务在 token 限内完成：

• 输入上下文：系统提示、记忆、技能、工具提示
• 压缩：自动卸载和摘要压缩对话历史和大型中间结果
• 隔离：子智能体隔离繁重子任务，仅返回最终结果
• 长期记忆：虚拟文件系统中的持久存储跨线程携带信息

提示缓存复制标题链接

对 Anthropic 和 Amazon Bedrock 模型，create_deep_agent 默认启用提示缓存——系统提示的静态部分（基础指令、记忆、技能）在每次重复调用时复用，降低延迟和成本。

委派（Delegation）复制标题链接

任务规划复制标题链接

内置 write_todos 工具，让 Agent 在执行过程中维护结构化任务列表。支持状态跟踪（pending、in_progress、completed），持久化在 Agent state 中。

子智能体（Subagents）复制标题链接

内置 task 工具让主 Agent 创建临时子智能体处理隔离的子任务：

• 全新上下文：每次调用创建新 Agent 实例，拥有独立上下文窗口
• 自主执行：子智能体独立运行直到完成
• 单次交接：向主 Agent 返回最终结果
• 可配置策略：使用默认 general-purpose 子智能体或自定义
• 状态化消息：子智能体是无状态的，不能发送多条消息回主 Agent

为什么使用子智能体复制标题链接

子智能体解决上下文膨胀问题。当工具返回大量输出（网页搜索、文件读取、数据库查询），子智能体隔离这些细节——主 Agent 只收到最终结果，而不是产生结果的所有中间工具调用。

适用场景：

• ✅ 多步骤任务会污染主 Agent 上下文
• ✅ 专用领域需要自定义指令或工具
• ✅ 任务需要不同模型能力
• ✅ 需要主 Agent 聚焦高层协调

不适用场景：

• ❌ 简单单步任务
• ❌ 需要维护中间上下文
• ❌ 开销大于收益时

自定义子智能体复制标题链接

from deepagents import create_deep_agent

research_subagent = {
    "name": "research-agent",
    "description": "用于深入调研问题",
    "system_prompt": "你是一个优秀的调研员",
    "tools": [internet_search],
    "model": "openai:gpt-5.5",  # 可选，覆盖默认模型
}

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    subagents=[research_subagent],
)

自定义子智能体字段：

CompiledSubAgent复制标题链接

对于复杂工作流，可使用预编译的 LangGraph 图作为子智能体：

from deepagents import create_deep_agent, CompiledSubAgent
from langchain.agents import create_agent

custom_graph = create_agent(
    model=your_model,
    tools=specialized_tools,
    prompt="专用数据分析师...",
)

custom_subagent = CompiledSubAgent(
    name="data-analyzer",
    description="专用复杂数据分析 Agent",
    runnable=custom_graph,
)

动态子智能体复制标题链接

当 Agent 同时拥有子智能体和解释器（Interpreter）时，可以从代码中调度子智能体——使用循环、分支和并行批处理将工作在多个项目上展开并综合结果。适用于：

• 批处理工作（审查目录中所有文件、分拣工单）
• 需要多角度分析
• 递归分析

人机协同（Human-in-the-Loop）复制标题链接

通过 interrupt_on 参数配置敏感操作前的人类审批：

from langchain.tools import tool
from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver


@tool
def remove_file(path: str) -> str:
    """删除文件"""
    return f"已删除 {path}"


@tool
def notify_email(to: str, subject: str, body: str) -> str:
    """发送邮件"""
    return f"已发送邮件给 {to}"


# 人机协同需要 checkpointer！
checkpointer = MemorySaver()

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[remove_file, notify_email],
    interrupt_on={
        "remove_file": True,  # 默认：批准、编辑、拒绝、回复
        "notify_email": {"allowed_decisions": ["approve", "reject"]},  # 禁止编辑
    },
    checkpointer=checkpointer,  # 必须！
)

interrupt_on 的值可以是：

• True — 启用中断，默认行为（approve/edit/reject/respond 全允许）
• False — 禁用中断
• InterruptOnConfig — 自定义配置，通过 allowed_decisions 控制审批选项

注意：人机协同必须配置 checkpointer，常用 MemorySaver（开发）或 SqliteSaver（生产）。

决策流程：

create_deep_agent 主要参数复制标题链接

默认中间件栈复制标题链接

Deep Agents 默认启用一组中间件，按顺序执行。常见中间件包括：

• FilesystemMiddleware — 文件系统操作和上下文
• SubAgentMiddleware — 子智能体调度（task 工具）
• SkillsMiddleware — 技能加载
• SummarizationMiddleware — 上下文压缩/摘要
• MemoryMiddleware — 记忆加载
• PatchToolCallsMiddleware — 工具调用修补
• HumanInTheLoopMiddleware — 人机协同（配置 interrupt_on 时添加）

可通过 excluded_middleware 排除不需要的中间件（注意：FilesystemMiddleware 和 SubAgentMiddleware 是必需的脚手架，不可通过此方式删除）。

与 LangGraph 的关系复制标题链接

Deep Agents 构建在 LangChain 核心构建块之上，使用 LangGraph 运行时实现：

• 持久化执行：通过 Checkpointer 保存/恢复状态
• 流式输出：实时追踪 Agent 执行
• 人机协同：通过 LangGraph Interrupt 实现
• 丰富生态：兼容所有 LangGraph Store/Checkpointer

因此 Deep Agents 是一个高层抽象——它在 LangGraph 之上提供了生产就绪的 Harness。

生产部署复制标题链接

对于生产环境，建议配合 LangSmith 进行：

• 请求追踪
• Agent 行为调试
• 输出评估

参见 Going to production。

相关资源复制标题链接

• Deep Agents 官方文档
• Deep Agents API Reference
• Deep Agents GitHub
• LangChain Agents 文档
• LangGraph 文档
• LangSmith 可观测性