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

# 预构建中间件

> 针对常见智能体用例的预构建中间件

LangChain 和 [Deep Agents](/oss/python/deepagents/overview) 提供了针对常见用例的预构建中间件。每个中间件都已达到生产就绪状态，并可根据您的具体需求进行配置。

## 与提供商无关的中间件

以下中间件可与任何 LLM 提供商配合使用：

| 中间件                                       | 描述                          |
| ----------------------------------------- | --------------------------- |
| [摘要](#摘要)                                 | 在接近令牌限制时自动总结对话历史。           |
| \[Human in the Loop]\(#Human in the Loop) | 暂停执行以等待人工批准工具调用。            |
| [模型调用限制](#模型调用限制)                         | 限制模型调用次数以防止成本过高。            |
| [工具调用限制](#工具调用限制)                         | 通过限制调用次数来控制工具执行。            |
| [模型回退](#模型回退)                             | 当主模型失败时自动回退到备用模型。           |
| [PII 检测](#pii-检测)                         | 检测和处理个人身份信息 (PII)。          |
| [待办事项列表](#待办事项列表)                         | 为智能体配备任务规划和跟踪能力。            |
| [LLM 工具选择器](#llm-工具选择器)                   | 在调用主模型之前使用 LLM 选择相关工具。      |
| [工具重试](#工具重试)                             | 使用指数退避自动重试失败的工具调用。          |
| [模型重试](#模型重试)                             | 使用指数退避自动重试失败的模型调用。          |
| [LLM 工具模拟器](#llm-工具模拟器)                   | 使用 LLM 模拟工具执行以用于测试目的。       |
| [上下文编辑](#上下文编辑)                           | 通过修剪或清除工具使用来管理对话上下文。        |
| [Shell 工具](#shell-工具)                     | 向智能体暴露一个持久的 shell 会话以执行命令。  |
| [文件搜索](#文件搜索)                             | 提供基于文件系统的 Glob 和 Grep 搜索工具。 |
| [文件系统](#文件系统中间件)                          | 为智能体提供用于存储上下文和长期记忆的文件系统。    |
| [子智能体](#子智能体)                             | 添加生成子智能体的能力。                |

### 摘要

在接近令牌限制时自动总结对话历史，保留最近的消息同时压缩较旧的上下文。摘要对于以下情况很有用：

* 超出上下文窗口的长时间运行对话。
* 具有大量历史记录的多轮对话。
* 保留完整对话上下文很重要的应用程序。

**API 参考：** [`SummarizationMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/summarization/SummarizationMiddleware)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[your_weather_tool, your_calculator_tool],
    middleware=[
        SummarizationMiddleware(
            model="gpt-5.4-mini",
            trigger=("tokens", 4000),
            keep=("messages", 20),
        ),
    ],
)
```

<Accordion title="配置选项">
  <Tip>
    `trigger` 和 `keep` 的 `fraction` 条件（如下所示）依赖于聊天模型的[配置文件数据](/oss/python/langchain/models#model-profiles)（如果使用 `langchain>=1.1`）。如果数据不可用，请使用其他条件或手动指定：

    ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    from langchain.chat_models import init_chat_model

    custom_profile = {
        "max_input_tokens": 100_000,
        # ...
    }
    model = init_chat_model("gpt-5.4", profile=custom_profile)
    ```
  </Tip>

  <ParamField body="model" type="string | BaseChatModel" required>
    用于生成摘要的模型。可以是模型标识符字符串（例如，`'openai:gpt-5.4-mini'`）或
    `BaseChatModel` 实例。更多信息请参阅
    [`init_chat_model`](https://reference.langchain.com/python/langchain/chat_models/base/init_chat_model)。
  </ParamField>

  <ParamField body="trigger" type="ContextSize | list[ContextSize] | None">
    触发摘要的条件。可以是：

    * 单个 [`ContextSize`](https://reference.langchain.com/python/langchain/agents/middleware/summarization/ContextSize) 元组（必须满足指定条件）
    * [`ContextSize`](https://reference.langchain.com/python/langchain/agents/middleware/summarization/ContextSize) 元组列表（必须满足任一条件 - OR 逻辑）

    条件应为以下之一：

    * `fraction` (float)：模型上下文大小的比例 (0-1)
    * `tokens` (int)：绝对令牌数
    * `messages` (int)：消息数

    至少必须指定一个条件。如果未提供，摘要将不会自动触发。

    更多信息请参阅 [`ContextSize`](https://reference.langchain.com/python/langchain/agents/middleware/summarization/ContextSize) 的 API 参考。
  </ParamField>

  <ParamField body="keep" type="ContextSize" default="('messages', 20)">
    摘要后保留多少上下文。请精确指定以下之一：

    * `fraction` (float)：保留模型上下文大小的比例 (0-1)
    * `tokens` (int)：保留的绝对令牌数
    * `messages` (int)：保留的最近消息数

    更多信息请参阅 [`ContextSize`](https://reference.langchain.com/python/langchain/agents/middleware/summarization/ContextSize) 的 API 参考。
  </ParamField>

  <ParamField body="token_counter" type="function">
    自定义令牌计数函数。默认为基于字符的计数。
  </ParamField>

  <ParamField body="summary_prompt" type="string">
    用于摘要的自定义提示模板。如果未指定，则使用内置模板。模板应包含 `{messages}`
    占位符，对话历史将插入其中。
  </ParamField>

  <ParamField body="trim_tokens_to_summarize" type="number" default="4000">
    生成摘要时包含的最大令牌数。消息将在摘要前被修剪以适应此限制。
  </ParamField>

  <ParamField body="summary_prefix" type="string" deprecated>
    **已弃用：** 请改用 `summary_prompt` 提供完整提示。
  </ParamField>

  <ParamField body="max_tokens_before_summary" type="number" deprecated>
    **已弃用：** 请改用 `trigger: ("tokens", value)`。触发摘要的令牌阈值。
  </ParamField>

  <ParamField body="messages_to_keep" type="number" deprecated>
    **已弃用：** 请改用 `keep: ("messages", value)`。要保留的最近消息数。
  </ParamField>
</Accordion>

<Accordion title="完整示例">
  摘要中间件监控消息令牌数，并在达到阈值时自动总结较旧的消息。

  **触发条件**控制摘要何时运行：

  * 单个条件对象（必须满足指定条件）
  * 条件数组（必须满足任一条件 - OR 逻辑）
  * 每个条件可以使用 `fraction`（模型上下文大小的比例）、`tokens`（绝对计数）或 `messages`（消息数）

  **保留条件**控制保留多少上下文（请精确指定一个）：

  * `fraction` - 保留模型上下文大小的比例
  * `tokens` - 保留的绝对令牌数
  * `messages` - 保留的最近消息数

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain.agents import create_agent
  from langchain.agents.middleware import SummarizationMiddleware


  # 单个条件：如果令牌数 >= 4000 则触发
  agent = create_agent(
      model="gpt-5.4",
      tools=[your_weather_tool, your_calculator_tool],
      middleware=[
          SummarizationMiddleware(
              model="gpt-5.4-mini",
              trigger=("tokens", 4000),
              keep=("messages", 20),
          ),
      ],
  )

  # 多个条件：如果令牌数 >= 3000 或消息数 >= 6 则触发
  agent2 = create_agent(
      model="gpt-5.4",
      tools=[your_weather_tool, your_calculator_tool],
      middleware=[
          SummarizationMiddleware(
              model="gpt-5.4-mini",
              trigger=[
                  ("tokens", 3000),
                  ("messages", 6),
              ],
              keep=("messages", 20),
          ),
      ],
  )

  # 使用比例限制
  agent3 = create_agent(
      model="gpt-5.4",
      tools=[your_weather_tool, your_calculator_tool],
      middleware=[
          SummarizationMiddleware(
              model="gpt-5.4-mini",
              trigger=("fraction", 0.8),
              keep=("fraction", 0.3),
          ),
      ],
  )
  ```
</Accordion>

### Human in the Loop

暂停智能体执行，以便在工具调用执行前进行人工批准、编辑或拒绝。[Human in the Loop](/oss/python/langchain/human-in-the-loop)对于以下情况很有用：

* 需要人工批准的高风险操作（例如数据库写入、金融交易）。
* 需要人工监督的合规工作流程。
* 人工反馈指导智能体的长时间运行对话。

**API 参考：** [`HumanInTheLoopMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/human_in_the_loop/HumanInTheLoopMiddleware)

<Warning>
  Human in the
  Loop中间件需要一个[检查点](/oss/python/langgraph/persistence#checkpoints)来在中断期间维护状态。
</Warning>

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver


def your_read_email_tool(email_id: str) -> str:
    """模拟通过 ID 读取电子邮件的函数。"""
    return f"Email content for ID: {email_id}"

def your_send_email_tool(recipient: str, subject: str, body: str) -> str:
    """模拟发送电子邮件的函数。"""
    return f"Email sent to {recipient} with subject '{subject}'"

agent = create_agent(
    model="gpt-5.4",
    tools=[your_read_email_tool, your_send_email_tool],
    checkpointer=InMemorySaver(),
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "your_send_email_tool": {
                    "allowed_decisions": ["approve", "edit", "reject"],
                },
                "your_read_email_tool": False,
            }
        ),
    ],
)
```

<Tip>
  有关完整示例、配置选项和集成模式，请参阅[Human in the
  Loop文档](/oss/python/langchain/human-in-the-loop)。
</Tip>

<Callout icon="player-play" iconType="solid">
  观看此[视频指南](https://www.youtube.com/watch?v=SpfT6-YAVPk)演示Human in the
  Loop中间件的行为。
</Callout>

### 模型调用限制

限制模型调用次数以防止无限循环或成本过高。模型调用限制对于以下情况很有用：

* 防止失控的智能体进行过多的 API 调用。
* 对生产部署实施成本控制。
* 在特定调用预算内测试智能体行为。

**API 参考：** [`ModelCallLimitMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/model_call_limit/ModelCallLimitMiddleware)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import ModelCallLimitMiddleware
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="gpt-5.4",
    checkpointer=InMemorySaver(),  # 线程限制所需
    tools=[],
    middleware=[
        ModelCallLimitMiddleware(
            thread_limit=10,
            run_limit=5,
            exit_behavior="end",
        ),
    ],
)
```

<Callout icon="player-play" iconType="solid">
  观看此[视频指南](https://www.youtube.com/watch?v=nJEER0uaNkE)演示模型调用限制中间件的行为。
</Callout>

<Accordion title="配置选项">
  <ParamField body="thread_limit" type="number">
    线程中所有运行的最大模型调用次数。默认为无限制。
  </ParamField>

  <ParamField body="run_limit" type="number">
    单次调用的最大模型调用次数。默认为无限制。
  </ParamField>

  <ParamField body="exit_behavior" type="string" default="end">
    达到限制时的行为。选项：`'end'`（正常终止）或 `'error'`（引发异常）
  </ParamField>
</Accordion>

### 工具调用限制

通过限制工具调用次数来控制智能体执行，可以全局限制所有工具，也可以针对特定工具。工具调用限制对于以下情况很有用：

* 防止对昂贵的外部 API 进行过多调用。
* 限制网络搜索或数据库查询。
* 对特定工具使用实施速率限制。
* 防止智能体循环失控。

**API 参考：** [`ToolCallLimitMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/tool_call_limit/ToolCallLimitMiddleware)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import ToolCallLimitMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool, database_tool],
    middleware=[
        # 全局限制
        ToolCallLimitMiddleware(thread_limit=20, run_limit=10),
        # 特定工具限制
        ToolCallLimitMiddleware(
            tool_name="search",
            thread_limit=5,
            run_limit=3,
        ),
    ],
)
```

<Callout icon="player-play" iconType="solid">
  观看此[视频指南](https://www.youtube.com/watch?v=6gYlaJJ8t0w)演示工具调用限制中间件的行为。
</Callout>

<Accordion title="配置选项">
  <ParamField body="tool_name" type="string">
    要限制的特定工具的名称。如果未提供，限制将应用于**所有全局工具**。
  </ParamField>

  <ParamField body="thread_limit" type="number">
    线程（对话）中所有运行的最大工具调用次数。使用相同线程 ID
    的多次调用会持久化。需要检查点来维护状态。`None` 表示无线程限制。
  </ParamField>

  <ParamField body="run_limit" type="number">
    单次调用（一个用户消息 → 响应周期）的最大工具调用次数。每次新用户消息时重置。`None` 表示无运行限制。

    **注意：** 必须指定 `thread_limit` 或 `run_limit` 中的至少一个。
  </ParamField>

  <ParamField body="exit_behavior" type="string" default="continue">
    达到限制时的行为：

    * `'continue'`（默认）- 用错误消息阻止超出的工具调用，让其他工具和模型继续。模型根据错误消息决定何时结束。
    * `'error'` - 立即引发 `ToolCallLimitExceededError` 异常，停止执行
    * `'end'` - 立即停止执行，并为超出的工具调用提供 `ToolMessage` 和 AI 消息。仅在限制单个工具时有效；如果其他工具有挂起的调用，则引发 `NotImplementedError`。
  </ParamField>
</Accordion>

<Accordion title="完整示例">
  使用以下方式指定限制：

  * **线程限制** - 对话中所有运行的最大调用次数（需要检查点）
  * **运行限制** - 单次调用的最大调用次数（每轮重置）

  退出行为：

  * `'continue'`（默认）- 用错误消息阻止超出的调用，智能体继续
  * `'error'` - 立即引发异常
  * `'end'` - 以 ToolMessage + AI 消息停止（仅限单工具场景）

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain.agents import create_agent
  from langchain.agents.middleware import ToolCallLimitMiddleware


  global_limiter = ToolCallLimitMiddleware(thread_limit=20, run_limit=10)
  search_limiter = ToolCallLimitMiddleware(tool_name="search", thread_limit=5, run_limit=3)
  database_limiter = ToolCallLimitMiddleware(tool_name="query_database", thread_limit=10)
  strict_limiter = ToolCallLimitMiddleware(tool_name="scrape_webpage", run_limit=2, exit_behavior="error")

  agent = create_agent(
      model="gpt-5.4",
      tools=[search_tool, database_tool, scraper_tool],
      middleware=[global_limiter, search_limiter, database_limiter, strict_limiter],
  )
  ```
</Accordion>

### 模型回退

当主模型失败时自动回退到备用模型。模型回退对于以下情况很有用：

* 构建能够处理模型中断的弹性智能体。
* 通过回退到更便宜的模型来优化成本。
* 跨 OpenAI、Anthropic 等的提供商冗余。

**API 参考：** [`ModelFallbackMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/model_fallback/ModelFallbackMiddleware)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import ModelFallbackMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        ModelFallbackMiddleware(
            "gpt-5.4-mini",
            "claude-3-5-sonnet-20241022",
        ),
    ],
)
```

<Callout icon="player-play" iconType="solid">
  观看此[视频指南](https://www.youtube.com/watch?v=8rCRO0DUeIM)演示模型回退中间件的行为。
</Callout>

<Accordion title="配置选项">
  <ParamField body="first_model" type="string | BaseChatModel" required>
    当主模型失败时尝试的第一个备用模型。可以是模型标识符字符串（例如，`'openai:gpt-5.4-mini'`）或
    `BaseChatModel` 实例。
  </ParamField>

  <ParamField body="*additional_models" type="string | BaseChatModel">
    如果之前的模型失败，则按顺序尝试的其他备用模型
  </ParamField>
</Accordion>

### PII 检测

使用可配置的策略检测和处理对话中的个人身份信息 (PII)。PII 检测对于以下情况很有用：

* 具有合规要求的医疗和金融应用程序。
* 需要清理日志的客户服务智能体。
* 任何处理敏感用户数据的应用程序。

**API 参考：** [`PIIMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/pii/PIIMiddleware)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        PIIMiddleware("email", strategy="redact", apply_to_input=True),
        PIIMiddleware("credit_card", strategy="mask", apply_to_input=True),
    ],
)
```

#### 自定义 PII 类型

您可以通过提供 `detector` 参数来创建自定义 PII 类型。这允许您检测超出内置类型的、特定于您用例的模式。

**创建自定义检测器的三种方式：**

1. **正则表达式模式字符串** - 简单的模式匹配

2. **自定义函数** - 带有验证的复杂检测逻辑

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware
import re


# 方法 1：正则表达式模式字符串
agent1 = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        PIIMiddleware(
            "api_key",
            detector=r"sk-[a-zA-Z0-9]{32}",
            strategy="block",
        ),
    ],
)

# 方法 2：编译后的正则表达式模式
agent2 = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        PIIMiddleware(
            "phone_number",
            detector=re.compile(r"\+?\d{1,3}[\s.-]?\d{3,4}[\s.-]?\d{4}"),
            strategy="mask",
        ),
    ],
)

# 方法 3：自定义检测器函数
def detect_ssn(content: str) -> list[dict[str, str | int]]:
    """检测 SSN 并进行验证。

    返回一个包含 'text'、'start' 和 'end' 键的字典列表。
    """
    import re
    matches = []
    pattern = r"\d{3}-\d{2}-\d{4}"
    for match in re.finditer(pattern, content):
        ssn = match.group(0)
        # 验证：前 3 位数字不应为 000、666 或 900-999
        first_three = int(ssn[:3])
        if first_three not in [0, 666] and not (900 <= first_three <= 999):
            matches.append({
                "text": ssn,
                "start": match.start(),
                "end": match.end(),
            })
    return matches

agent3 = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        PIIMiddleware(
            "ssn",
            detector=detect_ssn,
            strategy="hash",
        ),
    ],
)
```

**自定义检测器函数签名：**

检测器函数必须接受一个字符串（内容）并返回匹配项：

返回一个包含 `text`、`start` 和 `end` 键的字典列表：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
def detector(content: str) -> list[dict[str, str | int]]:
    return [
        {"text": "matched_text", "start": 0, "end": 12},
        # ... 更多匹配项
    ]
```

<Tip>
  对于自定义检测器：

  * 对于简单模式使用正则表达式字符串
  * 当需要标志（例如，不区分大小写的匹配）时使用 RegExp 对象
  * 当需要超出模式匹配的验证逻辑时使用自定义函数
  * 自定义函数让您完全控制检测逻辑，并可以实现复杂的验证规则
</Tip>

<Accordion title="配置选项">
  <ParamField body="pii_type" type="string" required>
    要检测的 PII
    类型。可以是内置类型（`email`、`credit_card`、`ip`、`mac_address`、`url`）或自定义类型名称。
  </ParamField>

  <ParamField body="strategy" type="string" default="redact">
    如何处理检测到的 PII。选项：

    * `'block'` - 检测到时引发异常
    * `'redact'` - 替换为 `[REDACTED_{PII_TYPE}]`
    * `'mask'` - 部分遮蔽（例如，`****-****-****-1234`）
    * `'hash'` - 替换为确定性哈希值
  </ParamField>

  <ParamField body="detector" type="function | regex">
    自定义检测器函数或正则表达式模式。如果未提供，则使用该 PII 类型的内置检测器。
  </ParamField>

  <ParamField body="apply_to_input" type="boolean" default="True">
    在模型调用前检查用户消息
  </ParamField>

  <ParamField body="apply_to_output" type="boolean" default="False">
    在模型调用后检查 AI 消息
  </ParamField>

  <ParamField body="apply_to_tool_results" type="boolean" default="False">
    在执行后检查工具结果消息
  </ParamField>
</Accordion>

### 待办事项列表

为智能体配备任务规划和跟踪能力，以处理复杂的多步骤任务。待办事项列表对于以下情况很有用：

* 需要跨多个工具协调的复杂多步骤任务。
* 进度可见性很重要的长时间运行操作。

<Note>
  此中间件自动为智能体提供 `write_todos` 工具和系统提示，以指导有效的任务规划。
</Note>

**API 参考：** [`TodoListMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/todo/TodoListMiddleware)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[read_file, write_file, run_tests],
    middleware=[TodoListMiddleware()],
)
```

<Callout icon="player-play" iconType="solid">
  观看此[视频指南](https://www.youtube.com/watch?v=yTWocbVKQxw)演示待办事项列表中间件的行为。
</Callout>

<Accordion title="配置选项">
  <ParamField body="system_prompt" type="string">
    用于指导待办事项使用的自定义系统提示。如果未指定，则使用内置提示。
  </ParamField>

  <ParamField body="tool_description" type="string">
    `write_todos` 工具的自定义描述。如果未指定，则使用内置描述。
  </ParamField>
</Accordion>

### LLM 工具选择器

在调用主模型之前，使用 LLM 智能地选择相关工具。LLM 工具选择器对于以下情况很有用：

* 具有许多工具（10+）的智能体，其中大多数与每个查询无关。
* 通过过滤不相关的工具来减少令牌使用量。
* 提高模型的专注度和准确性。

此中间件使用结构化输出来询问 LLM 哪些工具与当前查询最相关。结构化输出模式定义了可用的工具名称和描述。模型提供商通常会在幕后将此结构化输出信息添加到系统提示中。

**API 参考：** [`LLMToolSelectorMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/tool_selection/LLMToolSelectorMiddleware)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import LLMToolSelectorMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[tool1, tool2, tool3, tool4, tool5, ...],
    middleware=[
        LLMToolSelectorMiddleware(
            model="gpt-5.4-mini",
            max_tools=3,
            always_include=["search"],
        ),
    ],
)
```

<Accordion title="配置选项">
  <ParamField body="model" type="string | BaseChatModel">
    用于工具选择的模型。可以是模型标识符字符串（例如，`'openai:gpt-5.4-mini'`）或 `BaseChatModel` 实例。更多信息请参阅 [`init_chat_model`](https://reference.langchain.com/python/langchain/chat_models/base/init_chat_model)。

    默认为智能体的主模型。
  </ParamField>

  <ParamField body="system_prompt" type="string">
    给选择模型的指令。如果未指定，则使用内置提示。
  </ParamField>

  <ParamField body="max_tools" type="number">
    要选择的最大工具数。如果模型选择更多，则仅使用前 max\_tools
    个。如果未指定，则无限制。
  </ParamField>

  <ParamField body="always_include" type="list[string]">
    无论选择如何都始终包含的工具名称。这些不计入 max\_tools 限制。
  </ParamField>
</Accordion>

### 工具重试

使用可配置的指数退避自动重试失败的工具调用。工具重试对于以下情况很有用：

* 处理外部 API 调用中的暂时性故障。
* 提高依赖网络的工具的可靠性。
* 构建能够优雅处理临时错误的弹性智能体。

**API 参考：** [`ToolRetryMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/tool_retry/ToolRetryMiddleware)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import ToolRetryMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool, database_tool],
    middleware=[
        ToolRetryMiddleware(
            max_retries=3,
            backoff_factor=2.0,
            initial_delay=1.0,
        ),
    ],
)
```

<Accordion title="配置选项">
  <ParamField body="max_retries" type="number" default="2">
    初始调用后的最大重试次数（默认为 3 次总尝试）
  </ParamField>

  <ParamField body="tools" type="list[BaseTool | str]">
    可选的工具或工具名称列表，用于应用重试逻辑。如果为 `None`，则应用于所有工具。
  </ParamField>

  <ParamField body="retry_on" type="tuple[type[Exception], ...] | callable" default="(Exception,)">
    要重试的异常类型元组，或一个接受异常并在应重试时返回 `True` 的可调用对象。
  </ParamField>

  <ParamField body="on_failure" type="string | callable" default="return_message">
    所有重试耗尽后的行为。选项： - `'return_message'` - 返回包含错误详情的
    `ToolMessage`（允许 LLM 处理失败） - `'raise'` -
    重新引发异常（停止智能体执行） - 自定义可调用对象 - 接受异常并返回
    `ToolMessage` 内容字符串的函数
  </ParamField>

  <ParamField body="backoff_factor" type="number" default="2.0">
    指数退避的乘数。每次重试等待 `initial_delay * (backoff_factor **
          retry_number)` 秒。设置为 `0.0` 表示恒定延迟。
  </ParamField>

  <ParamField body="initial_delay" type="number" default="1.0">
    首次重试前的初始延迟（秒）
  </ParamField>

  <ParamField body="max_delay" type="number" default="60.0">
    重试之间的最大延迟（秒）（限制指数退避增长）
  </ParamField>

  <ParamField body="jitter" type="boolean" default="true">
    是否向延迟添加随机抖动（`±25%`）以避免惊群效应
  </ParamField>
</Accordion>

<Accordion title="完整示例">
  中间件使用指数退避自动重试失败的工具调用。

  **关键配置：**

  * `max_retries` - 重试次数（默认：2）
  * `backoff_factor` - 指数退避的乘数（默认：2.0）
  * `initial_delay` - 起始延迟（秒）（默认：1.0）
  * `max_delay` - 延迟增长上限（默认：60.0）
  * `jitter` - 添加随机变化（默认：True）

  **失败处理：**

  * `on_failure='return_message'` - 返回错误消息
  * `on_failure='raise'` - 重新引发异常
  * 自定义函数 - 返回错误消息的函数

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain.agents import create_agent
  from langchain.agents.middleware import ToolRetryMiddleware


  agent = create_agent(
      model="gpt-5.4",
      tools=[search_tool, database_tool, api_tool],
      middleware=[
          ToolRetryMiddleware(
              max_retries=3,
              backoff_factor=2.0,
              initial_delay=1.0,
              max_delay=60.0,
              jitter=True,
              tools=["api_tool"],
              retry_on=(ConnectionError, TimeoutError),
              on_failure="continue",
          ),
      ],
  )
  ```
</Accordion>

### 模型重试

使用可配置的指数退避自动重试失败的模型调用。模型重试对于以下情况很有用：

* 处理模型 API 调用中的暂时性故障。
* 提高依赖网络的模型请求的可靠性。
* 构建能够优雅处理临时模型错误的弹性智能体。

**API 参考：** [`ModelRetryMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/model_retry/ModelRetryMiddleware)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import ModelRetryMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool, database_tool],
    middleware=[
        ModelRetryMiddleware(
            max_retries=3,
            backoff_factor=2.0,
            initial_delay=1.0,
        ),
    ],
)
```

<Accordion title="配置选项">
  <ParamField body="max_retries" type="number" default="2">
    初始调用后的最大重试次数（默认为 3 次总尝试）
  </ParamField>

  <ParamField body="retry_on" type="tuple[type[Exception], ...] | callable" default="(Exception,)">
    要重试的异常类型元组，或一个接受异常并在应重试时返回 `True` 的可调用对象。
  </ParamField>

  <ParamField body="on_failure" type="string | callable" default="continue">
    所有重试耗尽后的行为。选项： - `'continue'`（默认）- 返回包含错误详情的
    `AIMessage`，允许智能体可能优雅地处理失败 - `'error'` -
    重新引发异常（停止智能体执行） - 自定义可调用对象 - 接受异常并返回 `AIMessage`
    内容字符串的函数
  </ParamField>

  <ParamField body="backoff_factor" type="number" default="2.0">
    指数退避的乘数。每次重试等待 `initial_delay * (backoff_factor **
          retry_number)` 秒。设置为 `0.0` 表示恒定延迟。
  </ParamField>

  <ParamField body="initial_delay" type="number" default="1.0">
    首次重试前的初始延迟（秒）
  </ParamField>

  <ParamField body="max_delay" type="number" default="60.0">
    重试之间的最大延迟（秒）（限制指数退避增长）
  </ParamField>

  <ParamField body="jitter" type="boolean" default="true">
    是否向延迟添加随机抖动（`±25%`）以避免惊群效应
  </ParamField>
</Accordion>

<Accordion title="完整示例">
  中间件使用指数退避自动重试失败的模型调用。

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain.agents import create_agent
  from langchain.agents.middleware import ModelRetryMiddleware


  # 使用默认设置的基本用法（2 次重试，指数退避）
  agent = create_agent(
      model="gpt-5.4",
      tools=[search_tool],
      middleware=[ModelRetryMiddleware()],
  )

  # 自定义异常过滤
  class TimeoutError(Exception):
      """用于超时错误的自定义异常。"""
      pass

  class ConnectionError(Exception):
      """用于连接错误的自定义异常。"""
      pass

  # 仅重试特定异常
  retry = ModelRetryMiddleware(
      max_retries=4,
      retry_on=(TimeoutError, ConnectionError),
      backoff_factor=1.5,
  )


  def should_retry(error: Exception) -> bool:
      # 仅在速率限制错误时重试
      if isinstance(error, TimeoutError):
          return True
      # 或检查特定的 HTTP 状态码
      if hasattr(error, "status_code"):
          return error.status_code in (429, 503)
      return False

  retry_with_filter = ModelRetryMiddleware(
      max_retries=3,
      retry_on=should_retry,
  )

  # 返回错误消息而不是引发异常
  retry_continue = ModelRetryMiddleware(
      max_retries=4,
      on_failure="continue",  # 返回包含错误的 AIMessage 而不是引发异常
  )

  # 自定义错误消息格式化
  def format_error(error: Exception) -> str:
      return f"Model call failed: {error}. Please try again later."

  retry_with_formatter = ModelRetryMiddleware(
      max_retries=4,
      on_failure=format_error,
  )

  # 恒定退避（无指数增长）
  constant_backoff = ModelRetryMiddleware(
      max_retries=5,
      backoff_factor=0.0,  # 无指数增长
      initial_delay=2.0,  # 始终等待 2 秒
  )

  # 失败时引发异常
  strict_retry = ModelRetryMiddleware(
      max_retries=2,
      on_failure="error",  # 重新引发异常而不是返回消息
  )
  ```
</Accordion>

### LLM 工具模拟器

使用 LLM 模拟工具执行以用于测试目的，用 AI 生成的响应替换实际的工具调用。LLM 工具模拟器对于以下情况很有用：

* 在不执行真实工具的情况下测试智能体行为。
* 在外部工具不可用或昂贵时开发智能体。
* 在实现实际工具之前原型化智能体工作流程。

**API 参考：** [`LLMToolEmulator`](https://reference.langchain.com/python/langchain/agents/middleware/tool_emulator/LLMToolEmulator)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import LLMToolEmulator

agent = create_agent(
    model="gpt-5.4",
    tools=[get_weather, search_database, send_email],
    middleware=[
        LLMToolEmulator(),  # 模拟所有工具
    ],
)
```

<Accordion title="配置选项">
  <ParamField body="tools" type="list[str | BaseTool]">
    要模拟的工具名称（str）或 BaseTool 实例列表。如果为
    `None`（默认），则所有工具都将被模拟。如果为空列表
    `[]`，则不会模拟任何工具。如果包含工具名称/实例的数组，则仅模拟这些工具。
  </ParamField>

  <ParamField body="model" type="string | BaseChatModel">
    用于生成模拟工具响应的模型。可以是模型标识符字符串（例如，`'google_genai:gemini-3.1-pro-preview'`）或
    `BaseChatModel` 实例。如果未指定，则默认为智能体的模型。更多信息请参阅
    [`init_chat_model`](https://reference.langchain.com/python/langchain/chat_models/base/init_chat_model)。
  </ParamField>
</Accordion>

<Accordion title="完整示例">
  中间件使用 LLM 为工具调用生成合理的响应，而不是执行实际工具。

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain.agents import create_agent
  from langchain.agents.middleware import LLMToolEmulator
  from langchain.tools import tool


  @tool
  def get_weather(location: str) -> str:
      """获取某个位置的当前天气。"""
      return f"Weather in {location}"

  @tool
  def send_email(to: str, subject: str, body: str) -> str:
      """发送电子邮件。"""
      return "Email sent"


  # 模拟所有工具（默认行为）
  agent = create_agent(
      model="gpt-5.4",
      tools=[get_weather, send_email],
      middleware=[LLMToolEmulator()],
  )

  # 仅模拟特定工具
  agent2 = create_agent(
      model="gpt-5.4",
      tools=[get_weather, send_email],
      middleware=[LLMToolEmulator(tools=["get_weather"])],
  )

  # 使用自定义模型进行模拟
  agent4 = create_agent(
      model="gpt-5.4",
      tools=[get_weather, send_email],
      middleware=[LLMToolEmulator(model="claude-sonnet-4-6")],
  )
  ```
</Accordion>

### 上下文编辑

通过在达到令牌限制时清除较旧的工具调用输出来管理对话上下文，同时保留最近的结果。这有助于在具有许多工具调用的长对话中保持上下文窗口的可管理性。上下文编辑对于以下情况很有用：

* 具有许多工具调用且超出令牌限制的长对话
* 通过删除不再相关的较旧工具输出来降低令牌成本
* 仅在上下文中保留最近的 N 个工具结果

**API 参考：** [`ContextEditingMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/context_editing/ContextEditingMiddleware), [`ClearToolUsesEdit`](https://reference.langchain.com/python/langchain/agents/middleware/context_editing/ClearToolUsesEdit)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import ContextEditingMiddleware, ClearToolUsesEdit

agent = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        ContextEditingMiddleware(
            edits=[
                ClearToolUsesEdit(
                    trigger=100000,
                    keep=3,
                ),
            ],
        ),
    ],
)
```

<Accordion title="配置选项">
  <ParamField body="edits" type="list[ContextEdit]" default="[ClearToolUsesEdit()]">
    要应用的
    [`ContextEdit`](https://reference.langchain.com/python/langchain/agents/middleware/context_editing/ContextEdit)
    策略列表
  </ParamField>

  <ParamField body="token_count_method" type="string" default="approximate">
    令牌计数方法。选项：`'approximate'` 或 `'model'`
  </ParamField>

  **[`ClearToolUsesEdit`](https://reference.langchain.com/python/langchain/agents/middleware/context_editing/ClearToolUsesEdit) 选项：**

  <ParamField body="trigger" type="number" default="100000">
    触发编辑的令牌数。当对话超过此令牌数时，较旧的工具输出将被清除。
  </ParamField>

  <ParamField body="clear_at_least" type="number" default="0">
    编辑运行时要回收的最小令牌数。如果设置为 0，则清除所需的所有内容。
  </ParamField>

  <ParamField body="keep" type="number" default="3">
    必须保留的最近工具结果数。这些永远不会被清除。
  </ParamField>

  <ParamField body="clear_tool_inputs" type="boolean" default="False">
    是否清除 AI 消息上发起的工具调用参数。当为 `True`
    时，工具调用参数将被替换为空对象。
  </ParamField>

  <ParamField body="exclude_tools" type="list[string]" default="()">
    要排除在清除之外的工具名称列表。这些工具的输出永远不会被清除。
  </ParamField>

  <ParamField body="placeholder" type="string" default="[cleared]">
    为已清除的工具输出插入的占位符文本。这将替换原始工具消息内容。
  </ParamField>
</Accordion>

<Accordion title="完整示例">
  中间件在达到令牌限制时应用上下文编辑策略。最常见的策略是 `ClearToolUsesEdit`，它清除较旧的工具结果，同时保留最近的结果。

  **工作原理：**

  1. 监控对话中的令牌数
  2. 达到阈值时，清除较旧的工具输出
  3. 保留最近的 N 个工具结果
  4. 可选地保留工具调用参数以获取上下文

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain.agents import create_agent
  from langchain.agents.middleware import ContextEditingMiddleware, ClearToolUsesEdit


  agent = create_agent(
      model="gpt-5.4",
      tools=[search_tool, your_calculator_tool, database_tool],
      middleware=[
          ContextEditingMiddleware(
              edits=[
                  ClearToolUsesEdit(
                      trigger=2000,
                      keep=3,
                      clear_tool_inputs=False,
                      exclude_tools=[],
                      placeholder="[cleared]",
                  ),
              ],
          ),
      ],
  )
  ```
</Accordion>

### Shell 工具

向智能体暴露一个持久的 shell 会话以执行命令。Shell 工具中间件对于以下情况很有用：

* 需要执行系统命令的智能体
* 开发和部署自动化任务
* 测试和验证工作流程
* 文件系统操作和脚本执行

<Warning>
  **安全考虑**：使用适当的执行策略（`HostExecutionPolicy`、`DockerExecutionPolicy`
  或 `CodexSandboxExecutionPolicy`）以匹配您部署的安全要求。
</Warning>

<Note>
  **限制**：持久 shell 会话目前不支持中断（Human in the
  Loop）。我们预计将来会添加对此的支持。
</Note>

**API 参考：** [`ShellToolMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/shell_tool/ShellToolMiddleware)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import (
    ShellToolMiddleware,
    HostExecutionPolicy,
)

agent = create_agent(
    model="gpt-5.4",
    tools=[search_tool],
    middleware=[
        ShellToolMiddleware(
            workspace_root="/workspace",
            execution_policy=HostExecutionPolicy(),
        ),
    ],
)
```

<Accordion title="配置选项">
  <ParamField body="workspace_root" type="str | Path | None">
    shell 会话的基目录。如果省略，智能体启动时会创建一个临时目录，并在结束时删除。
  </ParamField>

  <ParamField body="startup_commands" type="tuple[str, ...] | list[str] | str | None">
    会话启动后顺序执行的可选命令
  </ParamField>

  <ParamField body="shutdown_commands" type="tuple[str, ...] | list[str] | str | None">
    会话关闭前执行的可选命令
  </ParamField>

  <ParamField body="execution_policy" type="BaseExecutionPolicy | None">
    控制超时、输出限制和资源配置的执行策略。选项：

    * `HostExecutionPolicy` - 完整主机访问（默认）；最适合智能体已在容器或 VM 内运行的受信任环境
    * `DockerExecutionPolicy` - 为每次智能体运行启动一个单独的 Docker 容器，提供更强的隔离性
    * `CodexSandboxExecutionPolicy` - 重用 Codex CLI 沙箱以进行额外的系统调用/文件系统限制
  </ParamField>

  <ParamField body="redaction_rules" type="tuple[RedactionRule, ...] | list[RedactionRule] | None">
    可选的编辑规则，用于在将命令输出返回给模型之前清理它。

    <Warning>
      编辑规则在执行后应用，使用 `HostExecutionPolicy`
      时无法防止机密或敏感数据泄露。
    </Warning>
  </ParamField>

  <ParamField body="tool_description" type="str | None">
    注册的 shell 工具描述的可选覆盖
  </ParamField>

  <ParamField body="shell_command" type="Sequence[str] | str | None">
    用于启动持久会话的可选 shell 可执行文件（字符串）或参数序列。默认为
    `/bin/bash`。
  </ParamField>

  <ParamField body="env" type="Mapping[str, Any] | None">
    提供给 shell 会话的可选环境变量。值在命令执行前被强制转换为字符串。
  </ParamField>
</Accordion>

<Accordion title="完整示例">
  中间件提供一个持久的 shell 会话，智能体可以使用它顺序执行命令。

  **执行策略：**

  * `HostExecutionPolicy`（默认）- 具有完整主机访问权限的本机执行
  * `DockerExecutionPolicy` - 隔离的 Docker 容器执行
  * `CodexSandboxExecutionPolicy` - 通过 Codex CLI 进行沙箱执行

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain.agents import create_agent
  from langchain.agents.middleware import (
      ShellToolMiddleware,
      HostExecutionPolicy,
      DockerExecutionPolicy,
      RedactionRule,
  )


  # 使用主机执行的基本 shell 工具
  agent = create_agent(
      model="gpt-5.4",
      tools=[search_tool],
      middleware=[
          ShellToolMiddleware(
              workspace_root="/workspace",
              execution_policy=HostExecutionPolicy(),
          ),
      ],
  )

  # Docker 隔离与启动命令
  agent_docker = create_agent(
      model="gpt-5.4",
      tools=[],
      middleware=[
          ShellToolMiddleware(
              workspace_root="/workspace",
              startup_commands=["pip install requests", "export PYTHONPATH=/workspace"],
              execution_policy=DockerExecutionPolicy(
                  image="python:3.11-slim",
                  command_timeout=60.0,
              ),
          ),
      ],
  )

  # 带有输出编辑（执行后应用）
  agent_redacted = create_agent(
      model="gpt-5.4",
      tools=[],
      middleware=[
          ShellToolMiddleware(
              workspace_root="/workspace",
              redaction_rules=[
                  RedactionRule(pii_type="api_key", detector=r"sk-[a-zA-Z0-9]{32}"),
              ],
          ),
      ],
  )
  ```
</Accordion>

### 文件搜索

提供基于文件系统的 Glob 和 Grep 搜索工具。文件搜索中间件对于以下情况很有用：

* 代码探索和分析
* 按名称模式查找文件
* 使用正则表达式搜索代码内容
* 需要文件发现的大型代码库

**API 参考：** [`FilesystemFileSearchMiddleware`](https://reference.langchain.com/python/langchain/agents/middleware/file_search/FilesystemFileSearchMiddleware)

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from langchain.agents.middleware import FilesystemFileSearchMiddleware

agent = create_agent(
    model="gpt-5.4",
    tools=[],
    middleware=[
        FilesystemFileSearchMiddleware(
            root_path="/workspace",
            use_ripgrep=True,
        ),
    ],
)
```

<Accordion title="配置选项">
  <ParamField body="root_path" type="str" required>
    要搜索的根目录。所有文件操作都相对于此路径。
  </ParamField>

  <ParamField body="use_ripgrep" type="bool" default="True">
    是否使用 ripgrep 进行搜索。如果 ripgrep 不可用，则回退到 Python 正则表达式。
  </ParamField>

  <ParamField body="max_file_size_mb" type="int" default="10">
    要搜索的最大文件大小（MB）。大于此大小的文件将被跳过。
  </ParamField>
</Accordion>

<Accordion title="完整示例">
  中间件向智能体添加两个搜索工具：

  **Glob 工具** - 快速文件模式匹配：

  * 支持 `**/*.py`、`src/**/*.ts` 等模式
  * 返回按修改时间排序的匹配文件路径

  **Grep 工具** - 使用正则表达式的内容搜索：

  * 完整的正则表达式语法支持
  * 使用 `include` 参数按文件模式过滤
  * 三种输出模式：`files_with_matches`、`content`、`count`

  ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from langchain.agents import create_agent
  from langchain.agents.middleware import FilesystemFileSearchMiddleware
  from langchain.messages import HumanMessage


  agent = create_agent(
      model="gpt-5.4",
      tools=[],
      middleware=[
          FilesystemFileSearchMiddleware(
              root_path="/workspace",
              use_ripgrep=True,
              max_file_size_mb=10,
          ),
      ],
  )

  # 智能体现在可以使用 glob_search 和 grep_search 工具
  result = agent.invoke({
      "messages": [HumanMessage("Find all Python files containing 'async def'")]
  })

  # 智能体将使用：
  # 1. glob_search(pattern="**/*.py") 查找 Python 文件
  # 2. grep_search(pattern="async def", include="*.py") 查找异步函数
  ```
</Accordion>

### 文件系统中间件

上下文工程是构建有效智能体的主要挑战。当使用返回可变长度结果的工具（例如 `web_search` 和 RAG）时，这尤其困难，因为较长的工具结果会快速填满您的上下文窗口。

来自 [Deep Agents](/oss/python/deepagents/overview) 的 `FilesystemMiddleware` 提供了四个用于与短期和长期记忆交互的工具：

* `ls`：列出文件系统中的文件
* `read_file`：读取整个文件或文件中的特定行数
* `write_file`：将新文件写入文件系统
* `edit_file`：编辑文件系统中的现有文件

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from deepagents.middleware.filesystem import FilesystemMiddleware

# FilesystemMiddleware 默认包含在 create_deep_agent 中
# 如果构建自定义智能体，您可以自定义它
agent = create_agent(
    model="claude-sonnet-4-6",
    middleware=[
        FilesystemMiddleware(
            backend=None,  # 可选：自定义后端（默认为 StateBackend）
            system_prompt="Write to the filesystem when...",  # 可选：系统提示的自定义补充
            custom_tool_descriptions={
                "ls": "Use the ls tool when...",
                "read_file": "Use the read_file tool to..."
            }  # 可选：文件系统工具的自定义描述
        ),
    ],
)
```

#### 短期与长期文件系统

默认情况下，这些工具写入图状态中的本地“文件系统”。要启用跨线程的持久存储，请配置一个 `CompositeBackend`，将特定路径（如 `/memories/`）路由到 `StoreBackend`。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from deepagents.middleware import FilesystemMiddleware
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

agent = create_agent(
    model="claude-sonnet-4-6",
    store=store,
    middleware=[
        FilesystemMiddleware(
            backend=CompositeBackend(
                default=StateBackend(),
                routes={"/memories/": StoreBackend()}
            ),
            custom_tool_descriptions={
                "ls": "Use the ls tool when...",
                "read_file": "Use the read_file tool to..."
            }  # 可选：文件系统工具的自定义描述
        ),
    ],
)
```

当您为 `/memories/` 配置带有 `StoreBackend` 的 `CompositeBackend` 时，任何以 **/memories/** 为前缀的文件都会保存到持久存储中，并在不同线程间保留。没有此前缀的文件保留在临时状态存储中。

### 子智能体

将任务交给子智能体可以隔离上下文，保持主（主管）智能体的上下文窗口干净，同时仍然深入处理任务。

来自 [Deep Agents](/oss/python/deepagents/overview) 的子智能体中间件允许您通过 `task` 工具提供子智能体。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.tools import tool
from langchain.agents import create_agent
from deepagents.middleware.subagents import SubAgentMiddleware


@tool
def get_weather(city: str) -> str:
    """获取城市的天气。"""
    return f"The weather in {city} is sunny."

agent = create_agent(
    model="claude-sonnet-4-6",
    middleware=[
        SubAgentMiddleware(
            default_model="claude-sonnet-4-6",
            default_tools=[],
            subagents=[
                {
                    "name": "weather",
                    "description": "This subagent can get weather in cities.",
                    "system_prompt": "Use the get_weather tool to get the weather in a city.",
                    "tools": [get_weather],
                    "model": "gpt-5.4",
                    "middleware": [],
                }
            ],
        )
    ],
)
```

子智能体通过**名称**、**描述**、**系统提示**和**工具**来定义。您还可以为子智能体提供自定义**模型**或额外的**中间件**。当您想给子智能体一个与主智能体共享的额外状态键时，这可能特别有用。

对于更复杂的用例，您也可以提供自己的预构建 LangGraph 图作为子智能体。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain.agents import create_agent
from deepagents.middleware.subagents import SubAgentMiddleware
from deepagents import CompiledSubAgent
from langgraph.graph import StateGraph

# 创建自定义 LangGraph 图
def create_weather_graph():
    workflow = StateGraph(...)
    # 构建您的自定义图
    return workflow.compile()

weather_graph = create_weather_graph()

# 将其包装在 CompiledSubAgent 中
weather_subagent = CompiledSubAgent(
    name="weather",
    description="This subagent can get weather in cities.",
    runnable=weather_graph
)

agent = create_agent(
    model="claude-sonnet-4-6",
    middleware=[
        SubAgentMiddleware(
            default_model="claude-sonnet-4-6",
            default_tools=[],
            subagents=[weather_subagent],
        )
    ],
)
```

除了任何用户定义的子智能体外，主智能体始终可以访问一个 `general-purpose` 子智能体。此子智能体具有与主智能体相同的指令和它可访问的所有工具。`general-purpose` 子智能体的主要目的是上下文隔离——主智能体可以将复杂任务委托给此子智能体，并获得简洁的答案，而不会因中间工具调用而膨胀。

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

这些中间件针对特定的 LLM 提供商进行了优化。有关完整详情和示例，请参阅每个提供商的文档。

<Columns cols={2}>
  <Card title="Anthropic" href="/oss/python/integrations/middleware/anthropic" icon="https://mintcdn.com/other-405835d4/agS8-xZoA1Gortud/images/providers/anthropic-icon.svg?fit=max&auto=format&n=agS8-xZoA1Gortud&q=85&s=88c98a84317065dc83e422014a1aac2c" arrow width="65" height="65" data-path="images/providers/anthropic-icon.svg">
    用于 Claude 模型的提示缓存、bash 工具、文本编辑器、记忆和文件搜索中间件。
  </Card>

  <Card title="AWS" href="/oss/python/integrations/middleware/aws" icon="brand-aws" arrow>
    用于 Amazon Bedrock 模型的提示缓存中间件。
  </Card>

  <Card title="OpenAI" href="/oss/python/integrations/middleware/openai" icon="brand-openai" arrow>
    用于 OpenAI 模型的内容审核中间件。
  </Card>
</Columns>

***

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

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