4.1 Built-in Middleware

本节介绍 LangChain 提供的内置中间件，涵盖上下文管理、执行控制、安全合规等多个方面。

概述

LangChain 提供生产就绪的中间件，分为两大类：

Provider-Agnostic：适用于任何 LLM 提供商
Provider-Specific：针对特定提供商优化（如 Anthropic、OpenAI）

Provider-Agnostic 中间件

上下文管理

SummarizationMiddleware

当对话接近 token 限制时，自动摘要对话历史：

python

from langchain.agents.middleware import SummarizationMiddleware

middleware = SummarizationMiddleware(
    max_tokens=4000,           # 触发摘要的 token 阈值
    summary_model="gpt-3.5-turbo",  # 用于摘要的模型
    keep_recent=5,             # 保留最近 N 条消息
)

agent = create_agent(
    "gpt-4o",
    tools=[my_tools],
    middleware=[middleware]
)

工作原理：

对话历史（超过阈值）
        │
        ▼
┌─────────────────┐
│  摘要旧消息      │
│  保留最近消息    │
└─────────────────┘
        │
        ▼
精简后的上下文

ContextEditingMiddleware

管理对话上下文，清理旧的工具输出：

python

from langchain.agents.middleware import ContextEditingMiddleware

middleware = ContextEditingMiddleware(
    max_tool_outputs=10,  # 保留的工具输出数量
    clear_after_steps=5,  # 每 N 步清理一次
)

执行控制

ModelCallLimitMiddleware

防止无限循环，限制 API 调用次数：

python

from langchain.agents.middleware import ModelCallLimitMiddleware

middleware = ModelCallLimitMiddleware(
    max_calls=20,              # 最大调用次数
    on_limit="stop",           # 达到限制时的行为: "stop" | "error"
    warning_threshold=15,      # 警告阈值
)

agent = create_agent(
    "gpt-4o",
    tools=[my_tools],
    middleware=[middleware]
)

ToolCallLimitMiddleware

控制工具执行频率：

python

from langchain.agents.middleware import ToolCallLimitMiddleware

middleware = ToolCallLimitMiddleware(
    max_calls_per_tool=5,      # 每个工具的最大调用次数
    max_total_calls=20,        # 工具总调用次数
)

ModelRetryMiddleware

API 调用失败时自动重试：

python

from langchain.agents.middleware import ModelRetryMiddleware

middleware = ModelRetryMiddleware(
    max_retries=3,             # 最大重试次数
    backoff_factor=2,          # 退避因子
    retry_on=[
        "RateLimitError",
        "ServiceUnavailable",
    ],
)

ToolRetryMiddleware

工具调用失败时自动重试：

python

from langchain.agents.middleware import ToolRetryMiddleware

middleware = ToolRetryMiddleware(
    max_retries=2,
    retry_on_error=True,
)

安全与合规

HumanInTheLoopMiddleware

暂停执行，等待人工审批：

python

from langchain.agents.middleware import HumanInTheLoopMiddleware

middleware = HumanInTheLoopMiddleware(
    tools=["send_email", "delete_file", "make_payment"],
    approval_callback=my_approval_function,
    timeout=300,  # 等待审批的超时时间（秒）
)

agent = create_agent(
    "gpt-4o",
    tools=[send_email, delete_file, search],
    middleware=[middleware]
)

审批回调示例：

python

def my_approval_function(tool_name, tool_args, state):
    """人工审批回调"""
    print(f"工具: {tool_name}")
    print(f"参数: {tool_args}")

    response = input("批准执行? (y/n): ")
    return response.lower() == "y"

PIIDetectionMiddleware

检测和处理敏感信息：

python

from langchain.agents.middleware import PIIDetectionMiddleware

middleware = PIIDetectionMiddleware(
    strategy="redact",  # "redact" | "mask" | "hash" | "block"
    pii_types=[
        "email",
        "phone",
        "ssn",
        "credit_card",
    ],
    on_detect="warn",  # "warn" | "block" | "log"
)

策略说明：

策略	说明	示例
`redact`	删除敏感信息	`[REDACTED]`
`mask`	部分遮蔽	`***@email.com`
`hash`	哈希处理	`a1b2c3d4...`
`block`	阻止请求	抛出异常

Agent 能力增强

TodoListMiddleware

提供任务规划和进度追踪：

python

from langchain.agents.middleware import TodoListMiddleware

middleware = TodoListMiddleware(
    max_items=10,
    auto_complete=True,
)

LLMToolSelectorMiddleware

智能过滤相关工具，适用于大型工具集：

python

from langchain.agents.middleware import LLMToolSelectorMiddleware

middleware = LLMToolSelectorMiddleware(
    max_tools=5,           # 每次最多选择的工具数
    selector_model="gpt-3.5-turbo",
)

# 适用于工具很多的场景
agent = create_agent(
    "gpt-4o",
    tools=[tool1, tool2, ..., tool50],  # 50个工具
    middleware=[middleware]  # 每次只选择最相关的5个
)

LLMToolEmulatorMiddleware

模拟工具执行，用于测试：

python

from langchain.agents.middleware import LLMToolEmulatorMiddleware

middleware = LLMToolEmulatorMiddleware(
    emulate_tools=["external_api", "database_query"],
    emulator_model="gpt-3.5-turbo",
)

ShellToolMiddleware

暴露持久化 Shell 会话：

python

from langchain.agents.middleware import ShellToolMiddleware

middleware = ShellToolMiddleware(
    allowed_commands=["ls", "cat", "grep", "find"],
    working_directory="/app/data",
    timeout=30,
)

FileSearchMiddleware

提供文件系统搜索能力：

python

from langchain.agents.middleware import FileSearchMiddleware

middleware = FileSearchMiddleware(
    root_directory="/project",
    allowed_extensions=[".py", ".js", ".md"],
)

弹性

ModelFallbackMiddleware

主模型失败时自动切换到备用模型：

python

from langchain.agents.middleware import ModelFallbackMiddleware

middleware = ModelFallbackMiddleware(
    fallback_models=[
        "gpt-3.5-turbo",
        "claude-haiku",
    ],
    fallback_on=[
        "RateLimitError",
        "ServiceUnavailable",
        "Timeout",
    ],
)

agent = create_agent(
    "gpt-4o",  # 主模型
    tools=[my_tools],
    middleware=[middleware]
)

Provider-Specific 中间件

Anthropic 中间件

python

from langchain.agents.middleware.anthropic import (
    PromptCachingMiddleware,
    BashToolMiddleware,
    TextEditorMiddleware,
)

# Prompt 缓存（减少延迟和成本）
prompt_caching = PromptCachingMiddleware()

# Bash 工具（Claude 专用）
bash_tool = BashToolMiddleware(
    allowed_commands=["python", "pip"],
)

# 文本编辑器（Claude 专用）
text_editor = TextEditorMiddleware()

OpenAI 中间件

python

from langchain.agents.middleware.openai import (
    ContentModerationMiddleware,
)

# 内容审核
moderation = ContentModerationMiddleware(
    categories=["hate", "violence", "self-harm"],
    threshold=0.8,
)

组合使用示例

python

from langchain.agents import create_agent
from langchain.agents.middleware import (
    SummarizationMiddleware,
    ModelCallLimitMiddleware,
    HumanInTheLoopMiddleware,
    ModelFallbackMiddleware,
    PIIDetectionMiddleware,
)

# 组合多个中间件构建生产级 Agent
agent = create_agent(
    model="gpt-4o",
    tools=[search, send_email, query_database],
    middleware=[
        # 1. 安全检查
        PIIDetectionMiddleware(strategy="mask"),

        # 2. 敏感操作审批
        HumanInTheLoopMiddleware(tools=["send_email"]),

        # 3. 上下文管理
        SummarizationMiddleware(max_tokens=4000),

        # 4. 执行限制
        ModelCallLimitMiddleware(max_calls=20),

        # 5. 故障恢复
        ModelFallbackMiddleware(fallback_models=["gpt-3.5-turbo"]),
    ]
)

中间件对照表

中间件	类别	用途
`SummarizationMiddleware`	上下文	自动摘要长对话
`ContextEditingMiddleware`	上下文	清理工具输出
`ModelCallLimitMiddleware`	执行控制	限制 API 调用
`ToolCallLimitMiddleware`	执行控制	限制工具调用
`ModelRetryMiddleware`	执行控制	API 重试
`ToolRetryMiddleware`	执行控制	工具重试
`HumanInTheLoopMiddleware`	安全	人工审批
`PIIDetectionMiddleware`	安全	PII 检测
`TodoListMiddleware`	能力	任务规划
`LLMToolSelectorMiddleware`	能力	智能工具选择
`LLMToolEmulatorMiddleware`	能力	工具模拟
`ShellToolMiddleware`	能力	Shell 访问
`FileSearchMiddleware`	能力	文件搜索
`ModelFallbackMiddleware`	弹性	模型降级

上一节：4.0 Middleware Overview

下一节：4.2 Custom Middleware

4.1 Built-in Middleware ​

概述 ​

Provider-Agnostic 中间件 ​

上下文管理 ​

SummarizationMiddleware ​

ContextEditingMiddleware ​

执行控制 ​

ModelCallLimitMiddleware ​

ToolCallLimitMiddleware ​

ModelRetryMiddleware ​

ToolRetryMiddleware ​

安全与合规 ​

HumanInTheLoopMiddleware ​

PIIDetectionMiddleware ​

Agent 能力增强 ​

TodoListMiddleware ​

LLMToolSelectorMiddleware ​

LLMToolEmulatorMiddleware ​

ShellToolMiddleware ​

FileSearchMiddleware ​

弹性 ​

ModelFallbackMiddleware ​

Provider-Specific 中间件 ​

Anthropic 中间件 ​

OpenAI 中间件 ​

组合使用示例 ​

中间件对照表 ​

4.1 Built-in Middleware

概述

Provider-Agnostic 中间件

上下文管理

SummarizationMiddleware

ContextEditingMiddleware

执行控制

ModelCallLimitMiddleware

ToolCallLimitMiddleware

ModelRetryMiddleware

ToolRetryMiddleware

安全与合规

HumanInTheLoopMiddleware

PIIDetectionMiddleware

Agent 能力增强

TodoListMiddleware

LLMToolSelectorMiddleware

LLMToolEmulatorMiddleware

ShellToolMiddleware

FileSearchMiddleware

弹性

ModelFallbackMiddleware

Provider-Specific 中间件

Anthropic 中间件

OpenAI 中间件

组合使用示例

中间件对照表