> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 自定义 Deep Agents

> 了解如何使用系统提示、工具、子代理等自定义 Deep Agents

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

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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`](https://reference.langchain.com/python/deepagents/graph/create_deep_agent) API 参考。

## 模型

传递一个 `provider:model` 格式的 `model` 字符串，或一个已初始化的模型实例。有关所有提供商，请参阅[支持的模型](/oss/python/deepagents/models#supported-models)；有关经过测试的推荐模型，请参阅[推荐模型](/oss/python/deepagents/models#suggested-models)。

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

<Tabs>
  <Tab title="OpenAI">
    👉 阅读 [OpenAI 聊天模型集成文档](/oss/python/integrations/chat/openai/)

    ```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    pip install -U "langchain[openai]"
    ```

    <CodeGroup>
      ```python 默认参数 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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
      ```

      ```python init_chat_model theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```

      ```python 模型类 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Anthropic">
    👉 阅读 [Anthropic 聊天模型集成文档](/oss/python/integrations/chat/anthropic/)

    ```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    pip install -U "langchain[anthropic]"
    ```

    <CodeGroup>
      ```python 默认参数 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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
      ```

      ```python init_chat_model theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```

      ```python 模型类 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Azure">
    👉 阅读 [Azure 聊天模型集成文档](/oss/python/integrations/chat/azure_chat_openai/)

    ```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    pip install -U "langchain[openai]"
    ```

    <CodeGroup>
      ```python 默认参数 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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
      ```

      ```python init_chat_model theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```

      ```python 模型类 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Google Gemini">
    👉 阅读 [Google GenAI 聊天模型集成文档](/oss/python/integrations/chat/google_generative_ai/)

    ```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    pip install -U "langchain[google-genai]"
    ```

    <CodeGroup>
      ```python 默认参数 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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
      ```

      ```python init_chat_model theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```

      ```python 模型类 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="AWS Bedrock">
    👉 阅读 [AWS Bedrock 聊天模型集成文档](/oss/python/integrations/chat/bedrock/)

    ```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    pip install -U "langchain[aws]"
    ```

    <CodeGroup>
      ```python 默认参数 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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
      ```

      ```python init_chat_model theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```

      ```python 模型类 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="HuggingFace">
    👉 阅读 [HuggingFace 聊天模型集成文档](/oss/python/integrations/chat/huggingface/)

    ```shell theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    pip install -U "langchain[huggingface]"
    ```

    <CodeGroup>
      ```python 默认参数 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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
      ```

      ```python init_chat_model theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```

      ```python 模型类 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="其他">
    传入任何[支持的模型字符串](/oss/python/deepagents/models#supported-models)，或一个已初始化的模型实例：

    <CodeGroup>
      ```python 模型字符串 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      from deepagents import create_deep_agent

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

      ```python init_chat_model theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      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)
      ```

      ```python 模型类 theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      from langchain_<provider> import Chat<Provider>
      from deepagents import create_deep_agent

      model = Chat<Provider>(model="model-name")
      agent = create_deep_agent(model=model)
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### 连接弹性

LangChain 聊天模型会自动使用指数退避策略重试失败的 API 请求。默认情况下，模型会为网络错误、速率限制（429）和服务器错误（5xx）重试最多 **6 次**。客户端错误（如 401 未授权或 404 未找到）不会重试。

您可以在创建模型时调整 `max_retries` 参数，以根据您的环境调整此行为：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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,     # 对于慢速连接增加超时时间
    ),
)
```

<Tip>
  对于在不可靠网络上运行的长时间代理任务，考虑将 `max_retries` 增加到 10-15，并配合使用[检查点](/oss/python/langgraph/persistence)，以便在失败时保留进度。
</Tip>

## 工具

除了用于规划、文件管理和子代理生成的[内置工具](/oss/python/deepagents/overview#core-capabilities)外，您还可以提供自定义工具：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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 在模型之上提供的编排层——规划、虚拟文件系统工具和子代理——模型需要知道这些工具的存在以及何时使用它们。内置提示教会代理如何使用这个脚手架，这样您就不必为每个项目重新推导它；通过[配置文件](/oss/python/deepagents/profiles#harness-profiles)或您自己的 `system_prompt=` 来调整它，而不是逐字复制。

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

每个 Deep Agent 还应包含一个针对其特定用例的自定义系统提示：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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 的内置代理指导以及任何特定于模型的[配置文件](/oss/python/deepagents/profiles)覆盖可以以可预测的优先级共存。如果没有这种分层，为 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`](/oss/python/deepagents/profiles#harness-profiles)   | 当匹配的配置文件设置它时，完全替换 `BASE`。       |
| `SUFFIX` | [`HarnessProfile.system_prompt_suffix`](/oss/python/deepagents/profiles#harness-profiles) | 当匹配的配置文件设置它时，最后附加。              |

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

1. **`USER` 始终在最前面。** 调用者的文本优先于任何 SDK 或配置文件内容，因此无论选择哪个模型，角色/指令都具有优先权。
2. **`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` + `-` + `✓` 行：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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 特定的指导>
```

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

<AccordionGroup>
  <Accordion title="子代理提示">
    相同的覆盖规则适用于声明式[子代理](/oss/python/deepagents/subagents)——每个子代理根据**其自身模型**重新运行配置文件解析，然后将解析后的配置文件的 `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` 的配置文件将*完全替换*已编写的提示，因此请谨慎使用该字段。
  </Accordion>

  <Accordion title="通用子代理提示">
    自动添加的[通用子代理](/oss/python/deepagents/subagents#the-general-purpose-subagent)遵循相同的覆盖规则，但多了一层：GP 基础提示解析为 **`general_purpose_subagent.system_prompt`（如果已设置）-> `HarnessProfile.base_system_prompt`（如果已设置）-> SDK GP 默认值**。配置文件后缀无论如何都会叠加在上面。

    两个覆盖字段都可以携带基础提示替换，但它们不可互换。`general_purpose_subagent.system_prompt` 是 GP 特定的配置；`base_system_prompt` 是主要针对主代理的全局覆盖。当两者都设置时，**GP 特定的意图对 GP 子代理生效**，因此同时调整这两个字段的用户永远不会看到他们的 GP 覆盖被静默丢弃：

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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 默认值。
  </Accordion>
</AccordionGroup>

## 中间件

默认情况下，Deep Agents 可以访问以下[中间件](/oss/python/langchain/middleware/overview)：

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

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

* [`MemoryMiddleware`](https://reference.langchain.com/python/deepagents/middleware/memory/MemoryMiddleware)：当提供 `memory` 参数时，跨会话持久化和检索对话上下文
* [`SkillsMiddleware`](https://reference.langchain.com/python/deepagents/middleware/skills/SkillsMiddleware)：当提供 `skills` 参数时启用自定义技能
* `HumanInTheLoopMiddleware`：当提供 `interruptOn` 参数时，在指定点暂停以进行人工批准或输入

### 预构建中间件

LangChain 提供了额外的预构建中间件，允许您添加各种功能，例如重试、回退或 PII 检测。有关更多信息，请参阅[预构建中间件](/oss/python/langchain/middleware/built-in)。

`deepagents` 库还提供了 [create\_summarization\_tool\_middleware](https://reference.langchain.com/python/deepagents/middleware/summarization/create_summarization_tool_middleware)，使代理能够在合适的时机（例如任务之间）触发摘要，而不是在固定的令牌间隔。有关更多详细信息，请参阅[摘要](/oss/python/deepagents/context-engineering#summarization)。

### 特定于提供商的中间件

有关针对特定 LLM 提供商优化的特定于提供商的中间件，请参阅[官方集成](/oss/python/integrations/middleware#official-integrations)和[社区集成](/oss/python/integrations/middleware#community-integrations)。

### 自定义中间件

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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],
)
```

<Warning>
  **初始化后不要修改属性**

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

  **请这样做：**

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  class CustomMiddleware(AgentMiddleware):
      def __init__(self):
          pass

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

  **不要这样做：**

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  class CustomMiddleware(AgentMiddleware):
      def __init__(self):
          self.x = 1

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

  就地修改，例如在 `before_agent` 中修改 `self.x` 或在钩子中更改其他共享值，可能导致细微的错误和竞态条件，因为许多操作并发运行（子代理、并行工具以及在不同线程上的并行调用）。

  有关使用自定义属性扩展状态的完整详细信息，请参阅[自定义中间件 - 自定义状态模式](/oss/python/langchain/middleware/custom#custom-state-schema)。
  如果您必须在自定义中间件中使用修改，请考虑当子代理、并行工具或并发代理调用同时运行时会发生什么。
</Warning>

## 子代理

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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
)
```

有关更多信息，请参阅[子代理](/oss/python/deepagents/subagents)。

{/* ## 上下文 - 您可以在运行之间持久化代理状态以存储用户 ID 等信息。 */}

## 后端

Deep Agent 的工具可以利用虚拟文件系统来存储、访问和编辑文件。默认情况下，Deep Agents 使用 [`StateBackend`](https://reference.langchain.com/python/deepagents/backends/state/StateBackend)。

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

<Tabs>
  <Tab title="StateBackend">
    存储在 `langgraph` 状态中的临时文件系统后端。

    此文件系统仅在\_单个线程\_内持久化。

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    # 默认情况下我们提供一个 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()
    )
    ```
  </Tab>

  <Tab title="FilesystemBackend">
    本地机器的文件系统。

    <Warning>
      此后端授予代理直接的文件系统读/写访问权限。
      请谨慎使用，仅在适当的环境中使用。
      有关更多信息，请参阅 [`FilesystemBackend`](/oss/python/deepagents/backends#filesystembackend-local-disk)。
    </Warning>

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    from deepagents.backends import FilesystemBackend

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

  <Tab title="LocalShellBackend">
    一个直接在主机上执行 shell 的文件系统。提供文件系统工具以及用于运行命令的 `execute` 工具。

    <Warning>
      此后端授予代理直接的文件系统读/写访问权限**以及**在主机上不受限制的 shell 执行权限。
      请极其谨慎地使用，仅在适当的环境中使用。
      有关更多信息，请参阅 [`LocalShellBackend`](/oss/python/deepagents/backends#localshellbackend-local-shell)。
    </Warning>

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"})
    )
    ```
  </Tab>

  <Tab title="StoreBackend">
    一个提供\_跨线程持久化\_长期存储的文件系统。

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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 时请省略此参数
    )
    ```

    <Note>
      部署到 [LangSmith Deployment](/langsmith/deployment) 时，请省略 `store` 参数。平台会自动为您的智能体配置存储。
    </Note>

    <Tip>
      `namespace` 参数控制数据隔离。对于多用户部署，始终设置[命名空间工厂](/oss/python/deepagents/backends#namespace-factories)以按用户或租户隔离数据。
    </Tip>
  </Tab>

  <Tab title="CompositeBackend">
    一个灵活的后端，您可以在文件系统中指定不同的路由指向不同的后端。

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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
    )
    ```
  </Tab>
</Tabs>

有关更多信息，请参阅[后端](/oss/python/deepagents/backends)。

### 沙箱

沙箱是专门的[后端](/oss/python/deepagents/backends)，在隔离环境中运行代理代码，拥有自己的文件系统和用于 shell 命令的 `execute` 工具。
当您希望 Deep Agent 写入文件、安装依赖项和运行命令而不更改本地机器上的任何内容时，请使用沙箱后端。

您可以通过在创建 Deep Agent 时将沙箱后端传递给 `backend` 来配置沙箱：

<Tabs>
  <Tab title="Modal">
    <CodeGroup>
      ```bash pip theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      pip install langchain-modal
      ```

      ```bash uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      uv add langchain-modal
      ```
    </CodeGroup>

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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()
    ```
  </Tab>

  <Tab title="Runloop">
    <CodeGroup>
      ```bash pip theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      pip install langchain-runloop
      ```

      ```bash uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      uv add langchain-runloop
      ```
    </CodeGroup>

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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()
    ```
  </Tab>

  <Tab title="Daytona">
    <CodeGroup>
      ```bash pip theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      pip install langchain-daytona
      ```

      ```bash uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      uv add langchain-daytona
      ```
    </CodeGroup>

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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()
    ```
  </Tab>

  <Tab title="LangSmith">
    <Note>
      LangSmith 沙箱目前处于私有测试阶段。
    </Note>

    <CodeGroup>
      ```bash pip theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      pip install "langsmith[sandbox]"
      ```

      ```bash uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      uv add "langsmith[sandbox]"
      ```
    </CodeGroup>

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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)
    ```
  </Tab>
</Tabs>

有关更多信息，请参阅[沙箱](/oss/python/deepagents/sandboxes)。

## 人机协作

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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  # 必需！
)
```

您可以为代理和子代理配置在工具调用时以及从工具调用内部进行中断。
有关更多信息，请参阅[人机协作](/oss/python/deepagents/human-in-the-loop)。

## 技能

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

有关示例技能，请参阅 [Deep Agents 示例技能](https://github.com/langchain-ai/deepagentsjs/tree/main/examples/skills)。

要将技能添加到您的 Deep Agent，请将它们作为参数传递给 `create_deep_agent`：

<Tabs>
  <Tab title="StateBackend">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"}},
    )
    ```
  </Tab>

  <Tab title="StoreBackend">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"}},
    )
    ```
  </Tab>

  <Tab title="FilesystemBackend">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"}},
    )
    ```
  </Tab>
</Tabs>

## 记忆

使用 [`AGENTS.md` 文件](https://agents.md/)为您的 Deep Agent 提供额外的上下文。

您可以在创建 Deep Agent 时将一个或多个文件路径传递给 `memory` 参数：

<Tabs>
  <Tab title="StateBackend">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"}},
    )
    ```
  </Tab>

  <Tab title="StoreBackend">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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"}},
    )
    ```
  </Tab>

  <Tab title="FilesystemBackend">
    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    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,  # 必需！
    )
    ```
  </Tab>
</Tabs>

## 配置文件

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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from deepagents import HarnessProfile, register_harness_profile

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

有关注册键、合并语义和插件打包，请参阅[配置文件](/oss/python/deepagents/profiles)。一个更窄的配套 API，[提供商配置文件](/oss/python/deepagents/profiles#provider-profiles)，打包了提供商的模型构造参数。

## 结构化输出

Deep Agents 支持[结构化输出](/oss/python/langchain/structured-output)。
您可以通过将所需的结构化输出模式作为 `response_format` 参数传递给 `create_deep_agent()` 调用来设置它。
当模型生成结构化数据时，它会被捕获、验证，并在 Deep Agent 状态的 'structured\_response' 键中返回。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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.'
```

有关更多信息和示例，请参阅[响应格式](/oss/python/langchain/structured-output#response-format)。
有关更多信息和示例，请参阅[响应格式](/oss/python/langchain/structured-output#response-format)。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [通过 MCP 将这些文档](/use-these-docs)连接到 Claude、VSCode 等，以获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/customization.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>