围绕您的目标构建框架。 create_deep_agent 为您提供了一个生产就绪的基础：将其连接到您的数据、塑造其行为，并添加您的用例所需的功能。

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    system_prompt="You are a helpful assistant.",
    tools=[search, fetch_url],
    memory=["./AGENTS.md"],
    skills=["./skills/"],
)

完整参数列表请参阅 create_deep_agent API 参考文档。如需从头编写完全自定义的框架，请参阅 配置框架 或按照分步指南 从头构建 deep agent guide.

模型

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

工具

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

MCP 工具

安装 langchain-mcp-adapters 以连接到 MCP 服务器：

pip install langchain-mcp-adapters

from langchain_mcp_adapters.client import MultiServerMCPClient
from deepagents import create_deep_agent

async def main():
    async with MultiServerMCPClient(
        {
            "my_server": {
                "transport": "http",
                "url": "http://localhost:8000/mcp",
            }
        }
    ) as client:
        tools = await client.get_tools()

        agent = create_deep_agent(
            model="openai:gpt-5.5",
            tools=tools,
        )

        result = await agent.ainvoke(
            {"messages": [{"role": "user", "content": "Use the MCP server to help me."}]},
            config={"configurable": {"thread_id": "1"}},
        )

asyncio.run(main())

有关详细配置选项，包括 stdio 服务器、OAuth 身份验证、工具过滤和状态会话，请参阅完整的 MCP 指南.

系统提示词

Deep Agents 附带内置系统提示词。深度代理的价值来自 SDK 在模型之上提供的编排层——规划、虚拟文件系统工具和子代理——模型需要知道这些存在以及何时使用它们。内置提示词教代理如何使用这些脚手架，这样您就不必为每个项目重新推导它；通过 配置文件 或您自己的 system_prompt= 而不是逐字复制它来调整。

当中间件添加特殊工具（如文件系统工具）时，它会将其追加到系统提示词中。

每个深度代理还应包含一个针对其特定用例的自定义系统提示词：

提示词组装

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

实际上，大多数调用者只会遇到两个槽： USER （你的 system_prompt=）和 BASE （SDK 默认值）。使用内置配置文件选择模型——目前是 Anthropic 或 OpenAI——会添加一个 SUFFIX。完整的四部分组合主要与你创作自定义 HarnessProfile 或调试为什么配置文件的文本出现在特定位置有关。

四个命名部分（每个都可能不存在）：

顺序始终是 **USER -> (BASE or CUSTOM) -> SUFFIX**，用空行连接（\n\n）。两个不变量随之而来：

1. **USER 始终位于最前面。** The caller's text precedes any SDK or profile content, so persona/instructions take precedence regardless of which model is selected.
2. **SUFFIX 始终位于最后面。** 配置文件后缀最接近对话历史，模型调整指导最可靠地落地。

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

工作示例——内置配置文件（Anthropic、OpenAI）仅包含一个 system_prompt_suffix，因此典型调用落在 str + - + ✓ row:

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"
#         + 

        register_harness_profile(
            "anthropic",
            HarnessProfile(
                base_system_prompt="You are ACME's support orchestrator.",  # main agent
                general_purpose_subagent=GeneralPurposeSubagentProfile(
                    system_prompt="You are a research subagent. Cite sources.",  # GP subagent
                ),
                system_prompt_suffix="Always think step by step.",
            ),
        )
        

中间件

Deep Agents 支持任何 中间件，包括下面列出的内置中间件、来自 LangChain 的预构建中间件、提供商特定中间件以及您自己编写的自定义中间件。

将中间件传递给 middleware 的 create_deep_agent参数。自定义中间件在 PatchToolCallsMiddleware 之后的 默认堆栈中追加.

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

默认堆栈（主代理）

从第一个到最后一个：

1. TodoListMiddleware：跟踪和管理待办列表，用于组织代理任务和工作。
2. SkillsMiddleware：仅在您传递 skills时注入 **紧随其后** 待办事项中间件和 **在** 文件系统中间件之前，以便技能元数据在文件工具运行之前可用。
3. FilesystemMiddleware: 处理文件系统操作，如读取、写入和浏览目录。当你传递 permissions时，文件系统权限强制执行也包含在此处，以便它可以评估代理可能调用的每个工具。
4. SubAgentMiddleware: 生成并协调子代理，用于将任务委托给专业代理。
5. SummarizationMiddleware: 当对话变长时，收缩消息历史以保持在上下文限制内（通过 @[create_summarization_中间件]）。
6. PatchToolCallsMiddleware: 修复消息历史中悬空的工具调用，当运行在中断后恢复或收到格式错误的工具调用参数时。运行于 **之前** Anthropic 提示缓存和下面的尾部堆栈。
7. AsyncSubAgentMiddleware: 仅当你配置异步子代理时。
8. **你的中间件参数**: 你作为 middleware 参数传递的可选中间件会追加到此处（Patch 之后，尾部堆栈之前）。
9. **Harness 配置文件 extras**: 来自解析后模型配置文件的特定于提供商的中间件（如果有）。
10. **排除工具过滤**: 当 harness 配置文件列出排除的工具时，中间件会从代理中移除这些工具。
11. **提示缓存** (AnthropicPromptCachingMiddleware 和 BedrockPromptCachingMiddleware): 两者始终注册并在 **之后** Patch 和你的中间件之后运行，以便缓存前缀与实际发送给模型的内容匹配。每个都在不支持的模型上无操作（unsupported_model_behavior="ignore"），因此 Anthropic 中间件应用于 Anthropic 模型，Bedrock 中间件应用于支持缓存的 AWS Bedrock 模型。
12. MemoryMiddleware: 仅当你传递 memory.

1. HumanInTheLoopMiddleware: 仅当你传递 interrupt_on时。在配置的工具调用处暂停以等待人工批准或输入。

默认堆栈（同步子代理）

内置 **general-purpose** 子代理和每个声明式同步 SubAgent 图使用的堆栈在代码中构建。它在总体结构上与主代理匹配（待办事项列表、文件系统、摘要、Patch、配置文件额外项、Anthropic 和 Bedrock 缓存、可选权限），但在两个方面有所不同： create_deep_agent 技能在这些内部代理上运行

• 之后（在主代理上，当 @[PatchToolCallsMiddleware设置时，技能运行在文件系统中间件之前）。 **之前** 在子代理图中没有 skills 工具（只有父代理暴露
• - 工具）。 **no** @[SubAgentMiddleware当声明式子代理设置 task 时，该值被转发到

以获取子代理，它会为已配置的工具调用连接人工介入处理。 interrupt_on内置 create_agent 子代理和每个声明式同步

预构建中间件

LangChain 暴露了额外的预构建中间件，让您可以添加各种功能，例如重试、兜底或 PII 检测。请参阅 预构建中间件 了解更多。

该 deepagents 库还暴露了 create_summarization_tool_middleware，使代理能够在适当的时机触发摘要——例如在任务之间——而不是在固定 token 间隔时触发。详细请参阅 摘要.

特定提供商中间件

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

自定义中间件

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

解释器

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

有关设置、编程工具调用、子代理编排和限制，请参阅 解释器.

子代理

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

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

后端

深度代理的工具可以使用虚拟文件系统来存储、访问和编辑文件。默认情况下，深度代理使用 StateBackend.

如果您正在使用 技能 or 记忆，则必须在创建代理之前将预期的技能或记忆文件添加到后端。

更多信息，请参阅 后端.

沙箱

沙箱是专用的 后端 ，在隔离环境中运行代理代码，拥有自己的文件系统和 execute 用于 shell 命令的工具。 当您希望深度代理写入文件、安装依赖项和运行命令而不更改本地计算机上的任何内容时，请使用沙箱后端。

您可以通过在创建深度代理时传递沙箱后端来配置沙箱： backend 创建深度代理时：

更多信息，请参阅 沙箱.

Human-in-the-loop

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

您可以配置在工具调用时以及工具调用内部对代理和子代理进行中断。 更多信息，请参阅 Human-in-the-loop.

技能

您可以使用 技能 为您的深度代理提供新的能力和专业知识。 虽然 工具 倾向于覆盖较低级别的功能（如原生文件系统操作或规划），而技能可以包含关于如何完成任务的详细指令、参考信息和其他资源（如模板）。 这些文件仅在代理确定该技能对当前提示有用时才由代理加载。 这种渐进式披露减少了代理启动时需要考虑的令牌数量和上下文。

例如技能，请参阅 深度代理示例技能.

要向深度代理添加工具，请将其作为参数传递给 create_deep_agent:

记忆

使用 AGENTS.md 文件 为您的深度代理提供额外的上下文。

您可以在创建深度代理时将一个或多个文件路径传递给 memory 参数：

配置文件

A Harness 配置文件 是一个可重用的、按模型配置的资源包，当 create_deep_agent 选择匹配模型时自动应用。当您希望行为跟随模型而不是调用站点时，配置文件是合适的工具，例如针对 Claude 指令风格调优的系统提示后缀、为 GPT 重写的工具描述，或仅对特定提供商有意义的额外中间件。

单个配置文件可以包含：自定义基础系统提示（base_system_prompt）、追加的后缀（system_prompt_suffix）、工具描述覆盖、要排除的工具或中间件、要注入的额外中间件，以及对自动添加的通用子代理的编辑。

请参阅 配置文件 了解注册密钥、合并语义和插件打包。一个更窄的配套 API， 提供商配置文件，打包提供商的模型构建参数（API 密钥、超时、重试设置）。

结构化输出

深度代理支持 结构化输出. 您可以通过将其作为 response_format 参数传递给 create_deep_agent(). 调用来设置所需的结构化输出模式。当模型生成结构化数据时，它会被捕获、验证并返回在深度代理状态的 'structured_响应' 键中。

更多信息和示例，请参阅 响应格式.

高级

create_deep_agent 在 @ 之上预组装中间件堆栈create_agent。要构建完全自定义的智能体——选择要包含的确切功能——请参阅 [配置测试工具.