自定义 Deep Agents

create_deep_agent 具有以下核心配置选项：

模型
工具
系统提示
中间件
子代理
后端（虚拟文件系统）
人机协作
技能
记忆
配置文件

create_deep_agent(
    model: str | BaseChatModel | None = None,
    tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
    *,
    system_prompt: str | SystemMessage | None = None,
    middleware: Sequence[AgentMiddleware] = (),
    subagents: Sequence[SubAgent | CompiledSubAgent | AsyncSubAgent] | None = None,
    skills: list[str] | None = None,
    memory: list[str] | None = None,
    permissions: list[FilesystemPermission] | None = None,
    backend: BackendProtocol | BackendFactory | None = None,
    interrupt_on: dict[str, bool | InterruptOnConfig] | None = None,
    response_format: ResponseFormat[ResponseT] | type[ResponseT] | dict[str, Any] | None = None,
    context_schema: type[ContextT] | None = None,
    checkpointer: Checkpointer | None = None,
    store: BaseStore | None = None,
    debug: bool = False,
    name: str | None = None,
    cache: BaseCache | None = None
) -> CompiledStateGraph[AgentState[ResponseT], ContextT, _InputAgentState, _OutputAgentState[ResponseT]]

有关完整参数列表，请参阅 create_deep_agent API 参考。

模型

传递一个 provider:model 格式的 model 字符串，或一个已初始化的模型实例。有关所有提供商，请参阅支持的模型；有关经过测试的推荐模型，请参阅推荐模型。

使用 provider:model 格式（例如 openai:gpt-5.4）可以快速切换模型。

👉 阅读 OpenAI 聊天模型集成文档

pip install -U "langchain[openai]"

import os
from deepagents import create_deep_agent

os.environ["OPENAI_API_KEY"] = "sk-..."

agent = create_deep_agent(model="openai:gpt-5.4")
# 这会使用默认参数为指定模型调用 init_chat_model
# 要使用特定的模型参数，请直接使用 init_chat_model

import os
from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

os.environ["OPENAI_API_KEY"] = "sk-..."

model = init_chat_model(model="openai:gpt-5.4")
agent = create_deep_agent(model=model)

import os
from langchain_openai import ChatOpenAI
from deepagents import create_deep_agent

os.environ["OPENAI_API_KEY"] = "sk-..."

model = ChatOpenAI(model="gpt-5.4")
agent = create_deep_agent(model=model)

👉 阅读 Anthropic 聊天模型集成文档

pip install -U "langchain[anthropic]"

import os
from deepagents import create_deep_agent

os.environ["ANTHROPIC_API_KEY"] = "sk-..."

agent = create_deep_agent(model="anthropic:claude-sonnet-4-6")
# 这会使用默认参数为指定模型调用 init_chat_model
# 要使用特定的模型参数，请直接使用 init_chat_model

import os
from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

os.environ["ANTHROPIC_API_KEY"] = "sk-..."

model = init_chat_model(model="claude-sonnet-4-6")
agent = create_deep_agent(model=model)

import os
from langchain_anthropic import ChatAnthropic
from deepagents import create_deep_agent

os.environ["ANTHROPIC_API_KEY"] = "sk-..."

model = ChatAnthropic(model="claude-sonnet-4-6")
agent = create_deep_agent(model=model)

👉 阅读 Azure 聊天模型集成文档

pip install -U "langchain[openai]"

import os
from deepagents import create_deep_agent

os.environ["AZURE_OPENAI_API_KEY"] = "..."
os.environ["AZURE_OPENAI_ENDPOINT"] = "..."
os.environ["OPENAI_API_VERSION"] = "2025-03-01-preview"

agent = create_deep_agent(model="azure_openai:gpt-5.4")
# 这会使用默认参数为指定模型调用 init_chat_model
# 要使用特定的模型参数，请直接使用 init_chat_model

import os
from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

os.environ["AZURE_OPENAI_API_KEY"] = "..."
os.environ["AZURE_OPENAI_ENDPOINT"] = "..."
os.environ["OPENAI_API_VERSION"] = "2025-03-01-preview"

model = init_chat_model(
    model="azure_openai:gpt-5.4",
    azure_deployment=os.environ["AZURE_OPENAI_DEPLOYMENT_NAME"],
)
agent = create_deep_agent(model=model)

import os
from langchain_openai import AzureChatOpenAI
from deepagents import create_deep_agent

os.environ["AZURE_OPENAI_API_KEY"] = "..."
os.environ["AZURE_OPENAI_ENDPOINT"] = "..."
os.environ["OPENAI_API_VERSION"] = "2025-03-01-preview"

model = AzureChatOpenAI(
    model="gpt-5.4",
    azure_deployment=os.environ["AZURE_OPENAI_DEPLOYMENT_NAME"],
)
agent = create_deep_agent(model=model)

👉 阅读 Google GenAI 聊天模型集成文档

pip install -U "langchain[google-genai]"

import os
from deepagents import create_deep_agent

os.environ["GOOGLE_API_KEY"] = "..."

agent = create_deep_agent(model="google_genai:gemini-3.1-pro-preview")
# 这会使用默认参数为指定模型调用 init_chat_model
# 要使用特定的模型参数，请直接使用 init_chat_model

import os
from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

os.environ["GOOGLE_API_KEY"] = "..."

model = init_chat_model(model="google_genai:gemini-3.1-pro-preview")
agent = create_deep_agent(model=model)

import os
from langchain_google_genai import ChatGoogleGenerativeAI
from deepagents import create_deep_agent

os.environ["GOOGLE_API_KEY"] = "..."

model = ChatGoogleGenerativeAI(model="gemini-3.1-pro-preview")
agent = create_deep_agent(model=model)

👉 阅读 AWS Bedrock 聊天模型集成文档

pip install -U "langchain[aws]"

from deepagents import create_deep_agent

# 按照此处的步骤配置您的凭据：
# https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html

agent = create_deep_agent(
    model="anthropic.claude-sonnet-4-6",
    model_provider="bedrock_converse",
)
# 这会使用默认参数为指定模型调用 init_chat_model
# 要使用特定的模型参数，请直接使用 init_chat_model

from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

# 按照此处的步骤配置您的凭据：
# https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html

model = init_chat_model(
    model="anthropic.claude-sonnet-4-6",
    model_provider="bedrock_converse",
)
agent = create_deep_agent(model=model)

from langchain_aws import ChatBedrock
from deepagents import create_deep_agent

# 按照此处的步骤配置您的凭据：
# https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html

model = ChatBedrock(model="anthropic.claude-sonnet-4-6")
agent = create_deep_agent(model=model)

👉 阅读 HuggingFace 聊天模型集成文档

pip install -U "langchain[huggingface]"

import os
from deepagents import create_deep_agent

os.environ["HUGGINGFACEHUB_API_TOKEN"] = "hf_..."

agent = create_deep_agent(
    model="microsoft/Phi-3-mini-4k-instruct",
    model_provider="huggingface",
    temperature=0.7,
    max_tokens=1024,
)
# 这会使用默认参数为指定模型调用 init_chat_model
# 要使用特定的模型参数，请直接使用 init_chat_model

import os
from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

os.environ["HUGGINGFACEHUB_API_TOKEN"] = "hf_..."

model = init_chat_model(
    model="microsoft/Phi-3-mini-4k-instruct",
    model_provider="huggingface",
    temperature=0.7,
    max_tokens=1024,
)
agent = create_deep_agent(model=model)

import os
from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint
from deepagents import create_deep_agent

os.environ["HUGGINGFACEHUB_API_TOKEN"] = "hf_..."

llm = HuggingFaceEndpoint(
    repo_id="microsoft/Phi-3-mini-4k-instruct",
    temperature=0.7,
    max_length=1024,
)
model = ChatHuggingFace(llm=llm)
agent = create_deep_agent(model=model)

传入任何支持的模型字符串，或一个已初始化的模型实例：

from deepagents import create_deep_agent

agent = create_deep_agent(model="provider:model-name")

from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model

model = init_chat_model("provider:model-name")
agent = create_deep_agent(model=model)

from langchain_<provider> import Chat<Provider>
from deepagents import create_deep_agent

model = Chat<Provider>(model="model-name")
agent = create_deep_agent(model=model)

连接弹性

LangChain 聊天模型会自动使用指数退避策略重试失败的 API 请求。默认情况下，模型会为网络错误、速率限制（429）和服务器错误（5xx）重试最多 6 次。客户端错误（如 401 未授权或 404 未找到）不会重试。您可以在创建模型时调整 max_retries 参数，以根据您的环境调整此行为：

from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

agent = create_deep_agent(
    model=init_chat_model(
        model="google_genai:gemini-3.1-pro-preview",
        max_retries=10,  # 对于不可靠的网络增加重试次数（默认：6）
        timeout=120,     # 对于慢速连接增加超时时间
    ),
)

对于在不可靠网络上运行的长时间代理任务，考虑将 max_retries 增加到 10-15，并配合使用检查点，以便在失败时保留进度。

工具

除了用于规划、文件管理和子代理生成的内置工具外，您还可以提供自定义工具：

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """运行网络搜索"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    tools=[internet_search]
)

系统提示

Deep Agents 自带一个内置系统提示。Deep Agent 的价值来自于 SDK 在模型之上提供的编排层——规划、虚拟文件系统工具和子代理——模型需要知道这些工具的存在以及何时使用它们。内置提示教会代理如何使用这个脚手架，这样您就不必为每个项目重新推导它；通过配置文件或您自己的 system_prompt= 来调整它，而不是逐字复制。当中间件添加特殊工具（如文件系统工具）时，它会将它们附加到系统提示中。每个 Deep Agent 还应包含一个针对其特定用例的自定义系统提示：

from deepagents import create_deep_agent

research_instructions = """\
你是一名专业的研究员。你的工作是进行 \
深入的研究，然后撰写一份精炼的报告。\
"""

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    system_prompt=research_instructions,
)

提示组装

Deep Agents 从最多四个命名部分构建系统提示，以便调用者提供的指令、SDK 的内置代理指导以及任何特定于模型的配置文件覆盖可以以可预测的优先级共存。如果没有这种分层，为 Claude（例如）调整的配置文件后缀可能会根据调用顺序覆盖或被您的 system_prompt= 参数覆盖；命名槽位使顺序明确且稳定。在实践中，大多数调用者只遇到两个槽位：USER（您的 system_prompt=）和 BASE（SDK 默认值）。选择具有内置配置文件的模型——目前是 Anthropic 或 OpenAI——会添加一个 SUFFIX。完整的四部分组装主要在您编写自定义 HarnessProfile 或调试配置文件文本出现位置时相关。四个命名部分（每个都可能缺失）：

名称	来源	备注
`USER`	`create_deep_agent` 的 `system_prompt=` 参数	`str` 或 `SystemMessage`；未设置时省略。
`BASE`	SDK 默认值（`BASE_AGENT_PROMPT`）	始终存在，除非被配置文件的 `CUSTOM` 替换。
`CUSTOM`	`HarnessProfile.base_system_prompt`	当匹配的配置文件设置它时，完全替换 `BASE`。
`SUFFIX`	`HarnessProfile.system_prompt_suffix`	当匹配的配置文件设置它时，最后附加。

顺序始终是 USER -> (BASE 或 CUSTOM) -> SUFFIX，由空行（\n\n）连接。由此产生两个不变式：

USER 始终在最前面。 调用者的文本优先于任何 SDK 或配置文件内容，因此无论选择哪个模型，角色/指令都具有优先权。
SUFFIX 始终在最后。 配置文件后缀最接近对话历史，模型调整指导在此处最可靠地生效。

组装形式（✓ = 字段已设置，- = 字段未设置）：

`system_prompt=`	配置文件 `base_system_prompt` (`CUSTOM`)	配置文件 `system_prompt_suffix` (`SUFFIX`)	最终组装的系统提示
`None`	-	-	`BASE`
`None`	-	✓	`BASE` + `SUFFIX`
`None`	✓	-	`CUSTOM`
`None`	✓	✓	`CUSTOM` + `SUFFIX`
`str`	-	-	`USER` + `BASE`
`str`	-	✓	`USER` + `BASE` + `SUFFIX`
`str`	✓	-	`USER` + `CUSTOM`
`str`	✓	✓	`USER` + `CUSTOM` + `SUFFIX`

实际示例——内置配置文件（Anthropic、OpenAI）仅提供 system_prompt_suffix，因此典型调用落在 str + - + ✓ 行：

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    system_prompt="你是 ACME 公司的客户支持代理。",
)
# 最终 = USER + BASE + SUFFIX
#       = "你是 ACME 公司的客户支持代理。"
#         + "\n\n"
#         + BASE_AGENT_PROMPT
#         + "\n\n"
#         + <Claude 特定的指导>

传递 SystemMessage（而不是字符串）会触发不同的连接路径：右侧组装（BASE 或 CUSTOM 加上任何 SUFFIX）作为额外的文本内容块附加到消息现有的 content_blocks 上。相同的逻辑顺序适用（调用者块优先），并且调用者块上的任何 cache_control 标记都会被保留——这对于放置显式的 Anthropic 提示缓存断点很有用。

子代理提示

相同的覆盖规则适用于声明式子代理——每个子代理根据其自身模型重新运行配置文件解析，然后将解析后的配置文件的 base_system_prompt / system_prompt_suffix 应用于其编写的 system_prompt。子代理的 system_prompt 扮演 BASE 角色；CUSTOM 和 SUFFIX 来自与子代理模型匹配的配置文件（可能与主代理的配置文件不同）。

`spec["system_prompt"]`	配置文件 `base_system_prompt` (`CUSTOM`)	配置文件 `system_prompt_suffix` (`SUFFIX`)	最终子代理系统提示
已编写	-	-	已编写
已编写	-	✓	已编写 + `SUFFIX`
已编写	✓	-	`CUSTOM`
已编写	✓	✓	`CUSTOM` + `SUFFIX`

子代理没有 USER 部分——规范的已编写 system_prompt 是最接近的模拟，并保持在 BASE 槽位中。仅提供 system_prompt_suffix 的配置文件（内置 Anthropic / OpenAI 配置文件的常见情况）只是附加到子代理作者编写的任何内容；设置 base_system_prompt 的配置文件将完全替换已编写的提示，因此请谨慎使用该字段。

通用子代理提示

自动添加的通用子代理遵循相同的覆盖规则，但多了一层：GP 基础提示解析为 general_purpose_subagent.system_prompt（如果已设置）-> HarnessProfile.base_system_prompt（如果已设置）-> SDK GP 默认值。配置文件后缀无论如何都会叠加在上面。两个覆盖字段都可以携带基础提示替换，但它们不可互换。general_purpose_subagent.system_prompt 是 GP 特定的配置；base_system_prompt 是主要针对主代理的全局覆盖。当两者都设置时，GP 特定的意图对 GP 子代理生效，因此同时调整这两个字段的用户永远不会看到他们的 GP 覆盖被静默丢弃：

register_harness_profile(
    "anthropic",
    HarnessProfile(
        base_system_prompt="你是 ACME 的支持协调员。",  # 主代理
        general_purpose_subagent=GeneralPurposeSubagentProfile(
            system_prompt="你是一个研究子代理。请引用来源。",  # GP 子代理
        ),
        system_prompt_suffix="始终逐步思考。",
    ),
)

堆栈	最终系统提示
主代理	`"你是 ACME 的支持协调员。" + SUFFIX`
GP 子代理	`"你是一个研究子代理。请引用来源。" + SUFFIX`

如果 general_purpose_subagent.system_prompt 未设置，GP 子代理将回退到 base_system_prompt（如果已设置），最后回退到 SDK GP 默认值。

中间件

默认情况下，Deep Agents 可以访问以下中间件：

TodoListMiddleware：跟踪和管理待办事项列表，用于组织代理任务和工作
FilesystemMiddleware：处理文件系统操作，如读取、写入和导航目录
SubAgentMiddleware：生成和协调子代理，将任务委派给专门的代理
SummarizationMiddleware：当对话变长时，压缩消息历史以保持在上下文限制内
AnthropicPromptCachingMiddleware：使用 Anthropic 模型时自动减少冗余的令牌处理
PatchToolCallsMiddleware：当工具调用在接收结果之前被中断或取消时，自动修复消息历史

如果您使用记忆、技能或人机协作，还会包含以下中间件：

MemoryMiddleware：当提供 memory 参数时，跨会话持久化和检索对话上下文
SkillsMiddleware：当提供 skills 参数时启用自定义技能
HumanInTheLoopMiddleware：当提供 interruptOn 参数时，在指定点暂停以进行人工批准或输入

预构建中间件

LangChain 提供了额外的预构建中间件，允许您添加各种功能，例如重试、回退或 PII 检测。有关更多信息，请参阅预构建中间件。 deepagents 库还提供了 create_summarization_tool_middleware，使代理能够在合适的时机（例如任务之间）触发摘要，而不是在固定的令牌间隔。有关更多详细信息，请参阅摘要。

特定于提供商的中间件

有关针对特定 LLM 提供商优化的特定于提供商的中间件，请参阅官方集成和社区集成。

自定义中间件

您可以提供额外的中间件来扩展功能、添加工具或实现自定义钩子：

from langchain.tools import tool
from langchain.agents.middleware import wrap_tool_call
from deepagents import create_deep_agent


@tool
def get_weather(city: str) -> str:
    """获取城市的天气。"""
    return f"{city} 的天气是晴天。"


call_count = [0]  # 使用列表以允许在嵌套函数中修改

@wrap_tool_call
def log_tool_calls(request, handler):
    """拦截并记录每个工具调用 - 演示横切关注点。"""
    call_count[0] += 1
    tool_name = request.name if hasattr(request, 'name') else str(request)

    print(f"[中间件] 工具调用 #{call_count[0]}: {tool_name}")
    print(f"[中间件] 参数: {request.args if hasattr(request, 'args') else 'N/A'}")

    # 执行工具调用
    result = handler(request)

    # 记录结果
    print(f"[中间件] 工具调用 #{call_count[0]} 已完成")

    return result


agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    tools=[get_weather],
    middleware=[log_tool_calls],
)

初始化后不要修改属性如果您需要在钩子调用之间跟踪值（例如计数器或累积数据），请使用图状态。图状态按设计限定于一个线程，因此更新在并发下是安全的。请这样做：

class CustomMiddleware(AgentMiddleware):
    def __init__(self):
        pass

    def before_agent(self, state, runtime):
        return {"x": state.get("x", 0) + 1}  # 改为更新图状态

不要这样做：

class CustomMiddleware(AgentMiddleware):
    def __init__(self):
        self.x = 1

    def before_agent(self, state, runtime):
        self.x += 1  # 修改会导致竞态条件

就地修改，例如在 before_agent 中修改 self.x 或在钩子中更改其他共享值，可能导致细微的错误和竞态条件，因为许多操作并发运行（子代理、并行工具以及在不同线程上的并行调用）。有关使用自定义属性扩展状态的完整详细信息，请参阅自定义中间件 - 自定义状态模式。如果您必须在自定义中间件中使用修改，请考虑当子代理、并行工具或并发代理调用同时运行时会发生什么。

子代理

为了隔离详细工作并避免上下文膨胀，请使用子代理：

import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """执行网络搜索"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

research_subagent = {
    "name": "research-agent",
    "description": "用于更深入地研究问题",
    "system_prompt": "你是一位出色的研究员",
    "tools": [internet_search],
    "model": "openai:gpt-5.4",  # 可选覆盖，默认使用主代理模型
}
subagents = [research_subagent]

agent = create_deep_agent(
    model="claude-sonnet-4-6",
    subagents=subagents
)

有关更多信息，请参阅子代理。

后端

Deep Agent 的工具可以利用虚拟文件系统来存储、访问和编辑文件。默认情况下，Deep Agents 使用 StateBackend。如果您使用技能或记忆，则必须在创建代理之前将预期的技能或记忆文件添加到后端。

StateBackend
FilesystemBackend
LocalShellBackend
StoreBackend
CompositeBackend

存储在 langgraph 状态中的临时文件系统后端。此文件系统仅在_单个线程_内持久化。

# 默认情况下我们提供一个 StateBackend
agent = create_deep_agent(model="google_genai:gemini-3.1-pro-preview")

# 底层实现如下
from deepagents.backends import StateBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=StateBackend()
)

本地机器的文件系统。

此后端授予代理直接的文件系统读/写访问权限。请谨慎使用，仅在适当的环境中使用。有关更多信息，请参阅 FilesystemBackend。

from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=FilesystemBackend(root_dir=".", virtual_mode=True)
)

一个直接在主机上执行 shell 的文件系统。提供文件系统工具以及用于运行命令的 execute 工具。

此后端授予代理直接的文件系统读/写访问权限以及在主机上不受限制的 shell 执行权限。请极其谨慎地使用，仅在适当的环境中使用。有关更多信息，请参阅 LocalShellBackend。

from deepagents.backends import LocalShellBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=LocalShellBackend(root_dir=".", env={"PATH": "/usr/bin:/bin"})
)

一个提供_跨线程持久化_长期存储的文件系统。

from langgraph.store.memory import InMemoryStore
from deepagents.backends import StoreBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=StoreBackend(
        namespace=lambda ctx: (ctx.runtime.context.user_id,),
    ),
    store=InMemoryStore()  # 适用于本地开发；部署到 LangSmith 时请省略此参数
)

部署到 LangSmith Deployment 时，请省略 store 参数。平台会自动为您的智能体配置存储。

namespace 参数控制数据隔离。对于多用户部署，始终设置命名空间工厂以按用户或租户隔离数据。

一个灵活的后端，您可以在文件系统中指定不同的路由指向不同的后端。

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(),
        }
    ),
    store=InMemoryStore()  # Store passed to create_deep_agent, not backend
)

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

沙箱

沙箱是专门的后端，在隔离环境中运行代理代码，拥有自己的文件系统和用于 shell 命令的 execute 工具。当您希望 Deep Agent 写入文件、安装依赖项和运行命令而不更改本地机器上的任何内容时，请使用沙箱后端。您可以通过在创建 Deep Agent 时将沙箱后端传递给 backend 来配置沙箱：

Modal
Runloop
Daytona
LangSmith

pip install langchain-modal

uv add langchain-modal

import modal
from deepagents import create_deep_agent
from langchain_anthropic import ChatAnthropic
from langchain_modal import ModalSandbox

app = modal.App.lookup("your-app")
modal_sandbox = modal.Sandbox.create(app=app)
backend = ModalSandbox(sandbox=modal_sandbox)

agent = create_deep_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    system_prompt="You are a Python coding assistant with sandbox access.",
    backend=backend,
)
try:
    result = agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": "Create a small Python package and run pytest",
                }
            ]
        }
    )
finally:
    modal_sandbox.terminate()

pip install langchain-runloop

uv add langchain-runloop

import os

from deepagents import create_deep_agent
from langchain_anthropic import ChatAnthropic
from langchain_runloop import RunloopSandbox
from runloop_api_client import RunloopSDK

client = RunloopSDK(bearer_token=os.environ["RUNLOOP_API_KEY"])

devbox = client.devbox.create()
backend = RunloopSandbox(devbox=devbox)

agent = create_deep_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    system_prompt="You are a Python coding assistant with sandbox access.",
    backend=backend,
)

try:
    result = agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": "Create a small Python package and run pytest",
                }
            ]
        }
    )
finally:
    devbox.shutdown()

pip install langchain-daytona

uv add langchain-daytona

from daytona import Daytona
from deepagents import create_deep_agent
from langchain_anthropic import ChatAnthropic
from langchain_daytona import DaytonaSandbox

sandbox = Daytona().create()
backend = DaytonaSandbox(sandbox=sandbox)

agent = create_deep_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    system_prompt="You are a Python coding assistant with sandbox access.",
    backend=backend,
)

try:
    result = agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": "Create a small Python package and run pytest",
                }
            ]
        }
    )
finally:
    sandbox.stop()

LangSmith 沙箱目前处于私有测试阶段。

pip install "langsmith[sandbox]"

uv add "langsmith[sandbox]"

from deepagents import create_deep_agent
from deepagents.backends import LangSmithSandbox
from langchain_anthropic import ChatAnthropic
from langsmith.sandbox import SandboxClient

client = SandboxClient()
ls_sandbox = client.create_sandbox(template_name="my-template")
backend = LangSmithSandbox(sandbox=ls_sandbox)

agent = create_deep_agent(
    model=ChatAnthropic(model="claude-sonnet-4-6"),
    system_prompt="You are a Python coding assistant with sandbox access.",
    backend=backend,
)
try:
    result = agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": "Create a small Python package and run pytest",
                }
            ]
        }
    )
finally:
    client.delete_sandbox(ls_sandbox.name)

有关更多信息，请参阅沙箱。

人机协作

某些工具操作可能很敏感，需要在执行前获得人工批准。您可以为每个工具配置批准：

from langchain.tools import tool
from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver

@tool
def delete_file(path: str) -> str:
    """从文件系统中删除文件。"""
    return f"已删除 {path}"

@tool
def read_file(path: str) -> str:
    """从文件系统中读取文件。"""
    return f"{path} 的内容"

@tool
def send_email(to: str, subject: str, body: str) -> str:
    """发送电子邮件。"""
    return f"已向 {to} 发送电子邮件"

# Human in the Loop功能必须使用检查点保存器
checkpointer = MemorySaver()

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    tools=[delete_file, read_file, send_email],
    interrupt_on={
        "delete_file": True,  # 默认：批准、编辑、拒绝、回复
        "read_file": False,   # 无需中断
        "send_email": {"allowed_decisions": ["approve", "reject"]},  # 不可编辑
    },
    checkpointer=checkpointer  # 必需！
)

您可以为代理和子代理配置在工具调用时以及从工具调用内部进行中断。有关更多信息，请参阅人机协作。

技能

您可以使用技能为您的 Deep Agent 提供新的能力和专业知识。虽然工具往往涵盖较低级别的功能，如原生文件系统操作或规划，但技能可以包含有关如何完成任务的详细说明、参考信息和其他资产，例如模板。这些文件仅在代理确定该技能对当前提示有用时才会被代理加载。这种渐进式披露减少了代理在启动时需要考虑的令牌和上下文数量。有关示例技能，请参阅 Deep Agents 示例技能。要将技能添加到您的 Deep Agent，请将它们作为参数传递给 create_deep_agent：

StateBackend
StoreBackend
FilesystemBackend

from urllib.request import urlopen
from deepagents import create_deep_agent
from deepagents.backends.utils import create_file_data
from langgraph.checkpoint.memory import MemorySaver

checkpointer = MemorySaver()

skill_url = "https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/libs/cli/examples/skills/langgraph-docs/SKILL.md"
with urlopen(skill_url) as response:
    skill_content = response.read().decode('utf-8')

skills_files = {
    "/skills/langgraph-docs/SKILL.md": create_file_data(skill_content)
}

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    skills=["/skills/"],
    checkpointer=checkpointer,
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "What is langgraph?",
            }
        ],
        # 为默认 StateBackend 的内部状态文件系统提供种子（虚拟路径必须以 "/" 开头）。
        "files": skills_files
    },
    config={"configurable": {"thread_id": "12345"}},
)

from urllib.request import urlopen
from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from deepagents.backends.utils import create_file_data
from langgraph.store.memory import InMemoryStore


store = InMemoryStore()

skill_url = "https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/libs/cli/examples/skills/langgraph-docs/SKILL.md"
with urlopen(skill_url) as response:
    skill_content = response.read().decode('utf-8')

store.put(
    namespace=("filesystem",),
    key="/skills/langgraph-docs/SKILL.md",
    value=create_file_data(skill_content)
)

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=StoreBackend(),
    store=store,
    skills=["/skills/"]
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "What is langgraph?",
            }
        ]
    },
    config={"configurable": {"thread_id": "12345"}},
)

from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver
from deepagents.backends.filesystem import FilesystemBackend

# 人机交互需要检查点存储器
checkpointer = MemorySaver()

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=FilesystemBackend(root_dir="/Users/user/{project}"),
    skills=["/Users/user/{project}/skills/"],
    interrupt_on={
        "write_file": True,  # 默认：批准、编辑、拒绝
        "read_file": False,  # 无需中断
        "edit_file": True    # 默认：批准、编辑、拒绝
    },
    checkpointer=checkpointer,  # 必需！
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "What is langgraph?",
            }
        ]
    },
    config={"configurable": {"thread_id": "12345"}},
)

记忆

使用 AGENTS.md 文件为您的 Deep Agent 提供额外的上下文。您可以在创建 Deep Agent 时将一个或多个文件路径传递给 memory 参数：

StateBackend
StoreBackend
FilesystemBackend

from urllib.request import urlopen

from deepagents import create_deep_agent
from deepagents.backends.utils import create_file_data
from langgraph.checkpoint.memory import MemorySaver

with urlopen("https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/examples/text-to-sql-agent/AGENTS.md") as response:
    agents_md = response.read().decode("utf-8")
checkpointer = MemorySaver()

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    memory=[
        "/AGENTS.md"
    ],
    checkpointer=checkpointer,
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "请告诉我你的记忆文件里有什么。",
            }
        ],
        # 为默认 StateBackend 的内存中文件系统提供种子（虚拟路径必须以 "/" 开头）。
        "files": {"/AGENTS.md": create_file_data(agents_md)},
    },
    config={"configurable": {"thread_id": "123456"}},
)

from urllib.request import urlopen

from deepagents import create_deep_agent
from deepagents.backends import StoreBackend
from deepagents.backends.utils import create_file_data
from langgraph.store.memory import InMemoryStore

with urlopen("https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/examples/text-to-sql-agent/AGENTS.md") as response:
    agents_md = response.read().decode("utf-8")

# 创建存储并添加文件
store = InMemoryStore()
file_data = create_file_data(agents_md)
store.put(
    namespace=("filesystem",),
    key="/AGENTS.md",
    value=file_data
)

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=StoreBackend(),
    store=store,
    memory=[
        "/AGENTS.md"
    ]
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "请告诉我你的记忆文件里有什么。",
            }
        ],
        "files": {"/AGENTS.md": create_file_data(agents_md)},
    },
    config={"configurable": {"thread_id": "12345"}},
)

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from langgraph.checkpoint.memory import MemorySaver

# 人机协作需要检查点
checkpointer = MemorySaver()

agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    backend=FilesystemBackend(root_dir="/Users/user/{project}"),
    memory=[
        "./AGENTS.md"
    ],
    interrupt_on={
        "write_file": True,  # 默认：批准、编辑、拒绝
        "read_file": False,  # 不需要中断
        "edit_file": True    # 默认：批准、编辑、拒绝
    },
    checkpointer=checkpointer,  # 必需！
)

配置文件

配置文件打包了每个提供商或每个模型的调整（系统提示后缀、工具描述覆盖、排除的工具或中间件、额外的中间件以及通用子代理编辑），以便 create_deep_agent 在选择匹配的模型时自动应用它们。

from deepagents import HarnessProfile, register_harness_profile

# 每当选择 gpt-5.4 时附加系统提示后缀。
register_harness_profile(
    "openai:gpt-5.4",
    HarnessProfile(system_prompt_suffix="回复不超过 100 个字。"),
)

有关注册键、合并语义和插件打包，请参阅配置文件。一个更窄的配套 API，提供商配置文件，打包了提供商的模型构造参数。

结构化输出

Deep Agents 支持结构化输出。您可以通过将所需的结构化输出模式作为 response_format 参数传递给 create_deep_agent() 调用来设置它。当模型生成结构化数据时，它会被捕获、验证，并在 Deep Agent 状态的 ‘structured_response’ 键中返回。

import os
from typing import Literal
from pydantic import BaseModel, Field
from tavily import TavilyClient
from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """运行网络搜索"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

class WeatherReport(BaseModel):
    """包含当前状况和预报的结构化天气报告。"""
    location: str = Field(description="此天气报告的位置")
    temperature: float = Field(description="当前温度（摄氏度）")
    condition: str = Field(description="当前天气状况（例如，晴天、多云、雨天）")
    humidity: int = Field(description="湿度百分比")
    wind_speed: float = Field(description="风速（公里/小时）")
    forecast: str = Field(description="未来 24 小时的简要预报")


agent = create_deep_agent(
    model="google_genai:gemini-3.1-pro-preview",
    response_format=WeatherReport,
    tools=[internet_search]
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "旧金山的天气怎么样？"
    }]
})

print(result["structured_response"])
# location='San Francisco, California' temperature=18.3 condition='Sunny' humidity=48 wind_speed=7.6 forecast='Pleasant sunny conditions expected to continue with temperatures around 64°F (18°C) during the day, dropping to around 52°F (11°C) at night. Clear skies with minimal precipitation expected.'

有关更多信息和示例，请参阅响应格式。有关更多信息和示例，请参阅响应格式。

通过 MCP 将这些文档连接到 Claude、VSCode 等，以获取实时答案。

在 GitHub 上编辑此页面或提交问题。

Get started

Deployment

Core capabilities

Frontend

Protocols

Command line interface

模型

连接弹性

工具

系统提示

提示组装

中间件

预构建中间件

特定于提供商的中间件

自定义中间件

子代理

后端

沙箱

人机协作

技能

记忆

配置文件

结构化输出

​模型

​连接弹性

​工具

​系统提示

​提示组装

​中间件

​预构建中间件

​特定于提供商的中间件

​自定义中间件

​子代理

​后端

​沙箱

​人机协作

​技能

​记忆

​配置文件

​结构化输出

模型

连接弹性

工具

系统提示

提示组装

中间件

预构建中间件

特定于提供商的中间件

自定义中间件

子代理

后端

沙箱

人机协作

技能

记忆

配置文件

结构化输出