定制代理

https://docs.langchain.com/oss/python/deepagents/customization#anthropic

​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\_agentAPI 参考文档。

模型

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

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

OpenAI

pip install -U "langchain[openai]"

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)

Anthropic

pip install -U "langchain[anthropic]"

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)

Gemini

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

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.5-flash")
agent = create_deep_agent(model=model)

工具

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

Anthropic

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,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )


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

系统提示词

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

from deepagents import create_deep_agent

research_instructions = """\
You are an expert researcher. Your job is to conduct \
thorough research, and then write a polished report. \
"""

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    system_prompt=research_instructions,
)

组装提示词

Deep Agents 使用最多四个命名部分构建系统提示，以便调用者提供的指令、SDK 内置的代理指导以及任何特定于模型的配置文件覆盖都能以可预测的优先级共存。如果没有这种分层结构，针对 Claude（例如）优化的配置文件后缀可能会根据system_prompt=调用顺序覆盖您的参数，或者被您的参数覆盖；命名槽位使顺序明确且稳定。

实际上，大多数调用者只会遇到两个槽位：（USER​您自己的system_prompt=​）和BASE​（SDK 默认值）。选择一个带有内置配置文件的模型（目前是 Anthropic 或 OpenAI）会添加一个SUFFIX​。完整的四部分汇编主要在您编写自定义配置文件HarnessProfile或调试配置文件文本的显示位置时才有用。

四个组成部分（每个部分都可能缺失）：

顺序始终为​​USER​​ ->（​​BASE​​或​​CUSTOM​​ ）->​​SUFFIX​​，以空行连接\n\n。以下是两个不变式：

1. ​​USER​​始终位于最前面。 呼叫者的文本优先于任何 SDK 或配置文件内容，因此无论选择哪个模型，角色/指令都优先显示。
2. ​​SUFFIX​​始终位于末尾。 个人资料后缀最靠近对话历史记录，模型调优指导最可靠地作用于此。

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

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

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    system_prompt="You are a customer-support agent for ACME Corp.",
)
# Final = USER + BASE + SUFFIX
#       = "You are a customer-support agent for ACME Corp."
#         + "\n\n"
#         + BASE_AGENT_PROMPT
#         + "\n\n"
#         + <Claude-specific guidance>

中间件

Deep Agents 支持任何中间件，包括下面列出的内置中间件、LangChain 的预构建中间件、提供商特定的中间件以及您自己编写的自定义中间件。将中间件传递给middleware​参数create_deep_agent。默认情况下，深度代理可以访问以下中间件：

• ​TodoListMiddleware跟踪和管理待办事项列表，以组织代理任务和工作
• ​FilesystemMiddleware处理文件系统操作，例如读取、写入和浏览目录。
• ​SubAgentMiddleware生成并协调子代理，以便将任务委派给专门的代理。
• ​SummarizationMiddleware当对话过长时，会精简消息历史记录，使其保持在上下文限制范围内。
• ​AnthropicPromptCachingMiddleware：在使用人格模型时自动减少冗余标记处理
• ​PatchToolCallsMiddleware：自动消息历史记录修复工具调用在接收结果前被中断或取消的情况。

如果您使用内存、技能或人机交互，则还包含以下中间件：

• ​MemoryMiddleware​memory：当提供参数时，跨会话持久化和检索对话上下文。
• ​SkillsMiddleware​skills：当提供参数时启用自定义技能
• ​HumanInTheLoopMiddlewareinterruptOn：在提供论据时，在指定点暂停以等待人工审核或输入。

预构建中间件

LangChain 提供了额外的预构建中间件，允许您添加各种功能，例如重试、回退或个人身份信息 (PII) 检测。有关更多信息，请参阅预构建中间件。该deepagents​库还提供了一项功能create\_summarization\_tool\_middleware​，使代理能够在合适的时机（例如任务间隙）触发摘要，而不是按照固定的词元间隔触发。更多详情，请参阅“摘要”部分。

提供商特定的中间件

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

自定义中间件

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

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


@tool
def get_weather(city: str) -> str:
    """Get the weather in a city."""
    return f"The weather in {city} is sunny."


call_count = [0]  # Use list to allow modification in nested function


@wrap_tool_call
def log_tool_calls(request, handler):
    """Intercept and log every tool call - demonstrates cross-cutting concern."""
    call_count[0] += 1
    tool_name = request.name if hasattr(request, "name") else str(request)

    print(f"[Middleware] Tool call #{call_count[0]}: {tool_name}")
    print(f"[Middleware] Arguments: {request.args if hasattr(request, 'args') else 'N/A'}")

    # Execute the tool call
    result = handler(request)

    # Log the result
    print(f"[Middleware] Tool call #{call_count[0]} completed")

    return result


agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[get_weather],
    middleware=[log_tool_calls],
)

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

from langchain.agents.middleware import AgentMiddleware


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

    def before_agent(self, state, runtime):
        return {"x": state.get("x", 0) + 1}  # Update graph state instead

不​要这样做：

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

    def before_agent(self, state, runtime):
        self.x += 1  # Mutation causes race conditions

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

解释器

使用解释器可以添加一个eval在限定作用域的 QuickJS 运行时环境中运行 JavaScript 的工具。当代理需要以编程方式组合工具、批量处理任务、处理代码错误或在无需完整 shell 环境的情况下转换结构化数据时，解释器非常有用。谷歌

from deepagents import create_deep_agent
from langchain_quickjs import CodeInterpreterMiddleware

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    middleware=[CodeInterpreterMiddleware()],
)

有关设置、程序化工具调用、解释器技能和限制，请参阅解释器。

次级代理商

为了隔离细节工作并避免上下文臃肿，请使用子代理：

import os
from typing import Literal

from deepagents import create_deep_agent
from tavily import TavilyClient

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,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )


research_subagent = {
    "name": "research-agent",
    "description": "Used to research more in depth questions",
    "system_prompt": "You are a great researcher",
    "tools": [internet_search],
    "model": "openai:gpt-5.4",  # Optional override, defaults to main agent model
}
subagents = [research_subagent]

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    subagents=subagents,
)

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

后端

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

状态后端

存储在状态中的线程作用域文件系统后端langgraph。文件在线程内跨回合保留（通过检查点），但不会在线程之间共享。

from deepagents import create_deep_agent
from deepagents.backends import StateBackend

# By default we provide a StateBackend
agent = create_deep_agent(model="google_genai:gemini-3.5-flash")

# Under the hood, it looks like
agent2 = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    backend=StateBackend(),
)

文件系统后端

本地计算机的文件系统。

此后端授予代理直接文件系统读/写权限。请谨慎使用，并仅在合适的环境中使用。更多信息，请参阅[此处] FilesystemBackend。

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
)

使用 .​ 标签包裹FilesystemBackend​代码，CompositeBackend​以防止内部代理数据（卸载的工具结果、对话历史记录）与项目文件一起写入磁盘。请参阅推荐的模式。

本地Shell后端

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

此后端授予代理程序直接对主机文件系统进行读/写访问以及不受限制的 shell 执行权限。请极其谨慎地使用，并且仅在合适的环境中使用。更多信息，请参阅[此处] LocalShellBackend。

from deepagents import create_deep_agent
from deepagents.backends import LocalShellBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    backend=LocalShellBackend(root_dir=".", virtual_mode=True, env={"PATH": "/usr/bin:/bin"}),
)

商店后端

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

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

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    backend=StoreBackend(
        namespace=lambda rt: (rt.server_info.user.identity,),
    ),
    store=InMemoryStore(),  # Good for local dev; omit for LangSmith Deployment
)

部署到LangSmith Deployment时，请省略该store参数。平台会自动为您的代理配置一个存储。

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

ContextHub后端

LangSmith Hub 代码库中的持久文件系统存储。

from deepagents import create_deep_agent
from deepagents.backends import ContextHubBackend

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    backend=ContextHubBackend("my-agent"),
)

更多详情请参见ContextHubBackend。

复合后端

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

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.5-flash",
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(namespace=lambda _rt: ("memories",)),
        },
    ),
    store=InMemoryStore(),  # Store passed to create_deep_agent, not backend
)

更多信息请参见后端。

沙盒

沙箱是一种专门的后端，它在隔离的环境中运行代理代码，拥有自己的文件系统和execute​shell 命令工具。如果您希望深度代理在不更改本地计算机任何内容的情况下写入文件、安装依赖项和运行命令，请使用沙箱后端。backend您可以通过在创建深度代理时传递沙箱后端来配置沙箱：

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

人机交互

某些工具操作可能涉及敏感信息，需要人工审批才能执行。您可以为每个工具配置审批流程：

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


@tool
def remove_file(path: str) -> str:
    """Delete a file from the filesystem."""
    return f"Deleted {path}"


@tool
def fetch_file(path: str) -> str:
    """Read a file from the filesystem."""
    return f"Contents of {path}"


@tool
def notify_email(to: str, subject: str, body: str) -> str:
    """Send an email."""
    return f"Sent email to {to}"


# Checkpointer is REQUIRED for human-in-the-loop
checkpointer = MemorySaver()

agent = create_deep_agent(
    model="google_genai:gemini-3.5-flash",
    tools=[remove_file, fetch_file, notify_email],
    interrupt_on={
        "remove_file": True,  # Default: approve, edit, reject, respond
        "fetch_file": False,  # No interrupts needed
        "notify_email": {"allowed_decisions": ["approve", "reject"]},  # No editing
    },
    checkpointer=checkpointer,  # Required!
)

您可以在工具调用时以及工具调用内部为代理和子代理配置中断。有关更多信息，请参阅“人机交互”。

技能

您可以使用技能为深度代理赋予新的能力和专业知识。工具通常涵盖底层功能，例如原生文件系统操作或规划，而技能则可以包含完成任务的详细说明、参考信息和其他资源，例如模板。只有当代理确定该技能对当前提示有用时，才会加载这些文件。这种渐进式披露减少了代理在启动时需要考虑的令牌和上下文数量。例如技能，请参阅深度代理示例技能。要向深度代理添加技能，请将它们作为参数传递给create_deep_agent：

记忆

使用AGENTS.md​文件为你的深度代理提供额外的上下文信息。memory创建深度代理时，您可以将一个或多个文件路径传递给参数：

Profile 配置文件

接口配置文件是一个可重用的、针对特定模型的配置包，create_deep_agent​当选择匹配的模型时会自动应用。如果您希望系统行为遵循模型本身而非调用站点，例如针对 Claude 指令风格优化的系统提示符后缀、为 GPT 重写的工具描述，或者仅在特定提供程序下才有意义的额外中间件，那么配置文件就是理想之选。单个配置文件可以包含：自定义基本系统提示（base_system_prompt​），附加后缀（system_prompt_suffix），工具描述覆盖，要排除的工具或中间件，要注入的其他中间件，以及对自动添加的通用子代理的编辑。

from deepagents import HarnessProfile, register_harness_profile

# Append a system-prompt suffix whenever gpt-5.4 is selected.
register_harness_profile(
    "openai:gpt-5.4",
    HarnessProfile(system_prompt_suffix="Respond in under 100 words."),
)

请参阅“配置文件”了解注册密钥、合并语义和插件打包信息。此外，还有一个更精简的配套 API，即提供程序配置文件，其中包含提供程序的包模型构建参数（API 密钥、超时、重试设置）。

结构化输出

深度代理支持结构化输出。您可以通过将所需的结构化输出模式作为response_format​参数传递给调用来设置create_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,
):
    """Run a web search"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )


class WeatherReport(BaseModel):
    """A structured weather report with current conditions and forecast."""
    location: str = Field(description="The location for this weather report")
    temperature: float = Field(description="Current temperature in Celsius")
    condition: str = Field(
        description="Current weather condition (e.g., sunny, cloudy, rainy)"
    )
    humidity: int = Field(description="Humidity percentage")
    wind_speed: float = Field(description="Wind speed in km/h")
    forecast: str = Field(description="Brief forecast for the next 24 hours")


agent = create_deep_agent(
    model=model,
    response_format=WeatherReport,
    tools=[internet_search],
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "What's the weather like in San Francisco?",
            }
        ]
    }
)

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.'

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

预组装

​create_deep_agent​在 之上预组装中间件堆栈create\_agent​。要构建完全自定义的代理（精确选择要包含的功能），请参阅配置框架。

‍