以编程方式使用文档

Deep Agents 是开始构建由 LLM 驱动的代理和应用程序最简单的方式——内置任务规划、用于上下文管理的文件系统、子代理生成和长期记忆等功能。 您可以将 Deep Agents 用于任何任务，包括复杂的多步骤任务。

Deep Agents 具有以下内置功能：

  • 在环境中执行操作：通过工具执行操作、读写文件、执行代码
  • 连接您的数据：在适当时机加载记忆、技能和领域知识
  • 管理不断增长的上下文：总结历史记录并在长时间运行中卸载大型结果
  • 并行化任务：委托给在隔离上下文窗口中运行的一般或专业子代理
  • 保持参与：在关键决策点暂停以等待人工审批
  • 随着时间推移而改进：根据实际使用情况更新记忆、技能和提示词

参见 核心功能 了解各组件的完整分解。

快速入门

Google

        # pip install -qU deepagents langchain-google-genai
        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.5-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

        # pip install -qU deepagents langchain-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

        # pip install -qU deepagents langchain-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-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"}]}
        )

OpenRouter

        # pip install -qU deepagents langchain-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: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"}]}
        )

Fireworks

        # pip install -qU deepagents langchain-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/qwen3p5-397b-a17b",
            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

        # pip install -qU deepagents langchain-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

        # pip install -qU deepagents langchain-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:devstral-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"}]}
        )

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

核心能力

按类别划分的智能体框架能力

Deep Agents 是一个 「智能体框架」。它与其他智能体框架具有相同的核心工具调用循环，但具有内置功能，使智能体能够可靠地处理实际任务：

Execution environment

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

Context management

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

Delegation

子智能体生成和任务规划

Steering

人工审批和中断

deepagents 是一个独立的库，构建在 LangChain的核心构建块。它使用 LangGraph 运行时，用于持久执行、流式处理、人工介入等功能。

LangChain 是为您提供代理核心构建块的框架。 要了解更多关于 LangChain、LangGraph 和 Deep Agents 之间的区别，请参阅 框架、运行时和工具。要与 Anthropic 的工具进行并列比较，请参阅 Deep Agents 与 Claude Agent SDK 对比.

若要构建不具备这些内置功能的自定义代理，请使用 LangChain 的 create_agent 或构建自定义 LangGraph workflow.

执行环境

执行环境是代理运作的场所。它有四个层级：

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

**流式处理** 使您能够使用类型化事件流跟踪消息、工具、值和委托任务的所有发生情况。

工具和 MCP

通过 MCP 服务器 参数传递自定义函数、LangChain 工具或来自任何 tools= 。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_fileRead file contents with line numbers, supports offset/limit for large files. Also supports returning multimodal content blocks for non-text files (images, video, audio, and documents). See supported extensions below.
write_file创建新文件
edit_file对文件执行精确字符串替换（支持全局替换模式）
glob查找匹配模式的文件（例如， **/*.py)
grep搜索文件内容，支持多种输出模式（仅文件、带上下文的文件内容或计数）
execute在环境中运行 shell 命令（可通过 沙箱后端 使用）

Supported multimodal file extensions

类型扩展名
图片.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

Running without the default filesystem tools

要向模型隐藏上述文件系统工具，请注册一个 工具配置文件 with 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", "glob", "grep"}
            ),
        ),
    )

移除 FilesystemMiddleware 本身（通过 excluded_middleware 会被故意拒绝——它是 默认中间件堆栈中的必需支架。若只需隐藏工具可见表面而不影响中间件，请使用 excluded_tools 来隐藏工具可见部分，保留中间件。如需完全移除 task 工具，请参阅 无子代理运行.

虚拟文件系统被工具中的其他功能使用，包括技能、记忆、代码执行和上下文管理。 在为 Deep Agents 构建自定义工具和中间件时，同样可以使用文件系统。

更多信息，请参阅 后端.

文件系统权限

工具支持声明式权限规则，用于控制代理可以读取或写入的文件和目录。这些权限适用于上述内置文件系统工具，并按声明顺序评估，采用首个匹配生效的语义。

通过向 permissions= 传递规则列表来定义权限。创建代理时。每条规则包括： - operations: "read" and/or "write" - paths：用于文件或目录的 Glob 模式 - mode: "allow" or "deny"

规则按从上到下顺序评估，首个匹配的规则生效。若无规则匹配，则允许操作。

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

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

完整的规则结构、示例和子代理继承，请参阅 权限.

代码执行

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

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

当代理需要安装依赖、运行测试、调用 CLI 或操作操作系统文件系统时，请使用沙盒后端。沙盒后端实现 SandboxBackendProtocolV2；当检测到时，测试工具会将 execute 工具添加到代理的可用工具列表中。

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

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

流式传输

事件流 将代理运行公开为消息、工具调用、值和输出的类型化投影。深度代理添加 stream.subagents 以便每个委派的任务都能获得独立的消息、工具调用和嵌套子代理流的句柄。

上下文管理

上下文管理组件控制代理的知识范围、在令牌限制内可以运行的时间长度，以及跨会话保留的内容。它有四个层次：

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

技能

技能为深度代理打包专业工作流、领域知识和自定义指令。

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

深度代理采用渐进式披露方式加载技能：代理在启动时读取 SKILL.md 前置内容，然后在任务需要时才读取完整的技能内容。这保持了启动时的上下文简洁，同时仍能按需提供丰富的能力。

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

记忆

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

记忆使用 AGENTS.md 文件 ，您在创建代理时通过 memory 参数传递这些文件。与技能不同，记忆文件始终加载，内容存储在配置的后端中（StateBackend, StoreBackend, or FilesystemBackend).

代理还可以根据交互和反馈更新记忆，因此偏好和模式可以在不需在每个会话中重复说明的情况下延续。

有关配置详情和示例，请参阅 内存.

摘要和上下文卸载

该测试框架管理上下文，使深度代理能够在令牌限制内处理长时间运行的工作，同时保持最相关的信息在范围内。

此上下文流程包含四个部分： - **输入上下文**：系统提示词、内存、技能和工具提示词定义了代理的起始状态。 - **压缩**：内置卸载和摘要功能会压缩对话历史和大型中间结果。 - **隔离**：子代理隔离重负载子任务，仅返回最终结果（请参阅 委托). - **长期记忆**：虚拟文件系统中的持久性存储可在线程之间传递信息。

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

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

提示词缓存

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

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

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

委托

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

  • - **任务规划**：内置 write_todos 用于结构化任务跟踪的工具
  • - **子代理**：处理隔离子任务的临时子代理

任务规划

该测试框架提供 write_todos ，使代理能够在执行过程中维护结构化的任务列表。

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

子代理

该测试框架包含一个内置 task ，允许主代理为隔离的、长时间运行的、多步骤的或并行的任务创建临时子代理。

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

Running without subagents (no `task` tool)

要在没有 task 工具的情况下运行代理，请参见 无子代理运行。请勿尝试通过SubAgentMiddleware移除 @ excluded_middleware——这是有意拒绝的。相反，通过 [harness 配置 禁用自动添加的子代理，并通过 subagents=不传递同步子代理。异步子代理不受影响。请参阅 默认中间件堆栈 获取完整排序。

更多信息，请参阅 子代理.

引导

引导组件使人类能够在运行时控制代理行为，并为代理工作设置文件系统权限。

Human-in-the-loop

深度代理与 LangGraph 中断集成，以便您可以在敏感工具调用时暂停以等待批准。使用 interrupt_on 中的 create_deep_agent.

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

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

更多信息，请参阅 Human-in-the-loop.

开始使用

Quickstart

构建您的第一个深度代理

Customization

了解自定义选项

Code

使用深度代理代码

ACP

在代码编辑器中通过 ACP 使用深度代理

Reference

请参阅 deepagents API 参考