LangChain 中文文档

外观

Deep Agents 是开始构建由 LLM 驱动的智能体和应用程序的最简单方式——内置了用于上下文管理的文件系统、子智能体生成和长期记忆能力。 当你的使用场景需要时，任务规划和技能等可选能力可扩展框架。 你可以使用深度智能体处理任何任务，包括复杂的多步骤任务。

Deep Agents 具备以下能力：

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

关于每个组件的完整说明，请参阅核心能力。

快速入门 ​

python
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"}]}
)
python
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"}]}
)
python
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-4-6",
    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"}]}
)
python
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"}]}
)
python
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"}]}
)
python
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"}]}
)
python
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"}]}
)
ts
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: "Get the weather for a given city",
  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?" }],
  }),
);

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

TIP

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

核心能力 ​

Agent harness capabilities by category

Deep Agents 是一个“智能体框架（agent harness）”。它与其它智能体框架使用相同的核心工具调用循环，但内置了让智能体在实际任务中表现可靠的能力：

  • 执行环境 — 工具、虚拟文件系统、可选沙箱和 REPL（解释器）
  • 上下文管理 — 技能、记忆、摘要、上下文卸载和提示词缓存
  • 委派 — 子智能体生成和可选任务规划
  • 引导 — 人在回路批准和中断

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

deepagents 是一个基于 LangChain 智能体核心构建模块的独立库，并使用 LangGraph 的工具在生产环境中运行智能体。

LangChain 是为你提供智能体核心构建模块的框架。 要了解 LangChain、LangGraph 和 Deep Agents 之间的区别，请参阅框架、运行时与智能体框架（harness）。如需与 Anthropic 框架的并排对比，请参阅Deep Agents 与 Claude Agent SDK。

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

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

执行环境 ​

执行环境是智能体采取行动的地方。它包含四层：

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

流式输出 使你可以通过针对消息、工具、值和委派任务的类型化事件流，实时掌握正在发生的一切。

工具与 MCP ​

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

python
from deepagents import create_deep_agent

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

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

虚拟文件系统访问 ​

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

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

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

INFO

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

ToolDescription
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

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

要从模型中隐藏上面列出的文件系统工具，请注册一个带有 `excluded_tools` 的[框架配置档案（harness profile）](/oss/deepagents/profiles#harness-profiles)：
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` 本身会被有意拒绝——它是[默认中间件栈](/oss/deepagents/customization#default-stack-main-agent)中必需的脚手架。请使用 `excluded_tools` 只隐藏模型可见的工具面，并保留中间件。要移除 `task` 工具，请参阅[在没有子智能体的情况下运行](/oss/deepagents/subagents#running-without-subagents)。

限制文件系统工具 ​

INFO

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

若要仅公开上面列出的文件系统工具的子集（而不是全部隐藏），请向 `FilesystemMiddleware` 传入 `tools` 允许列表，并通过 `middleware=` 提供该实例。任何未列入列表的内置文件系统工具都会从模型的工具列表中移除。
python
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`。无论你是否将其包含在 `tools` 中，只要配置的后端不支持 `execute` 和 `delete` 工具，它们也会从工具面中移除。你通过 `create_deep_agent` 自身的 `tools=` 参数添加的自定义工具绝不会受此允许列表的影响。

以这种方式传入你自己的 `FilesystemMiddleware` 实例会替换主智能体的默认实例，通用子智能体会继承相同的限制。有关更多信息，请参阅[覆盖默认中间件实例](/oss/deepagents/customization#override-a-default-middleware-instance)。声明式子智能体不会继承该限制：请在该子智能体自己的 `middleware` 字段中包含 `FilesystemMiddleware(tools=...)` 实例，以独立地加以限制。

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

有关更多信息，请参阅后端。

文件系统权限 ​

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

在创建智能体时，通过向 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，使每个委派任务都有自己的句柄，并带有独立的消息、工具调用和嵌套子智能体流。

上下文管理 ​

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

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

技能 ​

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

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

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

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

记忆 ​

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

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

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

有关配置细节和示例，请参阅记忆。

摘要与上下文卸载 ​

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

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

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

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

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

提示词缓存 ​

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

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

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

委派 ​

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

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

任务规划 ​

任务规划是一项可选的框架能力，让智能体在执行过程中维护结构化的任务列表。

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

任务规划通常适用于以下场景：

  • 长时间或复杂的多步骤任务
  • 能从明确的问责工具中获益的能力较弱的模型
  • 从智能体状态流式传输进度的界面（参阅待办列表）

将 TodoListMiddleware 传给 middleware 参数，为智能体提供一个 write_todos 工具，以便在执行过程中维护结构化的任务列表。

python
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()],
)
python
from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="openai:gpt-5.5",
    middleware=[TodoListMiddleware()],
)
python
from deepagents import create_deep_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    middleware=[TodoListMiddleware()],
)
python
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()],
)
python
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()],
)
python
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()],
)
python
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()],
)
ts
import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

const agent = await createDeepAgent({
  model: "google-genai:gemini-3.5-flash",
  middleware: [todoListMiddleware()],
});
ts
import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

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

const agent = await createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  middleware: [todoListMiddleware()],
});
ts
import { createDeepAgent } from "deepagents";
import { todoListMiddleware } from "langchain";

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

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

const agent = await createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  middleware: [todoListMiddleware()],
});
ts
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'），并持久化在智能体状态中。这为智能体提供了一个轻量级的规划层，用于组织长时间运行和多步骤的工作。

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

子智能体 ​

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

子智能体执行提供：

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

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

要在没有 `task` 工具的情况下运行智能体，请参阅[在没有子智能体的情况下运行](/oss/deepagents/subagents#running-without-subagents)。不要尝试通过 `excluded_middleware` 移除 `SubAgentMiddleware`——这是有意拒绝的。相反，请通过[框架配置档案（harness profile）](/oss/deepagents/profiles#harness-profiles)禁用自动添加的子智能体，并通过 `subagents=` 不传入任何同步子智能体。异步子智能体不受影响。完整的顺序请参阅[默认中间件栈](/oss/deepagents/customization#default-stack-main-agent)。

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

引导 ​

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

人在回路 ​

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

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

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

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

快速开始 ​

  • 快速入门 — 构建你的第一个深度智能体

  • 自定义 — 了解自定义选项

  • 代码 — 使用 Deep Agents Code

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

  • 参考 — 查看 deepagents API 参考

  • 快速入门 — 构建你的第一个深度智能体

  • 自定义 — 了解自定义选项

  • 代码 — 使用 Deep Agents Code

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

  • 参考 — 查看 deepagents API 参考