跳至主要內容

中间件

Mr.Zhang2026/6/8AILangChain大约 40 分钟约 12013 字

概述

在 create_agent() 的底层运行机制中，有几个很重要的组价，分别是：

  • 模型(Model)：Agent 的大脑，负责理解任务与决策推理
  • 工具(Tools)：Agent 的手脚，执行模型自己做不到的外部操作
  • 系统提示词(System Prompt)：Agent的角色，告诉模型该怎么想、参考什么上下文。
  • 中间件(Middleware)：Agent的中枢，在执行流程的关键节点进行拦截、控制和增强

声明如下：

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

agent = create_agent(
    model="gpt-5.5",
    tools=[...],
    middleware=[
        SummarizationMiddleware(...),
        HumanInTheLoopMiddleware(...)
    ],
)

什么是中间件

Middleware（中间件），简单说就是 Agent 执行过程中的钩子函数，是 LangChain 1.x 的王牌工程化能力。借助中间件，开发和可以高度定制和控制 Agent 运行的每一个环节，是处理 Agent 生命周期的标准方式。

在 LangChain 的 Agent 执行循环中，比如 "模型调用前"、"模型调用后"、"工具调用前" 设置一些钩子（hooks），让你在不改 Agent 主体逻辑的情况下实现策略与治理。

无中间件架构使用中间件架构
无中间件架构使用中间件架构

为什么需要中间件

中间件的价格在于把一些与业务无关，但与执行过程强相关的横切逻辑，从 Agent 主流程中分离出来，让其主体代码聚焦业务，而借助中间件实现拦截流程、修改流程、增强流程。

比如说实现如下功能：

  • 日志与分析： 追踪行为、调试、性能监控
  • 转换： 修改提示词、工具选择、输出格式
  • 容错： 重试、降级、早期终止
  • 安全： 限流、守护规则、PII 检测

中间件分类

LangChain 分为下面两类：
自定义中间件：允许开发者自定义
内置中间件：模型供应商无关的中间件 / 模型供应商定制的中间件

模型提供商无关的中间件分类

官网链接，大致分为下面六个类别：

成本与资源控制类

核心目标: 控成本、控配额、避免无限调用
解决的问题: Agent太贵、太能跑、停不下来
包含的功能:
• Model call limit：限制模型调用次数，防止一次任务反复请求LLM，导致费用失控
• Tool call limit：限制工具调用次数，避免Agent无限试错、死循环调工具
• Summarization：在上下文快满时自动总结历史，减少token消耗
• Context editing：裁剪上下文、清理工具调用痕迹，本质上也是为了节省上下文成本
业务场景理解: 适合生产环境的成本治理、配额治理、长会话优化、SaaS产品控费

常用内置中间件

SummarizationMiddleware

在接近 token 上限时自动总结对话历史，保留最近的消息同时压缩较早的上下文。

适用场景： 长时间运行的对话、多轮对话、需要保留完整对话上下文的应用。

注意： 摘要是文本导向的上下文压缩，不会对图片/音频/视频进行压缩。被 keep 保留的最近消息仍包含原始的多模态内容，而被摘要的较早消息仅以生成的文本摘要形式表示。

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

agent = create_agent(
    model="gpt-5.5",
    tools=[your_weather_tool, your_calculator_tool],
    middleware=[
        SummarizationMiddleware(
            model="gpt-5.4-mini",          # 必填：用于生成摘要的模型
            trigger=("tokens", 4000),       # 触发条件
            keep=("messages", 20),          # 保留条件
        ),
    ],
)

配置参数：

参数类型默认值说明
modelstring | BaseChatModel必填用于生成摘要的模型，可以是模型标识字符串或 BaseChatModel 实例
triggerContextSize | TriggerClause | list不触发触发摘要的条件。支持 fraction（模型上下文比例 0-1）、tokens（绝对 token 数）、messages（消息数量）。单个元组为单阈值，字典为 AND 逻辑，列表为 OR 逻辑
keepContextSize("messages", 20)摘要后保留的上下文量。只能指定 fraction、tokens、messages 中的一个
token_counterfunction字符计数自定义 token 计数函数
summary_promptstring内置模板自定义摘要提示模板，需包含 {messages} 占位符
trim_tokens_to_summarizenumber4000生成摘要时包含的最大 token 数

已废弃参数： max_tokens_before_summary（改用 trigger=("tokens", value)）、messages_to_keep（改用 keep=("messages", value)）

HumanInTheLoopMiddleware

在工具调用执行前暂停 Agent，等待人类审批、编辑或拒绝。

适用场景： 高风险操作（数据库写入、金融交易）、合规工作流、需要人类反馈的长对话。

警告： HumanInTheLoop 需要配置 checkpointer 来维护中断期间的状态。
Agent → 模型生成响应 → 中间件检查工具调用 → 触发 interrupt → 等待人类决策 → 恢复执行

配置参数：

参数类型默认值说明
interrupt_ondict必填工具名到审批配置的映射。值可以是 True（默认审批）、False（自动批准）或 InterruptOnConfig 对象
description_prefixstring"Tool execution requires approval"中断消息的前缀

InterruptOnConfig 选项：

参数说明
allowed_decisions允许的决策列表：'approve'、'edit'、'reject'、'respond'
description静态字符串或可调用函数，用于自定义描述
when可选的断言函数，接收 ToolCallRequest 返回 True 中断或 False 自动批准（需要 langchain>=1.3.3）

示例：

输出：

详情

前面中断了，下面指明工具调用请求决策

输出：

详情
演示实时交互

控制台：

PIIMiddleware

在发送给模型之前检测并处理对话中的个人身份信息（PII）。

适用场景： 医疗和金融合规应用、需要清理日志的客服代理、处理敏感用户数据的应用。

处理策略：

策略说明示例
redact替换为 [REDACTED_{PII_TYPE}][REDACTED_EMAIL]
mask部分遮盖****-****-****-1234
hash替换为确定性哈希a8f5f167...
block检测到时抛出异常抛出错误

内置 PII 类型： email（邮箱）、credit_card（信用卡，Luhn 校验）、ip（IP 地址）、mac_address（MAC 地址）、url（URL）

示例:

输出

配置参数：

参数类型默认值说明
pii_typestring必填要检测的 PII 类型（内置或自定义）
strategystring"redact"处理策略："block"、"redact"、"mask"、"hash"
detectorfunction | regex内置检测器自定义检测器，支持正则字符串、编译后的正则或自定义函数
apply_to_inputbooleanTrue在模型调用前检查用户消息
apply_to_outputbooleanFalse在模型调用后检查 AI 消息（langchain>=1.3.2 还支持流式输出脱敏）
apply_to_tool_resultsbooleanFalse在工具执行后检查工具结果消息

自定义检测器函数示例：

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

TodoListMiddleware

为 Agent 提供任务规划和跟踪能力，适用于复杂的多步骤任务。

适用场景： 需要跨多个工具协调的复杂多步骤任务、需要进度可见性的长时间运行操作。

注意： 此中间件自动为 Agent 提供 write_todos 工具和系统提示来引导有效的任务规划。

示例：

from langchain.agents import create_agent
from langchain.agents.middleware import TodoListMiddleware

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

配置参数：

参数类型说明
system_promptstring自定义系统提示，用于引导 todo 使用。不指定则使用内置提示
tool_descriptionstring自定义 write_todos 工具描述。不指定则使用内置描述

其它内置中间件

ModelCallLimitMiddleware

限制模型调用次数，防止无限循环或过度消耗成本。

适用场景： 防止失控 Agent 过多调用 API、强制执行生产环境成本控制、在特定调用预算内测试 Agent 行为。

注意： 线程限制（thread_limit）需要配置 checkpointer 来维护跨调用的状态。

示例：

配置参数：

参数类型默认值说明
thread_limitnumber无限制线程内（跨所有调用）的最大模型调用次数
run_limitnumber无限制单次调用的最大模型调用次数
exit_behaviorstring"end"达到限制时的行为："end"（优雅终止）、"error"（抛出异常）

ToolCallLimitMiddleware

控制 Agent 执行，限制工具调用次数，可全局限制或针对特定工具限制。

适用场景： 防止过度调用昂贵的外部 API、限制网络搜索或数据库查询、对特定工具强制执行速率限制、防止失控 Agent 循环。

注意： 至少需要指定 threadLimit/thread_limit 或 runLimit/run_limit 中的一个。线程限制需要 checkpointer。

示例：

from langchain.agents import create_agent
from langchain.agents.middleware import ToolCallLimitMiddleware

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

配置参数：

参数类型默认值说明
tool_namestring全局要限制的特定工具名称。不指定则全局限制
thread_limitnumber无限制线程内最大工具调用次数（需要 checkpointer）
run_limitnumber无限制单次调用的最大工具调用次数
exit_behaviorstring"continue"达到限制时的行为：
"continue"（阻止超限调用并返回错误消息，Agent 继续）
"error"（抛出 ToolCallLimitExceededError）
"end"（立即停止，仅限单工具场景，其它工具有待处理调用时抛出 NotImplementedError）

ModelFallbackMiddleware

当主模型失败时自动回退到备选模型。

适用场景： 构建处理模型中断的弹性 Agent、通过回退到更便宜的模型优化成本、跨 OpenAI/Anthropic 等的提供商冗余。

示例：

from langchain.agents import create_agent
from langchain.agents.middleware import ModelFallbackMiddleware

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

配置参数：

参数类型说明
first_modelstring | BaseChatModel第一个备选模型
*additional_modelsstring | BaseChatModel额外的备选模型，按顺序尝试

LLMToolSelectorMiddleware

在调用主模型之前，使用 LLM 智能选择相关工具。

适用场景： 拥有 10+ 工具的 Agent（大多数查询并不需要所有工具）、通过过滤不相关工具减少 token 使用、提高模型聚焦度和准确性。

工作原理： 此中间件使用结构化输出询问 LLM 哪些工具与当前查询最相关。结构化输出 schema 定义了可用工具的名称和描述。

示例：

from langchain.agents import create_agent
from langchain.agents.middleware import LLMToolSelectorMiddleware

agent = create_agent(
    model="gpt-5.5",
    tools=[tool1, tool2, tool3, tool4, tool5, ...],
    middleware=[
        LLMToolSelectorMiddleware(
            model="gpt-5.4-mini",
            max_tools=3,  # 最多3个工具
            always_include=["search"], # 使用包含的工具 不计入 max_tools
        ),
    ],
)

配置参数：

参数类型默认值说明
modelstring | BaseChatModelAgent 主模型用于工具选择的模型
system_promptstring内置提示选择模型的指令
max_toolsnumber无限制最多选择的工具数量
always_includelist[string][]始终包含的工具名称（不计入 max_tools 限制）

ToolRetryMiddleware

自动重试失败的工具调用，支持可配置的指数退避。

适用场景： 处理外部 API 调用的瞬时故障、提高网络依赖工具的可靠性、构建优雅处理临时错误的弹性 Agent。

提示

指数退避（Exponential Backoff）的核心思想就是：当某个操作失败（通常是网络请求、API调用或数据库连接）时，系统不会立刻重试，也不会每次都等待相同的固定时间，而是让每一次重试的延迟时间按指数级增长。

为什么不直接重试？

想象一下，某个热门网站的服务器因为瞬间流量太大（比如抢票或秒杀）崩溃了。如果所有失败的客户端都立刻或每隔1秒就重试一次，这无异于对已经瘫痪的服务器进行了一场持续的 DDoS（分布式拒绝服务）攻击，服务器可能永远也缓不过来。

示例：

配置参数：

参数类型默认值说明
max_retriesnumber2最大重试次数（默认共 3 次尝试）
toolslist[BaseTool | str]所有工具要应用重试逻辑的工具列表（工具实例或名称字符串）
retry_ontuple[type[Exception], ...] | callable所有错误异常类型元组或返回 True 表示应重试的可调用对象
on_failurestring | callable"return_message"重试耗尽后的行为："return_message"（返回错误 ToolMessage）、"raise"（重新抛出异常）、自定义可调用对象
backoff_factornumber2.0指数退避乘数。设为 0.0 则为固定延迟
initial_delaynumber1.0（秒）首次重试前的初始延迟
max_delaynumber60.0（秒）重试间的最大延迟（限制指数退避增长）
jitterbooleanTrue是否添加随机抖动（±25%）以避免惊群效应

ModelRetryMiddleware

自动重试失败的模型调用，支持可配置的指数退避。

适用场景： 处理模型 API 调用的瞬时故障、提高网络依赖模型请求的可靠性、构建优雅处理临时模型错误的弹性 Agent。

示例：

from langchain.agents import create_agent
from langchain.agents.middleware import ModelRetryMiddleware

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

配置参数：

参数类型默认值说明
max_retriesnumber2最大重试次数（默认共 3 次尝试）
retry_ontuple[type[Exception], ...] | callable所有错误异常类型元组或返回 True 表示应重试的可调用对象
on_failurestring | callable"continue"重试耗尽后的行为："continue"（返回错误 AIMessage）、"error"（重新抛出异常）、自定义可调用对象
backoff_factornumber2.0指数退避乘数。设为 0.0 则为固定延迟
initial_delaynumber1.0（秒）首次重试前的初始延迟
max_delaynumber60.0（秒）重试间的最大延迟
jitterbooleanTrue是否添加随机抖动（±25%）以避免惊群效应

与 ToolRetryMiddleware 的区别： ModelRetryMiddleware 重试的是 LLM 模型调用失败，ToolRetryMiddleware 重试的是工具执行失败。两者通常组合使用：

LLMToolEmulator

使用 LLM 模拟工具执行，替代实际工具调用生成 AI 回复。

适用场景： 在不执行真实工具的情况下测试 Agent 行为、在外部工具不可用或昂贵时开发 Agent、在实现实际工具之前原型化 Agent 工作流。

示例：

输出

配置参数：

参数类型默认值说明
toolslist[str | BaseTool]所有工具要模拟的工具列表。None 模拟所有工具，空列表不模拟任何工具
modelstring | BaseChatModelAgent 主模型用于生成模拟工具响应的模型

使用示例：

# 仅模拟特定工具（按名称）
LLMToolEmulator(tools=["get_weather"])

# 使用不同的模型进行模拟
LLMToolEmulator(model="claude-sonnet-4-6")

ContextEditingMiddleware

通过清除较旧的工具调用输出来管理对话上下文，同时保留最近的结果。帮助在包含大量工具调用的长对话中保持上下文窗口可控。

适用场景： 超过 token 限制的长对话（含大量工具调用）、通过移除不再相关的旧工具输出减少 token 成本、仅维护最近 N 个工具结果。

示例：

ContextEditingMiddleware 配置参数：

参数类型默认值说明
editslist[ContextEdit][ClearToolUsesEdit()]要应用的上下文编辑策略列表
token_count_methodstring"approximate"token 计数方法："approximate" 或 "model"

ClearToolUsesEdit 配置参数：

参数类型默认值说明
triggernumber100000触发编辑的 token 数
clear_at_leastnumber0编辑时最少回收的 token 数
keepnumber3必须保留的最近工具结果数量
clear_tool_inputsbooleanFalse是否清除 AI 消息上的工具调用参数（替换为空对象）
exclude_toolslist[string][]排除清除的工具名称列表
placeholderstring"[cleared]"替换已清除工具输出的占位符文本

工作原理：

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

FilesystemFileSearchMiddleware

提供 Glob 和 Grep 搜索工具，用于文件系统上的文件搜索。

适用场景： 代码探索和分析、按名称模式查找文件、用正则搜索代码内容、需要文件发现的大型代码库。

注意： 此中间件来自 Deep Agents。TypeScript/JS 对应的是 FilesystemMiddleware 中的 glob 和 grep 工具。

Python 示例：

from langchain.agents import create_agent
from langchain.agents.middleware import FilesystemFileSearchMiddleware

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

配置参数：

参数类型默认值说明
root_pathstr必填搜索的根目录，所有文件操作相对于此路径
use_ripgrepboolTrue是否使用 ripgrep 搜索。不可用时回退到 Python 正则
max_file_size_mbint10最大搜索文件大小（MB），超过此大小的文件将被跳过

提供的工具：

  • glob_search — 快速文件模式匹配，支持 **/*.py、src/**/*.ts 等模式，返回按修改时间排序的匹配文件路径
  • grep_search — 内容搜索，支持完整正则语法，可通过 include 参数按文件模式过滤，支持三种输出模式：files_with_matches、content、count
# Agent 可以使用 glob_search 和 grep_search 工具
result = agent.invoke({
    "messages": [HumanMessage("Find all Python files containing 'async def'")]
})
# Agent 将使用：
# 1. glob_search(pattern="**/*.py") 查找 Python 文件
# 2. grep_search(pattern="async def", include="*.py") 查找异步函数

Shell tool

Shell 工具允许 Agent 在沙盒环境中执行 shell 命令。这是 Deep Agents FilesystemMiddleware 中 execute 工具的一部分。

注意： execute 工具仅在 沙盒后端 可用，不适用于标准的 StateBackend 或 FilesystemBackend。

提供的操作：

工具说明
execute在环境中运行 shell 命令（仅限沙盒后端）

使用沙盒后端时，Agent 可以执行如 git status、npm test、ls -la 等命令。

Filesystem

FilesystemMiddleware 提供虚拟文件系统访问，支持短期和长期记忆的文件操作。这是 Deep Agents 的核心中间件之一，在 create_deep_agent 中默认包含。

示例：

from langchain.agents import create_agent
from deepagents.backends import StateBackend
from deepagents.middleware import FilesystemMiddleware

agent = create_agent(
    model="claude-sonnet-4-6",
    middleware=[
        FilesystemMiddleware(backend=StateBackend()),
    ],
)

提供的工具：

工具说明
ls列出目录中的文件及元数据（大小、修改时间）
read_file读取文件内容（支持行号、offset/limit），还支持非文本文件的多模态内容块（图片、视频、音频、文档）
write_file创建新文件
edit_file对文件执行精确字符串替换（支持全局替换模式）
glob按模式查找文件（如 **/*.py）
grep搜索文件内容，支持多种输出模式（仅文件名、带上下文的内容、计数）
execute运行 shell 命令（仅限沙盒后端）

支持的多模态文件扩展名：

类型扩展名
图片.png, .jpg, .jpeg, .gif, .webp, .heic, .heif
视频.mp4, .mpeg, .mov, .avi, .flv, .mpg, .webm, .wmv, .3gpp
音频.wav, .mp3, .aiff, .aac, .ogg, .flac
文件.pdf, .ppt, .pptx

可插拔后端： FilesystemMiddleware 支持多种后端：StateBackend（内存状态）、FilesystemBackend（本地磁盘）、StoreBackend（LangGraph Store）、CompositeBackend（组合路由）、自定义后端。详见 Backends 文档。

Subagent

将任务委派给子 Agent 来隔离上下文，保持主（监督者）Agent 的上下文窗口清洁，同时仍能深入处理任务。

子 Agent 中间件来自 Deep Agents，允许你通过 task 工具提供子 Agent。

示例：

子 Agent 配置选项：

参数类型说明
namestring子 Agent 名称（用于路由）
descriptionstring子 Agent 描述（帮助主 Agent 选择正确的子 Agent）
system_promptstring子 Agent 的系统提示
toolsBaseTool[]子 Agent 可用的工具列表
modelstring可选：子 Agent 使用的模型（覆盖默认模型）
middlewareMiddleware[]可选：子 Agent 的额外中间件

SubAgentMiddleware 配置参数：

参数类型说明
default_modelstring未指定模型的子 Agent 使用的默认模型
default_toolsBaseTool[]所有子 Agent 共享的默认工具
subagentsSubAgent[]子 Agent 定义列表

子 Agent 执行特性：

  • 全新上下文 — 每次调用创建新的 Agent 实例，拥有独立上下文
  • 自主执行 — 子 Agent 独立运行直到完成
  • 单次交接 — 返回一个最终报告给主 Agent
  • 无状态消息 — 子 Agent 是无状态的，不能发送多条消息回来
  • 上下文和 token 效率 — 繁重的子任务工作保持隔离，并被压缩为紧凑的结果

除了用户自定义的子 Agent，主 Agent 始终可以访问一个 general-purpose 子 Agent。该子 Agent 拥有与主 Agent 相同的指令和所有可用工具，主要目的是上下文隔离。

使用预构建 LangGraph 图作为子 Agent（Python）：

from deepagents import CompiledSubAgent
from langgraph.graph import StateGraph

def create_weather_graph():
    workflow = StateGraph(...)
    return workflow.compile()

weather_subagent = CompiledSubAgent(
    name="weather",
    description="This subagent can get weather in cities.",
    runnable=create_weather_graph()
)

自定义中间件

某些复杂场景下，官方内置的中间件不能完全满足需求，此时可以通过实现 LangChain 暴露的中间件 hook函数 构建自定义中间件。

什么是 hook 函数

Hook 函数，中文名长叫钩子函数，指的是：在某个既定流程的特定时机，被框架、系统或者主程序自动调用的扩展函数。

hook 函数分类

LangChain 中间件暴露了两大类共 6 个 hook 函数，分别对应 Agent 执行生命周期的不同切入点：

分类钩子函数触发时机典型用途
节点式（Node）before_agentAgent 开始前（每次调用仅一次）加载记忆、校验输入
before_model每次模型调用前修改提示词、裁剪消息
after_model每次模型响应后校验输出、应用护栏
after_agentAgent 完成后（每次调用仅一次）保存结果、清理资源
包裹式（Wrap）wrap_model_call包裹每次模型调用拦截请求/响应、重试、缓存
wrap_tool_call包裹每次工具调用拦截工具执行、修改参数/返回值

如何选择钩子类型？

需要顺序执行的逻辑（日志、校验、状态更新） → 用 Node-style hooks
需要控制调用流程的逻辑（重试、降级、缓存、动态切换模型/工具） → 用 Wrap-style hooks

Node-style hooks

节点式钩子在 Agent 执行的特定节点顺序运行，适合做日志记录、输入校验、输出校验、状态更新等线性逻辑。

每个 hook 函数签名为 (state: AgentState, runtime: Runtime) -> dict | None：

  • 返回 None 表示不修改状态，继续执行
  • 返回 dict 会合并到 Agent 状态中（键值映射到状态字段）
  • 返回包含 jump_to 的字典可以跳转到指定节点（"end" / "tools" / "model"）

四个 hook 的执行时机：

消息数量限制_示例：

装饰器写法

可用的 jump 目标：

目标说明
"end"跳转到 Agent 执行结束（或第一个 after_agent）
"tools"跳转到工具执行节点
"model"跳转到模型调用节点（或第一个 before_model）

注意： 使用 jump_to 需要在装饰器或 @hook_config 中声明 can_jump_to 列表，否则会抛出异常。

Wrap-style hooks

包裹式钩子以洋葱模型包裹在模型/工具调用周围，拥有对调用流程的完全控制权——你可以决定 handler 被调用 0 次（短路）、1 次（正常流程）、或多次（重试逻辑）。

可用的 wrap 钩子：

钩子包裹对象handler 签名
wrap_model_call每次模型调用handler(request: ModelRequest) -> ModelResponse
wrap_tool_call每次工具调用handler(request: ToolRequest) -> ToolResponse

核心机制： wrap 钩子接收 request 和 handler 两个参数。handler 代表被包裹的实际调用，你可以：

  • 在调用前修改 request（通过 request.override(...) 创建新请求，不可变模式）
  • 在调用后修改响应
  • 跳过 handler 直接返回（短路）
  • 多次调用 handler（重试）
  • 替换 handler 的目标（动态切换模型/工具）

模型调用重试_示例 1：

装饰器写法

动态选择模型_示例 2：

装饰器写法

动态修改系统提示词_示例 3：

ModelRequest 常用属性：

属性说明
request.messages当前对话消息列表
request.model当前使用的模型实例
request.tools当前可用的工具列表
request.system_message系统提示词（始终为 SystemMessage 对象）
request.state当前 Agent 状态
request.runtimeRuntime 对象，可访问上下文（runtime.context）
request.override(...)创建修改后的新请求（不可变模式）

装饰器和类的选择

LangChain 提供两种方式创建自定义中间件：装饰器和类。

对比维度装饰器写法类写法
适用场景单个 hook、快速原型多个 hook、复杂配置、需要同步+异步双版本
代码量少，一个函数即可多，需要定义类和方法
可配置性通过闭包或参数通过 __init__ 构造函数
异步支持需要单独定义异步函数可在同一个类中定义 abefore_model 等
状态扩展通过 state_schema 参数声明通过类属性 state_schema 声明
复用性适合项目内复用适合跨项目复用、发布为包
内置中间件—所有内置中间件均采用类写法

类写法的特殊类属性：

属性说明
state_schema扩展 Agent 状态，添加自定义字段（如计数器、用户信息）
tools注册中间件自带的工具（如 TodoListMiddleware 的 write_todos）
transformers注册流式转换器工厂，用于自定义事件投影

经验法则： 只需要一个 hook → 装饰器；需要多个 hook 或复杂配置 → 类。

多个中间件组合及执行顺序

在实际项目中，我们往往需要同时使用多个中间件来实现不同的功能。理解它们的执行顺序对于正确组合中间件至关重要。

执行顺序规则

当声明多个中间件时：

agent = create_agent(
    model="gpt-5.5",
    middleware=[middleware1, middleware2, middleware3],
    tools=[...],
)

完整的执行流程如下：

逐步执行顺序说明

Before 钩子按声明顺序（正序）执行：

  1. middleware1.before_agent()
  2. middleware2.before_agent()
  3. middleware3.before_agent()

Agent 循环开始：

  1. middleware1.before_model()
  2. middleware2.before_model()
  3. middleware3.before_model()

Wrap 钩子像函数调用一样嵌套（洋葱模型）：

  1. middleware1.wrap_model_call() → middleware2.wrap_model_call() → middleware3.wrap_model_call() → 实际模型调用

After 钩子按声明逆序执行：

  1. middleware3.after_model()
  2. middleware2.after_model()
  3. middleware1.after_model()

Agent 循环结束：

  1. middleware3.after_agent()
  2. middleware2.after_agent()
  3. middleware1.after_agent()

核心规则总结

钩子类型执行顺序类比
before_*正序（先声明先执行）像排队，先到先服务
after_*逆序（先声明后执行）像剥洋葱，从外到内再从内到外
wrap_*嵌套（第一个包裹所有）像套娃，外层包裹内层

设计思想： 这种"正序进入、逆序退出"的模式与 Express.js / Koa.js 的中间件模型完全一致。before 负责"进入"阶段的预处理，after 负责"退出"阶段的清理，wrap 则拥有对整个调用链的完全控制权。

实际组合示例

下面展示一个典型的多中间件组合——从输入安全检查到输出合规校验的完整管线：

执行流程解读：

  1. 用户消息进入 → PIIMiddleware（输入层）先脱敏邮箱和信用卡号
  2. ModelCallLimitMiddleware 检查本次运行是否超限
  3. SummarizationMiddleware 判断是否需要压缩历史上下文
  4. 模型调用时 → ModelRetryMiddleware 包裹调用，失败自动重试
  5. 重试耗尽 → ModelFallbackMiddleware 切换到备用模型
  6. 工具调用时 → ToolRetryMiddleware 包裹 database_tool 的执行
  7. 模型返回工具调用 → HumanInTheLoopMiddleware 拦截 send_email_tool 等待审批
  8. 审批通过后执行 → 输出经过 PIIMiddleware（输出层）再次脱敏

排列建议： 将"越通用、越靠输入侧"的中间件放前面（如 PII 输入过滤、成本限制），将"越具体、越靠输出侧"的放后面（如人工审批、输出校验）。容错类中间件（retry / fallback）使用 wrap 钩子，位置对执行顺序影响较小，通常放在中间即可。

最近更新:
贡献者: zhangxj_a_sc
🍃你是故意找茬是不是?
Copyright © 2026 Mr.Zhang