Deep Agents 总览

构建能够规划、调用子智能体并利用文件系统处理复杂任务的智能体

Deep Agents 是开始构建由大语言模型（LLM）驱动的智能体和应用程序的最简单方式——内置了用于上下文管理的文件系统、子智能体衍生（subagent-spawning）以及长期记忆能力。可选功能（如任务规划和技能）可以在你的用例需要时对运行框架（harness）进行扩展。你可以将 deep agents 用于任何任务，包括复杂的多步骤任务。

Deep Agents 具备以下核心能力：

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

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

尝试使用

快速起步

import * as z from "zod";
// npm install deepagents langchain @langchain/core
import { createDeepAgent } from "deepagents";
import { tool } from "langchain";

const getWeather = tool(({ city }) => `It's always sunny in ${city}!`, {
  name: "get_weather",
  description: "获取指定城市的天气",
  schema: z.object({
    city: z.string(),
  }),
});

const agent = await createDeepAgent({
  tools: [getWeather],
  systemPrompt: "You are a helpful assistant",
});

console.log(
  await agent.invoke({
    messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
  }),
);

查看示例 Trace
为此示例打开一个公开的 LangSmith 运行记录。

请参阅快速起步和自定义指南，开始使用 Deep Agents 构建属于你自己的智能体和应用程序。

TIP

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

核心能力

按类别划分的 Agent 框架能力

Deep Agents 是一个“Agent 运行框架（agent harness）”。它具有与其他智能体框架相同的核心工具调用循环，但内置了使智能体能够可靠处理真实任务的能力：

执行环境
工具、虚拟文件系统、可选沙箱以及 REPL（解释器）

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

委派
子智能体衍生与可选的任务规划

控制引导
人在回路审批与中断

deepagents 是一个构建在 LangChain 核心智能体基础原语之上、并使用 LangGraph 工具在生产环境中运行智能体的独立库。

LangChain 是为你的智能体提供核心构件的框架。要了解 LangChain、LangGraph 和 Deep Agents 之间的区别，请参阅框架、运行时与运行框架。有关与 Anthropic 框架的横向对比，请参阅 Deep Agents vs. Claude Agent SDK。

如果想在不使用这些内置能力的情况下构建自定义智能体，可考虑使用 LangChain 的 createAgent 或构建自定义 LangGraph 工作流。

执行环境

执行环境是智能体采取行动的场所。它由四层组成：

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

流式传输允许你使用针对消息、工具、状态值和委派任务的有类型事件流来实时跟进发生的一切。

工具与 MCP

通过 tools= 参数传入自定义函数、LangChain 工具或来自任何 MCP 服务器的工具。Deep Agents 完全支持模型上下文协议（Model Context Protocol, MCP），让你通过标准接口连接到数据库、API、文件系统等。

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

虚拟文件系统访问

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

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

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

支持的多模态文件扩展名
类型扩展名
图像 .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

类型	扩展名
图像	`.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 profile）：
python
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 工具，请参阅在不使用子智能体的情况下运行。

虚拟文件系统被其他几个框架功能所使用，例如技能、记忆、代码执行和上下文管理。在为 Deep Agents 构建自定义工具和中间件时，你也可以使用该文件系统。

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

文件系统权限

运行框架支持声明式权限规则，以控制智能体可以读取或写入哪些文件和目录。权限适用于上面列出的内置文件系统工具，并按声明顺序进行评估，采用“首个匹配生效（first-match-wins）”的语义。

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

operations："read" 和/或 "write"
paths：文件或目录的 Glob 模式
mode："allow"（允许）或 "deny"（拒绝）

规则从上到下评估，第一条匹配的规则生效。如果没有规则匹配，则允许该操作。

该模型允许你将智能体限制在特定目录（例如 /workspace/），保护敏感文件（例如 .env 或凭据），并为子智能体提供比父智能体更窄的访问权限。

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

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

代码执行

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

沙箱后端公开了一个用于在隔离环境中运行 Shell 命令的 execute 工具。
解释器添加了一个在作用域限定的 QuickJS 运行时中运行 JavaScript 的 eval 工具。

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

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

有关沙箱设置、提供商和文件传输 API，请参阅沙箱。有关 QuickJS 运行时和以编程方式调用工具，请参阅解释器。

流式传输

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

上下文管理

上下文管理组件控制智能体知晓什么、它在 Token 限制内可以运行多长时间，以及它在跨会话中保留什么。它由四层组成：

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

技能

技能（Skills）为你的 deep agent 打包了专业工作流、领域知识和自定义指令。

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

Deep Agents 采用渐进式披露（progressive disclosure）加载技能：智能体在启动时读取 SKILL.md 前置元数据（frontmatter），仅在任务需要时才读取完整的技能内容。这使启动上下文保持紧凑，同时仍能按需提供丰富的能力。

更多信息请参阅技能。

记忆

记忆为你的 deep agent 提供了跨对话的持久上下文，例如代码风格、偏好、约定和项目准则。

记忆使用在创建智能体时通过 memory 参数传入的 AGENTS.md 文件。与技能不同，记忆文件始终处于加载状态，内容存储在配置的后端（StateBackend、StoreBackend 或 FilesystemBackend）中。

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

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

摘要与上下文卸载

运行框架负责管理上下文，使 deep agents 能够在 Token 限制内处理长时间运行的工作，同时保持最相关的信息在有效范围内。

这种上下文流动包含四个部分：

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

这些机制共同支持超过单个上下文窗口的多步骤任务，同时减少手动修剪上下文的操作和 Token 使用量。

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

提示词缓存

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

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

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

委派

委派（Delegation）组件使智能体能够将大问题拆解为较小的、可并行化的工作单元。它包含两层：

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

任务规划

任务规划是一项可选的框架能力，它允许智能体在执行期间维护结构化任务列表。

从 v0.7 开始，任务规划为纯可选功能。在更早的版本中，任务规划中间件是默认包含的。

规划通常对以下场景很有用：

冗长或复杂的多步骤任务
能从明确的责任工具中受益的较弱模型
从智能体状态流式传输进度的 UI（参见 Todo 列表）

将 TodoListMiddleware 传递给中间件参数，即可为智能体提供 write_todos 工具，用于在执行期间维护结构化任务列表。

import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "google:gemini-3.6-flash",
  middleware: [todoListMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "openai:gpt-5.5",
  middleware: [todoListMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-5",
  middleware: [todoListMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "openrouter:z-ai/glm-5.2",
  middleware: [todoListMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  middleware: [todoListMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  middleware: [todoListMiddleware()],
});

import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  middleware: [todoListMiddleware()],
});

任务支持状态跟踪（'pending'、'in_progress'、'completed'），并持久化保存在智能体状态中。这为智能体提供了一个轻量级的规划层，用于组织长时间运行和多步骤的工作。

有关配置选项和行为详细信息，请参阅待办事项列表（To-do list）。

子智能体

运行框架包含一个内置的 task 工具，它允许主智能体创建短暂的子智能体（ephemeral subagents），用于执行隔离的、长时间运行的、多步骤或并行的任务。提供两种子智能体类型：同步子智能体（默认）会阻塞主管智能体，直到返回单一报告；异步子智能体并行运行，并通过启动（launch）、检查（check）、更新（update）和取消（cancel）工具支持运行中控制。

子智能体执行提供：

隔离或继承的上下文：默认情况下，每次调用都会创建一个具有自身上下文的新智能体实例（mode: "isolated"）。使用 mode: "fork" 可以继承父级的完整对话历史。参见分叉子智能体。
自主执行：子智能体独立运行直到完成。
单次交接：它向主智能体返回一份最终报告。
可配置策略：使用默认的通用（general-purpose）子智能体（默认启用）或定义自定义子智能体。
无状态消息传递：子智能体是无状态的，无法发回多条消息。
上下文与 Token 效率：繁重的子任务工作保持隔离，并压缩为紧凑的结果。

更多信息请参阅子智能体。要移除 task 工具，请参阅在不使用子智能体的情况下运行。

控制引导

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

人在回路

Deep Agents 与 LangGraph 中断机制相集成，因此你可以在敏感的工具调用上暂停以等待审批。在 create_deep_agent 中使用 interrupt_on 参数启用此行为。

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

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

更多信息请参阅人在回路（Human-in-the-loop）。

开始探索

快速起步
构建你的第一个 deep agent

自定义指南
了解自定义选项

ACP 协议
通过 ACP 在代码编辑器中使用 deep agents

参考文档
查看 deepagents API 参考文档

Deep Agents 总览 ​

尝试使用 ​

快速起步 ​

核心能力 ​

执行环境 ​

工具与 MCP ​

虚拟文件系统访问 ​

文件系统权限 ​

代码执行 ​

流式传输 ​

上下文管理 ​

技能 ​

记忆 ​

摘要与上下文卸载 ​

提示词缓存 ​

委派 ​

任务规划 ​

子智能体 ​

控制引导 ​

人在回路 ​

开始探索 ​