Deep Agents 概述

Deep Agents 是开始构建由大语言模型驱动的智能体和应用程序的最简单方式——它内置了用于上下文管理的文件系统能力、生成子智能体以及长期记忆功能。当您的用例需要时，可以选择性地扩展诸如任务规划和技能等能力。您可以将 Deep Agents 用于任何任务，包括复杂的、多步骤的任务。 Deep Agents 具备以下能力：

在环境中执行操作：通过工具执行操作、读写文件、执行代码
连接您的数据：在合适的时机加载记忆、技能和领域知识
管理不断增长的上下文：在长时间运行中，对历史记录进行摘要并卸载大型结果
并行化任务：委托给在隔离的上下文窗口中运行的通用或专门子智能体
保持在环路中：在关键决策点暂停以等待人工批准
随时间改进：基于实际使用情况更新记忆、技能和提示词

每个组件的完整分类，请参阅核心能力。

快速入门

from deepagents import create_deep_agent


def get_weather(city: str) -> str:
    """获取给定城市的天气。"""
    return f"It's always sunny in {city}!"


agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# 运行智能代理
agent.invoke(
    {"messages": [{"role": "user", "content": "旧金山的天气怎么样？"}]}
)

from deepagents import create_deep_agent


def get_weather(city: str) -> str:
    """获取给定城市的天气。"""
    return f"It's always sunny in {city}!"


agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# 运行智能代理
agent.invoke(
    {"messages": [{"role": "user", "content": "旧金山的天气怎么样？"}]}
)

from deepagents import create_deep_agent


def get_weather(city: str) -> str:
    """获取给定城市的天气。"""
    return f"It's always sunny in {city}!"


agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# 运行智能代理
agent.invoke(
    {"messages": [{"role": "user", "content": "旧金山的天气怎么样？"}]}
)

from deepagents import create_deep_agent


def get_weather(city: str) -> str:
    """获取给定城市的天气。"""
    return f"It's always sunny in {city}!"


agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# 运行智能代理
agent.invoke(
    {"messages": [{"role": "user", "content": "旧金山的天气怎么样？"}]}
)

from deepagents import create_deep_agent


def get_weather(city: str) -> str:
    """获取给定城市的天气。"""
    return f"It's always sunny in {city}!"


agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# 运行智能代理
agent.invoke(
    {"messages": [{"role": "user", "content": "旧金山的天气怎么样？"}]}
)

from deepagents import create_deep_agent


def get_weather(city: str) -> str:
    """获取给定城市的天气。"""
    return f"It's always sunny in {city}!"


agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# 运行智能代理
agent.invoke(
    {"messages": [{"role": "user", "content": "旧金山的天气怎么样？"}]}
)

from deepagents import create_deep_agent


def get_weather(city: str) -> str:
    """获取给定城市的天气。"""
    return f"It's always sunny in {city}!"


agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# 运行智能代理
agent.invoke(
    {"messages": [{"role": "user", "content": "旧金山的天气怎么样？"}]}
)

请参阅快速入门指南和自定义指南，开始使用 Deep Agents 构建您自己的智能体和应用程序。

使用 LangSmith 追踪请求、调试智能体行为并评估输出。请按照可观测性快速入门进行设置。当准备投入生产时，请参阅投入生产了解 LangSmith 部署选项。

核心能力

Deep Agents 是一个”智能体脚手架”。它与其他智能体框架的核心工具调用循环相同，但内置了使智能体在真实任务中可靠的特定能力：

执行环境

工具、虚拟文件系统、可选沙盒和 REPL（解释器）

上下文管理

技能、记忆、摘要、上下文卸载和提示词缓存

委托

子智能体生成和可选的任务规划

引导

人在环路的批准和中断

deepagents 是一个独立的库，构建在 LangChain 用于智能体的核心构建块之上。它使用 LangGraph 运行时来实现持久执行、流式传输、人在环路等功能。 LangChain 是为您的智能体提供核心构建块的框架。要了解 LangChain、LangGraph 和 Deep Agents 之间的区别，请参阅框架、运行时和脚手架。与 Anthropic 的脚手架进行并排比较，请参阅Deep Agents 与 Claude Agent SDK 对比。对于构建不包含这些内置能力的自定义智能体，请考虑使用 LangChain 的 create_agent 或构建自定义 LangGraph 工作流。

执行环境

执行环境是智能体发挥作用的地方。它包含四个层次：

工具：智能体可以调用的自定义函数、API 和数据库
虚拟文件系统：由可插拔后端支持的文件工具
文件系统权限：声明式访问控制，规定智能体可以读取或写入哪些路径
代码执行：沙盒化的 Shell 执行和进程内 JavaScript 解释器

流式传输 让您能够通过类型化的事件流（用于消息、工具、值和委托任务）跟踪所有正在发生的事情。

工具与 MCP

通过 tools= 参数传递自定义函数、LangChain 工具或来自任何 MCP 服务器的工具。Deep Agents 完全支持模型上下文协议 (MCP)，让您可以通过标准接口连接到数据库、API、文件系统等。

from deepagents import create_deep_agent

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

有关定义自定义工具、使用 MCP 服务器以及内置脚手架工具的完整列表的更多信息，请参阅工具。

虚拟文件系统访问

脚手架提供了一个可配置的虚拟文件系统，该系统可以由不同的可插拔后端支持：内存状态、本地磁盘、LangGraph 存储、复合路由，或带有用于读写访问的权限规则的自定义后端。后端支持以下文件系统操作：

工具	描述
`ls`	列出目录中的文件及其元数据（大小、修改时间）
`read_file`	读取文件内容并显示行号，支持对大文件使用偏移/限制。也支持为非文本文件（图像、视频、音频和文档）返回多模态内容块。支持的扩展名见下文。
`write_file`	创建新文件，或覆盖现有文件
`edit_file`	在文件中执行精确的字符串替换（带有全局替换模式）
`delete`	删除文件，或递归删除目录及其内容
`glob`	查找匹配模式的文件（例如 `*/.py`）
`grep`	搜索文件内容，支持多种输出模式（仅文件名、带上下文的内容或计数）
`execute`	在环境中运行 Shell 命令（仅在使用沙盒后端时可用）

delete 工具需要 deepagents>=0.7。不支持删除操作的后端会自动对该模型隐藏该工具。

支持的多模态文件扩展名

类型	扩展名
图像	`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.heic`, `.heif`
视频	`.mp4`, `.mpeg`, `.mov`, `.avi`, `.flv`, `.mpg`, `.webm`, `.wmv`, `.3gpp`
音频	`.wav`, `.mp3`, `.aiff`, `.aac`, `.ogg`, `.flac`
文件	`.pdf`, `.ppt`, `.pptx`

在没有默认文件系统工具的情况下运行

要向模型隐藏上面列出的文件系统工具，请注册一个带有 excluded_tools 的脚手架配置文件：

from deepagents import HarnessProfile, register_harness_profile

register_harness_profile(
    "anthropic:claude-sonnet-4-6",
    HarnessProfile(
        excluded_tools=frozenset(
            {"ls", "read_file", "write_file", "edit_file", "delete", "glob", "grep"}
        ),
    ),
)

通过 excluded_middleware 移除 FilesystemMiddleware 本身会被有意拒绝——它是默认中间件栈中必需的脚手架。使用 excluded_tools 仅隐藏模型可见的工具表面，并保留中间件。要移除 task 工具，请参阅在没有子智能体的情况下运行。

限制文件系统工具

FilesystemMiddleware 上的 tools 白名单需要 deepagents>=0.7。

要仅暴露上面列出的部分文件系统工具，而不是隐藏全部，可以向 FilesystemMiddleware 传递一个 tools 白名单，并通过 middleware= 提供该实例。任何未包含在列表中的内置文件系统工具都将从模型的工具列表中移除。

from deepagents import create_deep_agent
from deepagents.middleware import FilesystemMiddleware

# 只读智能体：write_file, edit_file, delete 和 execute 永远不会显示
agent = create_deep_agent(
    model="claude-sonnet-4-6",
    middleware=[
        FilesystemMiddleware(backend=backend, tools=["read_file", "ls", "glob", "grep"]),
    ],
)

read_file 必须始终包含在列表中——省略它会在创建智能体时引发 ValueError。当配置的后端不支持 execute 和 delete 工具时，无论您是否将它们包含在 tools 中，它们也会从工具表面移除。您通过 create_deep_agent 自身的 tools= 参数添加的自定义工具不受此白名单的影响。以这种方式传递您自己的 FilesystemMiddleware 实例会替换主智能体的默认实例，而通用子智能体会继承相同的限制。更多信息请参阅覆盖默认中间件实例。声明式子智能体不会继承它：需要在该子智能体自己的 middleware 字段中包含一个 FilesystemMiddleware(tools=...) 实例来独立限制它。

虚拟文件系统被脚手架的许多其他能力使用，例如技能、记忆、代码执行和上下文管理。您在为 Deep Agents 构建自定义工具和中间件时也可以使用文件系统。更多信息，请参阅后端。

文件系统权限

脚手架支持声明式权限规则，用于控制智能体可以读取或写入哪些文件和目录。权限适用于上面列出的内置文件系统工具，并按声明顺序进行评估，采用首次匹配生效的语义。通过在创建智能体时向 permissions= 传递一个规则列表来定义权限。每个规则包括：

operations："read" 和/或 "write"
paths：文件或目录的 glob 模式
mode："allow" 或 "deny"

规则从上到下进行评估，第一个匹配的规则生效。如果没有规则匹配，则操作被允许。此模型允许您将智能体限制在特定目录（例如 /workspace/），保护敏感文件（如 .env 或凭证），并为子智能体提供比父智能体更窄的访问权限。权限不适用于沙盒后端，后者支持通过 execute 工具执行任意命令。对于自定义验证逻辑，请使用后端策略钩子。有关完整的规则结构、示例和子智能体继承，请参阅权限。

代码执行

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

沙盒后端提供一个 execute 工具，用于在隔离环境中执行 Shell 命令。
解释器添加一个 eval 工具，在作用域化的 QuickJS 运行时中运行 JavaScript。

当智能体需要安装依赖、运行测试、调用 CLI 或处理操作系统文件系统时，请使用沙盒后端。沙盒后端实现了 SandboxBackendProtocolV2；当检测到时，脚手架会将 execute 工具添加到智能体的可用工具中。当智能体需要一个轻量级的可编程层来执行循环、批量处理、确定性数据转换或程序化工具调用时，请使用解释器。解释器不提供 Shell 访问、包安装或文件系统与网络访问。有关沙盒设置、提供程序和文件传输 API，请参阅沙盒。有关 QuickJS 运行时和程序化工具调用，请参阅解释器。

流式传输

事件流将智能体运行暴露为针对消息、工具调用、值和输出的类型化投影。Deep Agents 添加了 stream.subagents，因此每个委托的任务都会获得自己的句柄，该句柄具有独立的消息流、工具调用流和嵌套的子智能体流。

上下文管理

上下文管理组件控制智能体知道什么、它能在令牌限制内运行多久，以及它在会话之间保留什么。它包含四个层次：

技能：根据需要从技能文件中渐进加载的领域知识
记忆：在启动时从 AGENTS.md 文件加载的持久指令和偏好
摘要和上下文卸载：对话历史和大型工具结果的自动压缩
提示词缓存：静态提示词部分可被缓存，以在支持的模型上加速推理并降低成本

技能

技能为您的 Deep Agent 打包专门的工作流、领域知识和自定义指令。每个技能都遵循 Agent Skills 标准，并驻留在包含 SKILL.md 文件的目录中。技能还可以包括脚本、模板、参考文档和其他支持资源。 Deep Agents 以渐进式披露的方式加载技能：智能体在启动时读取 SKILL.md 的 frontmatter，然后仅在任务需要时才读取完整的技能内容。这使启动时的上下文保持紧凑，同时仍能按需提供丰富的能力。更多信息，请参阅技能。

记忆

记忆为您的 Deep Agent 提供跨对话的持久上下文，例如编码风格、偏好、惯例和项目指南。记忆使用您在创建智能体时通过 memory 参数传递的 AGENTS.md 文件。与技能不同，记忆文件始终被加载，其内容存储在配置的后端（StateBackend、StoreBackend 或 FilesystemBackend）中。智能体还可以根据交互和反馈更新记忆，因此偏好和模式可以延续下去，而无需在每个线程中重复说明。有关配置详情和示例，请参阅记忆。

摘要和上下文卸载

脚手架管理上下文，以便 Deep Agents 能够在令牌限制内处理长时间运行的工作，同时将最相关的信息保持在范围内。此上下文流程包含四个部分：

输入上下文：系统提示词、记忆、技能和工具提示词定义了智能体的起点。
压缩：内置的卸载和摘要功能压缩对话历史和大型中间结果。
隔离：子智能体将繁重的子任务隔离开，并仅返回最终结果（参见委托）。
长期记忆：虚拟文件系统中的持久存储跨线程携带信息。

这些机制共同支持那些超出单个上下文窗口的多步骤任务，同时减少手动上下文修剪和令牌使用。有关配置详情，请参阅上下文工程。有关多模态输入和工具输出，请参阅多模态。

提示词缓存

对于 Anthropic 和 Amazon Bedrock 模型，create_deep_agent 会自动将提示词缓存应用于系统提示词的静态部分——即每轮都会重复的基础智能体指令、记忆和技能内容。这避免了跨调用重复处理相同的令牌，从而减少了长时间运行的智能体的延迟和成本。当使用 Anthropic 模型或 Bedrock 模型（Claude 或 Nova）时，默认启用提示词缓存。无需配置。对于其他提供商，请参阅中间件集成了解可用的特定于提供商的缓存中间件。

委托

委托组件使智能体能够将大问题分解为更小、可并行化的工作单元。它包含两个层次：

任务规划：一个可选的 write_todos 工具，用于结构化任务跟踪
子智能体：处理隔离子任务的临时子智能体

任务规划

任务规划是脚手架的一个可选能力，允许智能体在执行期间维护结构化的任务列表。从 v0.7 开始，任务规划是纯可选的。在早期版本中，任务规划中间件默认包含在内。规划通常适用于以下情况：

冗长或复杂的多步骤任务
能力较弱的模型，受益于一个明确的问责工具
从智能体状态流式传输进度的用户界面（参见待办事项列表）

向 middleware 参数传递 TodoListMiddleware，可为智能体提供一个 write_todos 工具，用于在执行期间维护结构化的任务列表。

from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware

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

from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="openai:gpt-5.5",
    middleware=[TodoListMiddleware()],
)

from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    middleware=[TodoListMiddleware()],
)

from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    middleware=[TodoListMiddleware()],
)

from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    middleware=[TodoListMiddleware()],
)

from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    middleware=[TodoListMiddleware()],
)

from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    middleware=[TodoListMiddleware()],
)

任务支持状态跟踪（'pending'、'in_progress'、'completed'），并持久化在智能体状态中。这为智能体提供了一个轻量级的规划层，用于组织长时间运行和多步骤的工作。有关配置选项和行为详情，请参阅待办事项列表。

子智能体

脚手架包含一个内置的 task 工具，允许主智能体创建临时的子智能体，用于处理隔离的、长时间运行的、多步骤的或并行的任务。子智能体执行提供：

全新的上下文：每次调用都会创建一个新的智能体实例，具有自己的上下文。
自主执行：子智能体独立运行直到完成。
单次交接：它向主智能体返回一个最终报告。
可配置策略：使用默认的 general-purpose 子智能体（默认启用）或定义自定义子智能体。
无状态消息传递：子智能体是无状态的，不能发送多条消息回来。
上下文和令牌效率：繁重的子任务工作被隔离，并被压缩成一个紧凑的结果。

在没有子智能体的情况下运行（无 `task` 工具）

要运行一个没有 task 工具的智能体，请参阅在没有子智能体的情况下运行。不要尝试通过 excluded_middleware 移除 SubAgentMiddleware——这会被有意拒绝。相反，通过脚手架配置文件禁用自动添加的子智能体，并且不通过 subagents= 传递同步子智能体。异步子智能体不受影响。完整的排序请参阅默认中间件栈。

更多信息，请参阅子智能体。

引导

引导组件让人类在运行时控制智能体的行为，并为智能体的工作设置文件系统权限。

人在环路

Deep Agents 与 LangGraph 中断集成，因此您可以在敏感的工具调用处暂停以获取批准。在 create_deep_agent 中使用 interrupt_on 参数启用此行为。 interrupt_on 接受一个工具名称到中断配置的映射。例如，interrupt_on={"edit_file": True} 会在每次编辑前暂停，让您可以在执行前批准调用、添加指导或修改工具输入。这为您在处理破坏性操作、昂贵的 API 调用和交互式调试时，提供了一个运行时的安全和控制层。更多信息，请参阅人在环路。

入门指南

快速入门

构建您的第一个 Deep Agent

自定义

了解自定义选项

代码

使用 Deep Agents Code

ACP

在代码编辑器中通过 ACP 使用 Deep Agents

参考文档

查看 deepagents API 参考文档

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Deployment

Execution environment

Context management

Delegation

Steering

Frontend

Protocols

快速入门

核心能力

执行环境

上下文管理

委托

引导

执行环境

工具与 MCP

虚拟文件系统访问

文件系统权限

代码执行

流式传输

上下文管理

技能

记忆

摘要和上下文卸载

提示词缓存

委托

任务规划

子智能体

引导

人在环路

入门指南

快速入门

自定义

代码

ACP

参考文档

​快速入门

​核心能力

执行环境

上下文管理

委托

引导

​执行环境

​工具与 MCP

​虚拟文件系统访问

​文件系统权限

​代码执行

​流式传输

​上下文管理

​技能

​记忆

​摘要和上下文卸载

​提示词缓存

​委托

​任务规划

​子智能体

​引导

​人在环路

​入门指南

快速入门

自定义

代码

ACP

参考文档

快速入门

核心能力

执行环境

工具与 MCP

虚拟文件系统访问

文件系统权限

代码执行

流式传输

上下文管理

技能

记忆

摘要和上下文卸载

提示词缓存

委托

任务规划

子智能体

引导

人在环路

入门指南