Deep Agents 概述

构建能够进行规划、使用子智能体并利用文件系统来完成复杂任务的智能体

Deep Agents 是开始构建由 LLM 驱动的智能体和应用的最简单方式——内置了用于上下文管理的文件系统、子智能体派生和长期记忆等能力。 诸如 任务规划 和 技能 之类的可选能力会在你的用例需要时扩展 harness。 你可以将Deep Agents用于任何任务，包括复杂、多步骤的任务。

Deep Agents 具备以下能力：

• 在环境中采取行动：通过工具采取行动、读写文件、执行代码
• 连接你的数据：在恰当的时刻加载记忆、技能和领域知识
• 管理不断增长的上下文：在长时间运行中总结历史并卸载大型结果
• 并行处理任务：将任务委托给在隔离上下文窗口中运行的通用或专用子智能体
• 保持在回路中：在关键决策点暂停以等待人工批准
• 随时间改进：根据真实使用情况更新记忆、技能和提示词

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

::::

快速开始

Google

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    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",
)

# Run the agent
agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

OpenAI

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    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",
)

# Run the agent
agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

Anthropic

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

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

# Run the agent
agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

OpenRouter

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    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",
)

# Run the agent
agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

Fireworks

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    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",
)

# Run the agent
agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

Baseten

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    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",
)

# Run the agent
agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

Ollama

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    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",
)

# Run the agent
agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

•View example trace

打开本示例的一个公开 LangSmith 运行记录。

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

TIP

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

核心能力

Deep Agents 是一个 "智能体 harness"。它与其他智能体框架具有相同的核心工具调用循环，但内置了一些能力，使智能体在真实任务中更加可靠：

⚡Execution environment

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

•Context management

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

⊞Delegation

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

•Steering

人在回路批准和中断

deepagents 是一个独立库，构建在 LangChain 的智能体核心构建块之上。它使用 LangGraph 运行时来实现持久化执行、流式传输、人在回路等功能。

LangChain 是为你的智能体提供核心构建块的框架。 要详细了解 LangChain、LangGraph 和 Deep Agents 之间的区别，请参阅 框架、运行时与 harness。要与 Anthropic 的 harness 进行并排比较，请参阅 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 服务器以及内置 harness 工具完整列表的更多信息，请参阅 工具。

虚拟文件系统访问

harness 提供了一个可配置的虚拟文件系统，它可以由不同的 可插拔后端 支持：内存状态、本地磁盘、LangGraph store、组合路由，或带有读写访问 权限规则 的自定义后端。

这些后端支持以下文件系统操作：

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

NOTE

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 的 harness 配置文件：

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 本身会被有意拒绝——它是 Deep Agents 技术栈 中必需的脚手架。请使用 excluded_tools 仅隐藏模型可见的工具面，并保留中间件不变。要移除 task 工具，请参阅 在不使用子智能体的情况下运行。

限制文件系统工具

NOTE

FilesystemMiddleware 上的 tools 允许列表需要 deepagents>=0.7。

要仅暴露上面列出的文件系统工具的一个子集，而不是将它们全部隐藏，请向 FilesystemMiddleware 传入一个 tools 允许列表，并通过 middleware= 提供该实例。任何未列入该列表的内置文件系统工具都会从模型的工具列表中移除。

from deepagents import create_deep_agent
from deepagents.middleware import FilesystemMiddleware

# Read-only agent: write_file, edit_file, delete, and execute are never shown
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=...) 实例，以便独立地限制它。

虚拟文件系统被若干其他 harness 能力使用，例如技能、记忆、代码执行和上下文管理。 在构建 Deep Agents 的自定义工具和中间件时，你也可以使用该文件系统。

有关更多信息，请参阅 后端。要生成智能体可以从文件系统读取的持久化仓库 wiki，请参阅 OpenWiki。

文件系统权限

harness 支持声明式权限规则，用于控制智能体可以读取或写入哪些文件和目录。权限适用于上面列出的内置文件系统工具，并按声明顺序以「首个匹配者获胜」的语义进行评估。

在创建智能体时，通过将规则列表传给 permissions= 来定义权限。每条规则包括：

• operations："read" 和/或 "write"
• paths：用于文件或目录的 Glob 模式
• mode："allow" 或 "deny"

规则自上而下进行评估，第一个匹配的规则获胜。如果没有规则匹配，则允许该操作。

该模型让你可以将智能体限制在特定目录（例如 /workspace/），保护诸如 .env 或凭据之类的敏感文件，并让子智能体拥有比父智能体更窄的访问权限。

权限不适用于 沙箱后端，后者支持通过 execute 工具执行任意命令。对于自定义验证逻辑，请使用 后端策略钩子。

有关完整的规则结构、示例和子智能体继承，请参阅 权限。

代码执行

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

• 沙箱后端 暴露一个 execute 工具，用于在隔离环境中执行 shell 命令。
• 解释器 添加一个 eval 工具，用于在作用域受限的 QuickJS 运行时中运行 JavaScript。

当智能体需要安装依赖项、运行测试、调用 CLI 或操作操作系统文件系统时，请使用沙箱后端。沙箱后端实现 SandboxBackendProtocolV2；一旦检测到，harness 就会将 execute 工具添加到智能体可用的工具中。

当智能体需要一个轻量级可编程层来处理循环、批处理、确定性数据转换或程序化工具调用时，请使用解释器。解释器不提供 shell 访问、包安装，也不提供文件系统和网络访问。

有关沙箱设置、服务商和文件传输 API，请参阅 沙箱。有关 QuickJS 运行时和程序化工具调用，请参阅 解释器。

流式

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

上下文管理

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

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

技能

技能为你的深度智能体打包专门的工作流、领域知识和自定义指令。

每个技能都遵循 Agent Skills 标准，并位于一个包含 SKILL.md 文件的目录中。技能还可以包含脚本、模板、参考文档和其他支持性资源。

Deep Agents 以渐进式披露的方式加载技能：智能体在启动时读取 SKILL.md 的 frontmatter，然后仅在任务需要时才读取完整的技能内容。这样既保持启动上下文紧凑，又能按需提供丰富的能力。

有关更多信息，请参阅 技能。

记忆

记忆为你的深度智能体提供跨对话的持久化上下文，例如编码风格、偏好、约定和项目指南。

记忆使用 AGENTS.md 文件，你在创建智能体时通过 memory 参数传入它们。与技能不同，记忆文件总是会被加载，其内容存储在已配置的后端中（StateBackend、StoreBackend 或 FilesystemBackend）。

智能体还可以根据交互和反馈更新记忆，因此偏好和模式可以延续下去，而无需在每个线程中重新陈述它们。

有关配置细节和示例，请参阅 记忆。要生成编码智能体可通过 AGENTS.md 发现的仓库 wiki，请参阅 OpenWiki。

摘要与上下文卸载

harness 管理上下文，使深度智能体能够在 token 限制内处理长时间运行的工作，同时将最相关的信息保留在范围内。

这个上下文流程有四个部分：

• 输入上下文：系统提示词、记忆、技能和工具提示词定义了智能体开始时所拥有的内容。
• 压缩：内置的卸载和摘要功能会压缩对话历史和大型中间结果。
• 隔离：子智能体会隔离重量级子任务，只返回最终结果（参见 委派）。
• 长期记忆：虚拟文件系统中的持久化存储会跨线程携带信息。

这些机制共同支持超出单个上下文窗口的多步骤任务，同时减少手动裁剪上下文和 token 用量。

有关配置细节，请参阅 上下文工程。有关多模态输入和工具输出，请参阅 多模态。

提示词缓存

对于 Anthropic 和 Amazon Bedrock 模型，create_deep_agent 会自动将提示词缓存应用于系统提示词的静态部分——即在每一轮都重复的基础智能体指令、记忆和技能内容。这样可以避免在多次调用中重复处理相同的 token，从而降低长时间运行智能体的延迟和成本。

使用 Anthropic 模型或 Bedrock 模型（Claude 或 Nova）时，提示词缓存默认启用。无需任何配置。

对于其他服务商，请参阅 中间件集成 了解可用的服务商特定缓存中间件。

委派

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

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

任务规划

任务规划是一种可选择启用的 harness 能力，它让智能体可以在执行期间维护结构化的任务列表。

从 v0.7 开始，任务规划仅可选择启用。在更早的版本中，任务规划中间件是默认包含的。

规划通常对以下情况很有用：

• 冗长或复杂的多步骤任务
• 能力较弱的模型，它们能从明确的问责工具中受益
• 从智能体状态流式输出进度的 UI（参见 待办事项列表）

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

Google

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

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

OpenAI

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

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

Anthropic

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

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

OpenRouter

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()],
)

Fireworks

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()],
)

Baseten

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()],
)

Ollama

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'）并持久化在智能体状态中。这为智能体提供了一个轻量级的规划层，用于组织长时间运行和多步骤的工作。

有关配置选项和行为细节，请参阅 待办事项列表。

子智能体

harness 包含一个内置的 task 工具，它让主智能体可以创建临时子智能体，用于隔离的、长时间运行的、多步骤的或并行的任务。

子智能体执行提供：

• 全新上下文：每次调用都会创建一个拥有自己上下文的新智能体实例。
• 自主执行：子智能体独立运行直至完成。
• 单次交接：它向主智能体返回一份最终报告。
• 可配置策略：使用 默认的 general-purpose 子智能体（默认启用），或定义 自定义子智能体。
• 无状态消息传递：子智能体是无状态的，无法回传多条消息。
• 上下文和 token 效率：重量级子任务工作保持隔离，并被压缩为简洁的结果。

在不使用子智能体的情况下运行（无 task 工具）

要在没有 task 工具的情况下运行智能体，请参阅 在不使用子智能体的情况下运行。不要尝试通过 excluded_middleware 移除 SubAgentMiddleware——那会被有意拒绝。取而代之，请通过 harness 配置文件 禁用自动添加的子智能体，并通过 subagents= 不传入任何同步子智能体。异步子智能体不受影响。有关完整的顺序，请参阅 完整技术栈。

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

引导

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

人在回路

Deep Agents 与 LangGraph 中断集成，因此你可以在敏感工具调用时暂停以等待批准。可通过 create_deep_agent 中的 interrupt_on 参数启用此行为。

interrupt_on 接受工具名称到中断配置的映射。例如，interrupt_on=""edit_file": True" 会在每次编辑前暂停，让你可以在执行前批准该调用、添加指导或修改工具输入。

这为你提供了一个运行时安全与控制层，用于处理破坏性操作、昂贵的 API 调用和交互式调试。

有关更多信息，请参阅 人在回路。

开始使用

•Quickstart

构建你的第一个深度智能体

•Customization

了解自定义选项

▸Code

使用 Deep Agents Code

•ACP

在代码编辑器中使用 ACP 运行深度智能体

•Reference

查看 deepagents API 参考

---