内置中间件

LangChain 和 Deep Agents 提供了用于常见用例的内置中间件。每个中间件都已达到生产级别，可根据你的特定需求进行配置。

与提供商无关的中间件

以下中间件适用于任何 LLM 提供商：

中间件	描述
摘要生成	当接近 Token 限制时自动摘要对话历史。
人机协作	暂停执行以等待人工批准工具调用。
模型调用限制	限制模型调用次数以防止过度开销。
工具调用限制	通过限制调用次数来控制工具执行。
模型回退	当主模型失败时自动回退到备选模型。
PII 检测	检测和处理个人身份信息（PII）。
待办列表	为智能体提供任务规划和跟踪能力。
LLM 工具选择器	在调用主模型之前使用 LLM 选择相关工具。
工具重试	使用指数退避自动重试失败的工具调用。
模型重试	使用指数退避自动重试失败的模型调用。
LLM 工具模拟器	使用 LLM 模拟工具执行，用于测试目的。
上下文编辑	通过裁剪或清除工具使用来管理对话上下文。
Shell 工具	为智能体暴露一个持久化 Shell 会话用于命令执行。
文件搜索	提供 Glob 和 Grep 搜索工具来搜索文件系统文件。
文件系统	为智能体提供文件系统，用于存储上下文和长期记忆。
子智能体	添加生成子智能体的能力。

摘要生成

当接近 Token 限制时自动摘要对话历史，在压缩旧上下文的同时保留近期消息。摘要生成适用于以下场景：

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

API 参考： SummarizationMiddleware

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),
        ),
    ],
)

配置选项

trigger 和 keep 的 fraction 条件（如下所示）在使用 langchain>=1.1 时依赖于聊天模型的配置数据。如果数据不可用，请使用其他条件或手动指定：

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)

string | BaseChatModel

required

用于生成摘要的模型。可以是模型标识符字符串（例如 'openai:gpt-5.4-mini'）或 BaseChatModel 实例。更多信息请参阅 init_chat_model。

ContextSize | list[ContextSize] | None

触发摘要生成的条件。可以是：

单个 ContextSize 元组（必须满足指定条件）
ContextSize 元组列表（满足任一条件即可 - 或逻辑）

条件应为以下之一：

fraction（浮点数）：模型上下文大小的比例（0-1）
tokens（整数）：绝对 Token 数量
messages（整数）：消息数量

至少必须指定一个条件。如果未提供，摘要生成不会自动触发。更多信息请参阅 ContextSize 的 API 参考。

ContextSize

default:"('messages', 20)"

摘要生成后保留多少上下文。请精确指定以下之一：

fraction（浮点数）：保留模型上下文大小的比例（0-1）
tokens（整数）：保留的绝对 Token 数量
messages（整数）：保留的近期消息数量

更多信息请参阅 ContextSize 的 API 参考。

function

自定义 Token 计数函数。默认使用基于字符的计数。

string

自定义摘要生成的提示词模板。如果未指定，使用内置模板。模板应包含 {messages} 占位符，对话历史将插入到此处。

number

default:"4000"

生成摘要时包含的最大 Token 数量。消息将被裁剪以适应此限制，然后再进行摘要。

string

deprecated

已弃用： 请使用 summary_prompt 来提供完整提示词。

number

deprecated

已弃用： 请使用 trigger: ("tokens", value) 代替。触发摘要生成的 Token 阈值。

number

deprecated

已弃用： 请使用 keep: ("messages", value) 代替。要保留的近期消息数量。

完整示例

摘要生成中间件监控消息的 Token 数量，并在达到阈值时自动对旧消息进行摘要。触发条件控制何时运行摘要生成：

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

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

fraction - 保留模型上下文大小的比例
tokens - 保留的绝对 Token 数量
messages - 保留的近期消息数量

from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware


# 单个条件：当 Token 数 >= 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),
        ),
    ],
)

# 多个条件：当 Token 数 >= 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),
        ),
    ],
)

人机协作

在工具调用执行之前暂停智能体执行，以等待人工批准、编辑或拒绝。人机协作适用于以下场景：

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

API 参考： HumanInTheLoopMiddleware

人机协作中间件需要一个检查点器来在中断之间维护状态。

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,
            }
        ),
    ],
)

有关完整示例、配置选项和集成模式，请参阅人机协作文档。

观看此视频指南，演示人机协作中间件的行为。

模型调用限制

限制模型调用次数以防止无限循环或过度开销。模型调用限制适用于以下场景：

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

API 参考： ModelCallLimitMiddleware

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",
        ),
    ],
)

观看此视频指南，演示模型调用限制中间件的行为。

配置选项

number

线程中所有运行的最大模型调用次数。默认无限制。

number

单次调用的最大模型调用次数。默认无限制。

string

default:"end"

达到限制时的行为。选项：'end'（优雅终止）或 'error'（抛出异常）

工具调用限制

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

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

API 参考： ToolCallLimitMiddleware

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,
        ),
    ],
)

观看此视频指南，演示工具调用限制中间件的行为。

配置选项

string

要限制的特定工具名称。如果未提供，限制将全局应用于所有工具。

number

线程（对话）中所有运行的最大工具调用次数。跨同一线程 ID 的多次调用持久化。需要检查点器来维护状态。None 表示无线程限制。

number

单次调用（一条用户消息到响应的周期）的最大工具调用次数。每条新用户消息都会重置。None 表示无运行限制。注意： 必须指定 thread_limit 或 run_limit 中的至少一个。

string

default:"continue"

达到限制时的行为：

'continue'（默认）- 用错误消息阻止超出的工具调用，让其他工具和模型继续。模型根据错误消息决定何时结束。
'error' - 抛出 ToolCallLimitExceededError 异常，立即停止执行
'end' - 立即停止执行，为超出的工具调用返回 ToolMessage 和 AI 消息。仅在限制单个工具时有效；如果其他工具有待处理的调用，则抛出 NotImplementedError。

完整示例

使用以下方式指定限制：

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

退出行为：

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

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],
)

模型回退

当主模型失败时自动回退到备选模型。模型回退适用于以下场景：

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

API 参考： ModelFallbackMiddleware

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",
        ),
    ],
)

观看此视频指南，演示模型回退中间件的行为。

配置选项

string | BaseChatModel

required

当主模型失败时首先尝试的回退模型。可以是模型标识符字符串（例如 'openai:gpt-5.4-mini'）或 BaseChatModel 实例。

string | BaseChatModel

如果前面的模型失败，按顺序尝试的额外回退模型

PII 检测

使用可配置策略检测和处理对话中的个人身份信息（PII）。PII 检测适用于以下场景：

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

API 参考： PIIMiddleware

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 类型。这允许你检测超出内置类型的特定于你用例的模式。 创建自定义检测器的三种方式：

正则表达式字符串 - 简单模式匹配
自定义函数 - 带验证的复杂检测逻辑

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 键的字典列表：

def detector(content: str) -> list[dict[str, str | int]]:
    return [
        {"text": "matched_text", "start": 0, "end": 12},
        # ... 更多匹配
    ]

关于自定义检测器：

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

配置选项

string

required

要检测的 PII 类型。可以是内置类型（email、credit_card、ip、mac_address、url）或自定义类型名称。

string

default:"redact"

如何处理检测到的 PII。选项：

'block' - 检测到时抛出异常
'redact' - 替换为 [REDACTED_{PII_TYPE}]
'mask' - 部分遮盖（例如 ****-****-****-1234）
'hash' - 替换为确定性哈希

function | regex

自定义检测器函数或正则表达式模式。如果未提供，使用该 PII 类型的内置检测器。

boolean

default:"True"

在模型调用前检查用户消息

boolean

default:"False"

在模型调用后检查 AI 消息

boolean

default:"False"

在执行后检查工具结果消息

待办列表

为智能体提供任务规划和跟踪能力，用于复杂的多步骤任务。待办列表适用于以下场景：

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

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

API 参考： TodoListMiddleware

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()],
)

观看此视频指南，演示待办列表中间件的行为。

配置选项

string

指导待办使用的自定义系统提示词。如果未指定，使用内置提示词。

string

write_todos 工具的自定义描述。如果未指定，使用内置描述。

LLM 工具选择器

使用 LLM 在调用主模型之前智能选择相关工具。LLM 工具选择器适用于以下场景：

拥有许多工具（10+）且大多数与每个查询无关的智能体。
通过过滤无关工具来减少 Token 用量。
提高模型的专注度和准确性。

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

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"],
        ),
    ],
)

配置选项

string | BaseChatModel

用于工具选择的模型。可以是模型标识符字符串（例如 'openai:gpt-5.4-mini'）或 BaseChatModel 实例。更多信息请参阅 init_chat_model。默认使用智能体的主模型。

string

选择模型的指令。如果未指定，使用内置提示词。

number

最大选择工具数量。如果模型选择了更多，只使用前 max_tools 个。如果未指定则无限制。

list[string]

无论选择结果如何都始终包含的工具名称。这些不计入 max_tools 限制。

工具重试

使用可配置的指数退避自动重试失败的工具调用。工具重试适用于以下场景：

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

API 参考： ToolRetryMiddleware

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,
        ),
    ],
)

配置选项

number

default:"2"

初始调用后的最大重试次数（使用默认值时共 3 次尝试）

list[BaseTool | str]

可选的要应用重试逻辑的工具或工具名称列表。如果为 None，则应用于所有工具。

tuple[type[Exception], ...] | callable

default:"(Exception,)"

要重试的异常类型元组，或接受异常并返回 True（应重试时）的可调用对象。

string | callable

default:"return_message"

所有重试耗尽时的行为。选项：

'return_message' - 返回包含错误详情的 ToolMessage（允许 LLM 处理失败）
'raise' - 重新抛出异常（停止智能体执行）
自定义可调用对象 - 接受异常并返回字符串作为 ToolMessage 内容的函数

number

default:"2.0"

指数退避的乘数。每次重试等待 initial_delay * (backoff_factor ** retry_number) 秒。设为 0.0 表示固定延迟。

number

default:"1.0"

首次重试前的初始延迟（秒）

number

default:"60.0"

重试之间的最大延迟（秒）（限制指数退避的增长）

boolean

default:"true"

是否添加随机抖动（±25%）以避免惊群效应

完整示例

中间件使用指数退避自动重试失败的工具调用。关键配置：

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

失败处理：

on_failure='return_message' - 返回错误消息
on_failure='raise' - 重新抛出异常
自定义函数 - 返回错误消息的函数

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",
        ),
    ],
)

模型重试

使用可配置的指数退避自动重试失败的模型调用。模型重试适用于以下场景：

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

API 参考： ModelRetryMiddleware

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,
        ),
    ],
)

配置选项

number

default:"2"

初始调用后的最大重试次数（使用默认值时共 3 次尝试）

tuple[type[Exception], ...] | callable

default:"(Exception,)"

要重试的异常类型元组，或接受异常并返回 True（应重试时）的可调用对象。

string | callable

default:"continue"

所有重试耗尽时的行为。选项：

'continue'（默认）- 返回包含错误详情的 AIMessage，允许智能体可能优雅地处理失败
'error' - 重新抛出异常（停止智能体执行）
自定义可调用对象 - 接受异常并返回字符串作为 AIMessage 内容的函数

number

default:"2.0"

指数退避的乘数。每次重试等待 initial_delay * (backoff_factor ** retry_number) 秒。设为 0.0 表示固定延迟。

number

default:"1.0"

首次重试前的初始延迟（秒）

number

default:"60.0"

重试之间的最大延迟（秒）（限制指数退避的增长）

boolean

default:"true"

是否添加随机抖动（±25%）以避免惊群效应

完整示例

中间件使用指数退避自动重试失败的模型调用。

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"模型调用失败：{error}。请稍后重试。"

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",  # 重新抛出异常而不是返回消息
)

LLM 工具模拟器

使用 LLM 模拟工具执行以用于测试目的，用 AI 生成的响应替代实际的工具调用。LLM 工具模拟器适用于以下场景：

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

API 参考： LLMToolEmulator

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(),  # 模拟所有工具
    ],
)

配置选项

list[str | BaseTool]

要模拟的工具名称（字符串）或 BaseTool 实例列表。如果为 None（默认），将模拟所有工具。如果为空列表 []，不模拟任何工具。如果是包含工具名称/实例的数组，只模拟那些工具。

string | BaseChatModel

用于生成模拟工具响应的模型。可以是模型标识符字符串（例如 'google_genai:gemini-3.1-pro-preview'）或 BaseChatModel 实例。如果未指定，默认使用智能体的模型。更多信息请参阅 init_chat_model。

完整示例

中间件使用 LLM 为工具调用生成合理的响应，而不是执行实际工具。

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")],
)

上下文编辑

通过在达到 Token 限制时清除较旧的工具调用输出来管理对话上下文，同时保留近期结果。这有助于在包含大量工具调用的长时间对话中保持上下文窗口的可管理性。上下文编辑适用于以下场景：

包含大量工具调用且超出 Token 限制的长时间对话
通过移除不再相关的旧工具输出来降低 Token 成本
在上下文中仅维护最近 N 个工具结果

API 参考： ContextEditingMiddleware、ClearToolUsesEdit

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,
                ),
            ],
        ),
    ],
)

配置选项

list[ContextEdit]

default:"[ClearToolUsesEdit()]"

要应用的 ContextEdit 策略列表

string

default:"approximate"

Token 计数方法。选项：'approximate' 或 'model'

ClearToolUsesEdit 选项：

number

default:"100000"

触发编辑的 Token 数量。当对话超过此 Token 数量时，较旧的工具输出将被清除。

number

default:"0"

编辑运行时要回收的最小 Token 数量。如果设为 0，则尽可能多地清除。

number

default:"3"

必须保留的最近工具结果数量。这些永远不会被清除。

boolean

default:"False"

是否清除 AI 消息上的原始工具调用参数。当为 True 时，工具调用参数将替换为空对象。

list[string]

default:"()"

排除在清除之外的工具名称列表。这些工具的输出永远不会被清除。

string

default:"[cleared]"

为已清除的工具输出插入的占位文本。这将替换原始的工具消息内容。

完整示例

中间件在达到 Token 限制时应用上下文编辑策略。最常用的策略是 ClearToolUsesEdit，它在保留近期结果的同时清除较旧的工具结果。工作原理：

监控对话中的 Token 数量
当达到阈值时，清除较旧的工具输出
保留最近 N 个工具结果
可选地保留工具调用参数以提供上下文

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]",
                ),
            ],
        ),
    ],
)

Shell 工具

为智能体暴露一个持久化 Shell 会话用于命令执行。Shell 工具中间件适用于以下场景：

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

安全考虑：使用适当的执行策略（HostExecutionPolicy、DockerExecutionPolicy 或 CodexSandboxExecutionPolicy）以匹配你的部署安全要求。

限制：持久化 Shell 会话目前不支持中断（人机协作）。我们预计未来会添加对此的支持。

API 参考： ShellToolMiddleware

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(),
        ),
    ],
)

配置选项

str | Path | None

Shell 会话的基目录。如果省略，智能体启动时创建临时目录，结束时移除。

tuple[str, ...] | list[str] | str | None

会话启动后顺序执行的可选命令

tuple[str, ...] | list[str] | str | None

会话关闭前执行的可选命令

BaseExecutionPolicy | None

控制超时、输出限制和资源配置的执行策略。选项：

HostExecutionPolicy - 完全主机访问（默认）；最适合智能体已在容器或虚拟机内运行的受信环境
DockerExecutionPolicy - 为每次智能体运行启动单独的 Docker 容器，提供更强的隔离
CodexSandboxExecutionPolicy - 重用 Codex CLI 沙箱以获得额外的系统调用/文件系统限制

tuple[RedactionRule, ...] | list[RedactionRule] | None

可选的脱敏规则，在将命令输出返回给模型之前进行清理。

脱敏规则在执行后应用，使用 HostExecutionPolicy 时不能阻止机密或敏感数据的泄露。

str | None

注册的 Shell 工具描述的可选覆盖

Sequence[str] | str | None

用于启动持久化会话的可选 Shell 可执行文件（字符串）或参数序列。默认为 /bin/bash。

Mapping[str, Any] | None

提供给 Shell 会话的可选环境变量。值在命令执行前会被转换为字符串。

完整示例

中间件提供了一个持久化 Shell 会话，智能体可以使用它来顺序执行命令。执行策略：

HostExecutionPolicy（默认）- 具有完全主机访问权限的原生执行
DockerExecutionPolicy - 隔离的 Docker 容器执行
CodexSandboxExecutionPolicy - 通过 Codex CLI 的沙箱化执行

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}"),
            ],
        ),
    ],
)

文件搜索

提供 Glob 和 Grep 搜索工具来搜索文件系统。文件搜索中间件适用于以下场景：

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

API 参考： FilesystemFileSearchMiddleware

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,
        ),
    ],
)

配置选项

str

required

搜索的根目录。所有文件操作都相对于此路径。

bool

default:"True"

是否使用 ripgrep 进行搜索。如果 ripgrep 不可用则回退到 Python 正则表达式。

int

default:"10"

搜索的最大文件大小（MB）。超过此大小的文件将被跳过。

完整示例

中间件为智能体添加两个搜索工具：Glob 工具 - 快速文件模式匹配：

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

Grep 工具 - 带正则表达式的内容搜索：

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

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("查找所有包含 'async def' 的 Python 文件")]
})

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

文件系统中间件

上下文工程是构建有效智能体的主要挑战。当使用返回可变长度结果的工具时（例如 web_search 和 RAG），这尤其困难，因为长工具结果会快速填满你的上下文窗口。 Deep Agents 的 FilesystemMiddleware 提供了四个工具来与短期和长期记忆交互：

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

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="在以下情况下写入文件系统...",  # 可选的系统提示词自定义添加
            custom_tool_descriptions={
                "ls": "在以下情况下使用 ls 工具...",
                "read_file": "使用 read_file 工具来..."
            }  # 可选：文件系统工具的自定义描述
        ),
    ],
)

短期 vs. 长期文件系统

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

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": "在以下情况下使用 ls 工具...",
                "read_file": "使用 read_file 工具来..."
            }  # 可选：文件系统工具的自定义描述
        ),
    ],
)

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

子智能体

将任务交接给子智能体可以隔离上下文，保持主（监督者）智能体的上下文窗口干净，同时仍能深入执行任务。 Deep Agents 的子智能体中间件允许你通过 task 工具提供子智能体。

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": "此子智能体可以获取城市天气。",
                    "system_prompt": "使用 get_weather 工具获取城市天气。",
                    "tools": [get_weather],
                    "model": "gpt-5.4",
                    "middleware": [],
                }
            ],
        )
    ],
)

子智能体通过名称、描述、系统提示词和工具来定义。你还可以为子智能体提供自定义模型或额外的中间件。当你想让子智能体拥有额外的状态键与主智能体共享时，这特别有用。对于更复杂的用例，你也可以提供自己预构建的 LangGraph 图作为子智能体。

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="此子智能体可以获取城市天气。",
    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 提供商进行了优化。有关完整详情和示例，请参阅每个提供商的文档。

Anthropic

Claude 模型的提示词缓存、bash 工具、文本编辑器、记忆和文件搜索中间件。

AWS

Amazon Bedrock 模型的提示词缓存中间件。

OpenAI

OpenAI 模型的内容审核中间件。

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

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

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Deploy with LangSmith

与提供商无关的中间件

摘要生成

人机协作

模型调用限制

工具调用限制

模型回退

PII 检测

自定义 PII 类型

待办列表

LLM 工具选择器

工具重试

模型重试

LLM 工具模拟器

上下文编辑

Shell 工具

文件搜索

文件系统中间件

短期 vs. 长期文件系统

子智能体

特定提供商的中间件

Anthropic

AWS

OpenAI

​与提供商无关的中间件

​摘要生成

​人机协作

​模型调用限制

​工具调用限制

​模型回退

​PII 检测

​自定义 PII 类型

​待办列表

​LLM 工具选择器

​工具重试

​模型重试

​LLM 工具模拟器

​上下文编辑

​Shell 工具

​文件搜索

​文件系统中间件

​短期 vs. 长期文件系统

​子智能体

​特定提供商的中间件

Anthropic

AWS

OpenAI

与提供商无关的中间件

摘要生成

人机协作

模型调用限制

工具调用限制

模型回退

PII 检测

自定义 PII 类型

待办列表

LLM 工具选择器

工具重试

模型重试

LLM 工具模拟器

上下文编辑

Shell 工具

文件搜索

文件系统中间件

短期 vs. 长期文件系统

子智能体

特定提供商的中间件