前言
大家好！最近在深耕 LangGraph 智能体开发时，很多小伙伴都会用到中间件功能，但对各类中间件的执行时机、适用场景一直模模糊糊，分不清 Node 样式和 Wrap 样式的区别，也不知道 before/after 系列钩子该在什么场景下使用。
今天我用最通俗、接地气的话，彻底讲明白 LangGraph 全部中间件执行时机，不用啃官方晦涩文档，看完直接上手开发、调试、日志埋点、请求拦截！
先简单铺垫一句：LangGraph 中间件核心作用就是 在智能体/模型/工具执行的前后插入自定义逻辑，比如打印日志、参数校验、请求修改、结果过滤、耗时统计、权限控制等，是开发企业级稳定智能体的必备功能。
LangGraph 中间件主要分为两大类：Node 样式（钩子型） 和 Wrap 样式（包装型），两类的执行逻辑和使用场景完全不同，下面分开拆解。
一、Node 样式中间件：精准的「前后钩子」
Node 样式可以简单理解为事件钩子，就是在某个核心动作「执行前」和「执行后」自动触发，每次动作执行都会单独跑一遍，粒度清晰、逻辑独立，是日常开发用得最多的样式。
它一共包含 4 个核心时机，我逐个通俗讲解，附带使用场景：
1. before_agent：Agent 启动前执行（每次调用必触发）
顾名思义，每一次智能体任务开始运行的一瞬间，最先执行这个钩子。
只要你调用一次 LangGraph 智能体 workflow，不管后续是否调用模型、是否调用工具，这个方法一定会先执行。
适用场景：
-
智能体任务初始化
-
请求参数校验、清洗、补全
-
全局任务日志初始化、生成任务 ID
-
权限校验、限流判断
简单理解：智能体上班前的「打卡准备工作」。
2. after_agent：Agent 执行完成后执行（每次调用必触发）
和 before_agent 对应，每一次智能体整个任务流程跑完、即将返回结果时触发，代表本轮智能体任务彻底结束。
不管中间调用了几次模型、几次工具，最终任务收尾时只会执行一次（单次智能体调用）。
适用场景：
-
统计单轮智能体任务总耗时
-
最终结果格式化、脱敏处理
-
任务收尾日志、异常结果汇总记录
-
全局资源释放
简单理解：智能体下班前的「工作总结收尾」。
3. before_model：每次大模型调用前执行
注意区分！这个不是智能体启动，是每一次请求 LLM 模型之前都会触发。
如果你的智能体一轮任务里，调用了 3 次大模型（多轮思考、多轮问答），这个钩子就会触发 3 次，粒度比 agent 钩子更细。
适用场景：
-
打印每次发给模型的 prompt 完整内容（调试神器）
-
动态修改 prompt、替换占位符
-
模型请求参数统一配置（温度、最大生成长度）
-
模型调用前置拦截、风控
4. after_model：每次大模型响应后执行
对应 before_model，每一次大模型返回结果后立刻触发，同样是调用几次模型，就触发几次。
适用场景：
-
打印模型返回的原始内容，排查幻觉、乱码问题
-
清洗模型返回的冗余内容、特殊符号
-
解析模型返回的 JSON/结构化数据，做容错处理
-
统计单次模型调用耗时、token 消耗
二、Wrap 样式中间件：全包式「包装拦截器」
如果说 Node 样式是「前后单独钩子」，那 Wrap 样式就是全包包装器。它不是拆分前后两个动作，而是把「整个调用过程」包裹起来，你可以在一个方法里同时处理 调用前、调用后、异常捕获、流程拦截 所有逻辑，灵活性更高，适合复杂定制场景。
LangGraph 提供两个核心 Wrap 包装方法：
1. wrap_model_call：包装每一次模型调用
专门包裹所有 LLM 模型的调用流程，每次向大模型发请求都会被这个包装器接管。
相比于 before_model + after_model 组合，wrap_model_call 的优势是：上下文连贯、可以统一捕获异常、可以直接中断模型调用、可以替换返回结果。
常用场景：
-
模型调用全局异常捕获（超时、报错自动重试）
-
统一统计所有模型调用的 token、耗时、成功率
-
动态拦截非法请求、敏感 prompt
-
灰度切换模型（根据场景自动切换 GPT、文心、通义等）
2. wrap_tool_call：包装每一次工具调用
专门包裹智能体的所有工具调用流程，比如调用搜索工具、计算器、数据库查询、API 接口等，每次执行工具都会被包裹拦截。
这是 Node 钩子没有的专属能力！Node 样式没有单独的工具前后钩子，想要管控工具调用，必须用 wrap_tool_call。
常用场景：
-
工具调用参数校验，防止非法参数导致报错
-
工具执行日志统一记录
-
工具调用超时控制、失败重试
-
禁止高危工具随意调用（权限管控）
-
工具返回结果二次加工、脱敏
三、核心区别总结（新手必看）
很多人学不会，就是分不清这两类样式，我一句话总结区别：
-
Node 样式（before/after）：拆分式钩子，只管「前」或「后」，逻辑简单、适合单纯日志、参数预处理，开箱即用。
-
Wrap 样式（wrap 包装）：全包式拦截，管全程，能捕获异常、能中断流程、能替换结果，适合复杂管控、重试、权限、监控场景。
四、极简使用场景选型建议
给大家整理一套直接抄的选型规则，开发时不用纠结：
要做智能体全局初始化/收尾 → 用 before_agent / after_agent
要调试 prompt、清洗模型输入输出 → 用 before_model / after_model
要管控模型调用异常、重试、监控 → 用 wrap_model_call
要管控工具调用、权限、重试、日志 → 必须用 wrap_tool_call
五、最后总结
LangGraph 中间件是构建企业级可观测、可管控、高稳定智能体的核心能力：
Node 四大钩子（before_agent/after_agent/before_model/after_model）主打简单高效，满足 80% 的日常调试、日志、参数处理需求；
Wrap 两大包装器（wrap_model_call/wrap_tool_call）主打全流程管控，解决异常、重试、权限、工具管控的复杂场景。
搞懂这 6 个执行时机，你就能精准把控 LangGraph 智能体的每一步执行流程，告别调试盲盒！
后续预告
后期会给大家带来 完整可运行的 LangGraph 中间件实战代码，包含日志打印、耗时统计、异常重试、工具拦截全套案例，需要的小伙伴可以点赞收藏关注！
