LangChain 1.0 核心中间件解析

AI手记叨叨2026-06-29 9:04

文章目录

  • 一、安全中间件
    • [1. PIIMiddleware (个人身份信息检测)](#1. PIIMiddleware (个人身份信息检测))
    • [2. HumanInTheLoopMiddleware (人工审批)](#2. HumanInTheLoopMiddleware (人工审批))
  • 二、功能中间件
    • [1. SummarizationMiddleware (对话总结)](#1. SummarizationMiddleware (对话总结))
    • [2. ModelFallbackMiddleware (模型回退)](#2. ModelFallbackMiddleware (模型回退))
    • [3. TodoListMiddleware (任务规划)](#3. TodoListMiddleware (任务规划))
    • [4. LLMToolSelectorMiddleware (工具选择器)](#4. LLMToolSelectorMiddleware (工具选择器))
    • [5. ToolRetryMiddleware (工具重试)](#5. ToolRetryMiddleware (工具重试))
    • [6. ModelRetryMiddleware (模型调用重试)](#6. ModelRetryMiddleware (模型调用重试))
    • [7. ContextEditingMiddleware (上下文编辑)](#7. ContextEditingMiddleware (上下文编辑))
    • [8. ShellToolMiddleware (Shell工具)](#8. ShellToolMiddleware (Shell工具))
    • [9. LLMToolEmulator (LLM工具模拟器)](#9. LLMToolEmulator (LLM工具模拟器))
    • [10. FilesystemFileSearchMiddleware (文件系统搜索中间件)](#10. FilesystemFileSearchMiddleware (文件系统搜索中间件))
  • 三、监控/限制中间件
    • [1. ModelCallLimitMiddleware (模型调用限制)](#1. ModelCallLimitMiddleware (模型调用限制))
    • [2. ToolCallLimitMiddleware (工具调用限制)](#2. ToolCallLimitMiddleware (工具调用限制))
  • 四、总结

LangChain中间件是用于增强、约束和监控Agent行为的可插拔组件，本文梳理了其核心中间件，涵盖2个安全中间件、10个功能中间件以及2个监控限制中间件，详细说明了每个中间件的核心作用、使用方式、代码示例及关键注意点，为开发者在实际项目中按需选用中间件提供参考。

一、安全中间件

这类中间件用于在运行时检测和拦截风险，确保AI应用的安全合规。

1. PIIMiddleware (个人身份信息检测)

作用：自动检测并处理对话中的个人身份信息（PII），如邮箱、信用卡号、IP地址等，防止数据泄露。

  • 使用方式：在创建Agent时，将 PIIMiddleware 实例添加到 middleware 列表中。可以为不同类型的PII配置不同的处理策略。
  • 处理策略：
    • "redact": 替换为 [REDACTED_类型]。
    • "mask": 部分模糊化（如保留后四位）。
    • "hash": 替换为哈希值。
    • "block": 检测到时直接抛出异常，阻止执行。
  • 代码示例：
python 复制代码 
from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware

agent = create_agent(
    model="gpt-4",
    tools=[...],
    middleware=[
        # 对输入中的邮箱进行编辑
        PIIMiddleware("email", strategy="redact", apply_to_input=True),
        # 对输出中的信用卡号进行掩码处理
        PIIMiddleware("credit_card", strategy="mask", apply_to_output=True),
    ],
)
  • 注意点：
    • apply_to_input 和 apply_to_output 参数控制中间件检查用户输入还是AI输出。
    • 内置的PII类型包括 credit_card, ip, mac_address, url 等，也可以通过 detector 参数自定义正则表达式来检测。

2. HumanInTheLoopMiddleware (人工审批)

作用：在执行某些高风险操作（如发送邮件、删除数据库记录）前，暂停执行并等待人工批准，防止Agent做出不可逆的错误决策。

  • 使用方式：通过 interrupt_on 字典配置哪些工具需要审批。
  • 代码示例：
python 复制代码 
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="gpt-4",
    tools=[send_email_tool, delete_database_tool],
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "send_email": True,      # 发送邮件需要审批
                "delete_database": True, # 删除数据库需要审批
            }
        ),
    ],
    checkpointer=InMemorySaver(), # 必须使用checkpointer来保存状态
)
  • 注意点：
    • 必须配合 checkpointer（如 InMemorySaver）使用，以便在等待审批时持久化状态。
    • 执行时需要在 config 中指定唯一的 thread_id，后续通过 Command(resume=...) 来恢复执行。

二、功能中间件

这类中间件扩展Agent的能力，优化其性能或行为模式。

1. SummarizationMiddleware (对话总结)

作用：当对话历史快达到模型的上下文窗口限制时，自动总结历史消息，将其压缩，从而保留关键信息并防止程序崩溃。

  • 使用方式：配置触发总结的阈值，可以基于Token数、消息条数或上下文比例。
  • 代码示例：
python 复制代码 
from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware

agent = create_agent(
    model="gpt-4",
    tools=[...],
    middleware=[
        SummarizationMiddleware(
            context_size="context_fraction", # 使用比例触发
            threshold=0.8, # 当上下文使用超过80%时触发
        )
    ],
)
  • 注意点：context_size 参数可以设置为 "context_tokens" (Token数), "context_messages" (消息数), 或 "context_fraction" (比例)。需要权衡总结带来的信息丢失。

2. ModelFallbackMiddleware (模型回退)

作用：当主模型不可用（如服务中断、速率限制）时，自动切换到备用模型，提高系统的鲁棒性。

  • 使用方式：指定主模型和备选模型列表。
  • 代码示例：
python 复制代码 
from langchain.agents import create_agent
from langchain.agents.middleware import ModelFallbackMiddleware

agent = create_agent(
    model=primary_model, # 主模型
    tools=[...],
    middleware=[
        ModelFallbackMiddleware(
            fallback_models=[backup_model_1, backup_model_2],
        )
    ],
)
  • 注意点：备选模型列表按顺序尝试，直到有一个成功。

3. TodoListMiddleware (任务规划)

作用：为Agent配备一个"待办事项列表"工具，使其能够更好地进行任务规划和跟踪，对于复杂、多步骤的任务非常有帮助。

  • 使用方式：直接添加到中间件列表即可。Agent会在需要时自动调用待办事项工具。
  • 代码示例：
python 复制代码 
from langchain.agents import create_agent
from langchain.agents.middleware import TodoListMiddleware

agent = create_agent(
    model="gpt-4",
    tools=[...],
    middleware=[TodoListMiddleware()],
)
  • 注意点：这是一个"无侵入式"的中间件，Agent会自主决定是否使用它来组织任务。

4. LLMToolSelectorMiddleware (工具选择器)

作用：在调用主模型之前，先用一个轻量级的LLM（或相同的模型）从大量工具中筛选出与当前用户问题最相关的几个工具，以减少上下文长度并提高准确性。

  • 使用方式：需要配置一个专门用于选择的模型。
  • 代码示例：
python 复制代码 
from langchain.agents import create_agent
from langchain.agents.middleware import LLMToolSelectorMiddleware

selector_model = init_chat_model("gpt-3.5-turbo") # 用更快的模型做选择
agent = create_agent(
    model="gpt-4",
    tools=[many_tools],
    middleware=[
        LLMToolSelectorMiddleware(selector_model=selector_model),
    ]
)
  • 注意点：适用于工具集非常庞大（例如超过几十个）的场景，能有效提升性能和降低成本。

5. ToolRetryMiddleware (工具重试)

作用：当工具调用因临时性错误（如网络超时）失败时，自动使用指数退避算法进行重试。

  • 使用方式：可以配置最大重试次数。
  • 代码示例：
python 复制代码 
from langchain.agents import create_agent
from langchain.agents.middleware import ToolRetryMiddleware

agent = create_agent(
    model="gpt-4",
    tools=[...],
    middleware=[ToolRetryMiddleware(max_retries=3)],
)
  • 注意点：重试策略基于指数退避，适合处理不稳定的网络或外部API调用。

6. ModelRetryMiddleware (模型调用重试)

作用：与 ToolRetryMiddleware 类似，但专门用于处理模型API调用失败时的自动重试。

  • 使用方式：用法与 ToolRetryMiddleware 高度相似。
  • 代码示例：
python 复制代码 
from langchain.agents import create_agent
from langchain.agents.middleware import ModelRetryMiddleware

agent = create_agent(
    model="gpt-4",
    tools=[...],
    middleware=[ModelRetryMiddleware(max_retries=3)],
)
  • 注意点：与 ModelFallbackMiddleware 是互补的。重试用于处理瞬时故障，回退用于处理模型完全不可用的情况。

7. ContextEditingMiddleware (上下文编辑)

作用：通过修剪（pruning）或清除（clearing）工具调用记录来主动管理对话上下文，防止上下文过长。

  • 使用方式：配置清除策略，例如在调用一定数量的工具后清除历史工具结果。
  • 代码示例：
python 复制代码 
from langchain.agents import create_agent
from langchain.agents.middleware import ContextEditingMiddleware
from langchain.agents.middleware import ClearToolUsesEdit

agent = create_agent(
    model="gpt-4",
    tools=[...],
    middleware=[
        ContextEditingMiddleware(
            clear_tool_uses=ClearToolUsesEdit(strategy="after_last"), # 保留最后一次工具调用
        )
    ],
)
  • 注意点：这是一个更"激进"的上下文管理方式，比起 SummarizationMiddleware，它可能会丢失更多历史信息，但能更有效地控制长度。

8. ShellToolMiddleware (Shell工具)

作用：为Agent暴露一个持久化的Shell会话，使其能够执行系统命令（如 ls, grep）。

  • 使用方式：直接添加到中间件列表。
  • 代码示例：
python 复制代码 
from langchain.agents import create_agent
from langchain.agents.middleware import ShellToolMiddleware

agent = create_agent(
    model="gpt-4",
    tools=[...],
    middleware=[ShellToolMiddleware()],
)
  • 注意点：这是一个具有极高安全风险的功能。仅在完全受控和信任的环境中使用，否则可能带来严重的系统安全漏洞。

9. LLMToolEmulator (LLM工具模拟器)

  • 核心作用：在不实际执行工具的情况下，用 LLM 来"模拟"工具调用的结果。这主要用于测试和开发阶段，当不想因为测试而真的发送邮件、修改数据库或产生费用时，这个中间件非常有用。

  • 使用方式：默认情况下，它会模拟 Agent 可用的所有工具。也可以通过 tools 参数，只针对指定的工具进行模拟。

  • 代码示例 (Python):

    python 复制代码 
    from langchain.agents import create_agent
from langchain.agents.middleware import LLMToolEmulator

agent = create_agent(
    model="gpt-4",
    # 假设这里有 send_email_tool, get_weather_tool 等
    tools=[send_email_tool, get_weather_tool],
    middleware=[
        LLMToolEmulator(
            # 只模拟发送邮件工具，天气工具仍会实际执行
            tools=["send_email_tool"],
        )
    ],
)

  • 注意点：

    • 仅用于测试：它的设计初衷是测试，切忌在生产环境中不加区分地使用，否则工具会返回由 LLM 生成的"虚构"结果，导致不可预测的行为。
    • 配置灵活：可以精确控制哪些工具被模拟，哪些工具真实执行，这为构建复杂的测试场景提供了便利。

10. FilesystemFileSearchMiddleware (文件系统搜索中间件)

  • 核心作用：为 Agent 增加在本地文件系统中搜索文件和内容的能力。它提供了两个工具：Glob（通过文件路径模式查找文件）和 Grep（通过关键词在文件内容中搜索）。

  • 使用方式：初始化时，最关键的是通过 root_path 指定一个根目录，Agent 的所有文件搜索操作将被限制在这个目录下。

  • 代码示例 (Python):

    python 复制代码 
    from langchain.agents import create_agent
from langchain.agents.middleware import FilesystemFileSearchMiddleware

agent = create_agent(
    model="gpt-4",
    tools=[], # 可以添加其他工具
    middleware=[
        FilesystemFileSearchMiddleware(
            root_path="/path/to/your/workspace", # 必须指定
            use_ripgrep=True, # 优先使用更快的ripgrep，不可用则回退到Python实现 
            max_file_size_mb=10, # 限制搜索的文件大小，防止性能问题 
        )
    ],
)

  • 注意点：

    • 安全风险：与 ShellToolMiddleware 类似，赋予 Agent 文件系统访问权限存在安全风险。务必通过 root_path 将其限定在一个安全的沙箱目录内，避免它读取或修改敏感系统文件。
    • 性能考量：max_file_size_mb 参数可以帮助控制搜索性能，防止 Agent 尝试读取过大的文件。

三、监控/限制中间件

这类中间件主要用于控制成本和监控Agent的行为。

1. ModelCallLimitMiddleware (模型调用限制)

作用：限制Agent在单次运行中可以调用模型的最大次数，防止因Agent陷入循环或执行过多步骤而导致高昂的API费用。

  • 使用方式：设置一个合理的调用上限。
  • 代码示例：
python 复制代码 
from langchain.agents import create_agent
from langchain.agents.middleware import ModelCallLimitMiddleware

agent = create_agent(
    model="gpt-4",
    tools=[...],
    middleware=[ModelCallLimitMiddleware(limit=10)],
)
  • 注意点：这个限制是针对一次Agent运行（agent.invoke）的总模型调用次数。如果超出限制，Agent会抛出异常或终止。

2. ToolCallLimitMiddleware (工具调用限制)

作用：限制Agent在单次运行中可以调用工具的总次数，防止失控的工具执行，也是对成本和资源消耗的一种控制。

  • 使用方式：设置一个工具调用上限。
  • 代码示例：
python 复制代码 
from langchain.agents import create_agent
from langchain.agents.middleware import ToolCallLimitMiddleware

agent = create_agent(
    model="gpt-4",
    tools=[...],
    middleware=[ToolCallLimitMiddleware(limit=15)],
)
  • 注意点：与 ModelCallLimitMiddleware 配合使用，可以形成双重保险，确保Agent的执行是可控的。

四、总结

中间件生态可分为三个层面：官方预构建中间件、供应商专属中间件、社区贡献中间件。本文梳理了其中官方预构建中间件里的14个核心常用组件（涵盖安全、功能和监控限制三大类）。除此之外，LangChain还支持开发者通过 createMiddleware 函数或继承 AgentMiddleware 基类构建完全自定义的中间件，通过 before_agent、before_model、wrap_model_call、wrap_tool_call、after_model、after_agent 等钩子在Agent执行的不同阶段介入控制。

热门推荐
012026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？022026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04飞书长连接_事件订阅（接收消息，审批任务状态变更）05Trae国际版与国内版深度测评：AI原生IDE的双生花06【AI】2026 年具身智能模型和世界模型总结07GitHub 镜像站点08Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析092026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？102026年AI架构实战：彻底解决OpenAI接口超时与封号，Python调用GPT-5.2/Sora2企业级架构详解（附源码+压测报告）