1. 从 middleware 到 HookDeepAgents 里那层被低估的“控制面”第一次翻 DeepAgents 源码的人十有八九会把注意力放在 agent loop 上——毕竟那是“大脑”是决定下一步干什么的地方。但真正跑过几个稍微复杂点的任务之后你会发现agent loop 本身其实相当“老实”它按部就班地推理、选工具、执行、观察结果然后进入下一轮。真正让一个 agent 从“能跑”变成“可控、可观测、可干预”的是挂在 loop 周围的那一圈 Hook。DeepAgents 系列的第二篇要聊的就是这六种 Hook 和两种范式。这个题目看起来像是文档目录但它背后其实回答了一个很实际的问题当 agent 的行为不符合预期时你到底能在哪些点上插手是只能在 prompt 里求它“乖一点”还是能在执行链路的某个确定位置做确定的事我自己的体会是早期做 agent 项目时最痛苦的不是模型能力不够而是“它做了我不想要的事但我不知道在哪拦”。比如它连续调了五次同一个搜索工具、比如它在写文件之前没有先读原文件、比如它把一段明显是幻觉的内容当成了事实继续往下推。这些问题如果只能靠改 prompt 解决那基本等于碰运气。Hook 的价值就在于它把这些“碰运气”变成了“可编程”。关键词里出现的 middleware、agent loop、LangGraph 其实是一条线索DeepAgents 的 Hook 机制并不是凭空造出来的它和 LangGraph 的图执行模型、和传统 middleware 的拦截思想都有血缘关系。理解这层关系比死记六个 Hook 的名字重要得多。这篇就按我实际读代码和踩坑的顺序把这六种 Hook 逐个拆开再讲清楚两种范式到底在选什么。2. 六种 Hook 各自守在哪一道关口2.1 为什么 Hook 要分六种而不是一种一个自然的疑问是既然都是“拦截”为什么不做成一个通用的 before/after 钩子答案藏在 agent 执行链路的异质性里。agent 的一轮循环里至少有几类性质完全不同的动作模型调用LLM call、工具调用tool call、状态更新state update、以及循环本身的控制流loop control。这四类动作的输入输出结构、失败模式、可干预程度都不一样。如果只有一个通用 Hook你要么拿到一个巨大的 context 对象自己判断“现在是什么阶段”要么就得在 Hook 内部写一堆 if-else。DeepAgents 选择拆成六种本质上是把“判断当前处于哪个阶段”这件事从用户代码里挪到了框架层。你注册哪个 Hook框架就知道你想干预哪一类动作context 也是为那类动作量身定制的。这六种 Hook 大致可以按“干预时机”和“干预对象”两个维度来理解。按时机分有循环开始前、模型调用前后、工具调用前后、循环结束后按对象分有面向消息的、面向工具调用的、面向状态的。下面逐个说但我不打算按官方文档的顺序而是按“你实际最可能用到”的顺序来排。2.2 模型调用前后的 Hook最常用也最容易写错模型调用前后的 Hook 是我在项目里用得最多的一类。它的典型用途包括在发给模型之前裁剪上下文、注入系统级约束、记录 token 消耗在模型返回之后做输出校验、格式修正、敏感内容过滤。这里有个很容易踩的坑很多人会把“裁剪上下文”写成“删除旧消息”。看起来没问题但 agent 的推理依赖消息之间的因果链你删掉中间某条工具返回结果模型下一轮就会看到一个“调用了工具但没有结果”的断裂上下文行为会变得很奇怪。正确的做法通常是做摘要压缩或者按轮次整体丢弃而不是随机删单条。另一个坑是“在 before 里改 prompt 却在 after 里按原 prompt 校验”。我见过一个案例before Hook 往 system prompt 里追加了一段“必须用 JSON 输出”的约束after Hook 却还在用正则去匹配自然语言格式结果永远校验失败。Hook 之间是有状态耦合的写的时候要意识到你改了什么后面的 Hook 得知道。def before_model_call(state, config): messages state[messages] # 按轮次压缩而不是删单条 if len(messages) MAX_TURNS * 2: messages compress_oldest_turns(messages, keep_recentMAX_TURNS) return {messages: messages} def after_model_call(state, config): last state[messages][-1] # 校验逻辑要和 before 里注入的约束保持一致 if not is_valid_json(last.content): return {messages: [repair_message(last)]} return {}2.3 工具调用前后的 Hook权限与副作用的真正闸门如果说模型调用 Hook 管的是“想什么”那工具调用 Hook 管的就是“做什么”。这是安全性和可控性最关键的一道关口。工具调用前的 Hook 可以做参数校验、权限检查、危险操作拦截工具调用后的 Hook 可以做结果清洗、错误重试、副作用确认。我印象最深的一次事故是 agent 在调试模式下把生产数据库的某张表清了。事后复盘问题不在于模型“坏”而在于没有任何一道 Hook 去检查工具名和参数。如果当时有一个工具调用前 Hook判断tool_name execute_sql且参数里包含DELETE或DROP就拦截这事根本不会发生。工具调用后的 Hook 同样重要但常被忽略。工具返回的结果往往不是模型能直接消化的格式——可能是一个巨大的 JSON、可能包含一堆无关字段、可能是分页的第一页。在 after Hook 里做结果规整比让模型自己去“理解”原始返回要可靠得多。注意工具调用 Hook 里做重试要非常小心。如果工具本身有副作用比如发邮件、写文件盲目重试会造成重复副作用。重试逻辑应该只针对幂等工具或者配合幂等键使用。2.4 状态更新与循环控制 Hook让 agent 知道“该停了”状态更新 Hook 和循环控制 Hook 是六种里最不显眼、但决定 agent 稳定性的两种。状态更新 Hook 关注的是 agent 内部状态比如 scratchpad、任务列表、中间变量的变更循环控制 Hook 关注的是“这一轮结束后是继续还是终止”。很多 agent 跑飞的根本原因不是模型不行而是没有明确的终止条件。模型会一直觉得“还有事没做完”于是无限循环。循环控制 Hook 就是给你一个确定的位置去判断任务是否完成、是否超预算、是否连续多轮没有进展。连续无进展检测尤其有用——如果连续三轮工具调用返回的结果高度相似基本可以判定卡住了这时候主动终止比让它继续烧 token 明智得多。状态更新 Hook 的一个实用场景是维护任务清单。agent 在多步任务里经常“忘记”自己做到哪了你可以在状态更新 Hook 里强制维护一个结构化的 todo 列表每轮检查是否有未完成项避免它提前收工或者重复劳动。2.5 六种 Hook 的对照速查Hook 类型干预时机典型用途最容易踩的坑循环开始前loop 启动初始化状态、加载配置状态未初始化导致后续 Hook 报错模型调用前LLM call 之前上下文裁剪、约束注入随机删消息破坏因果链模型调用后LLM call 之后输出校验、格式修正与 before 注入的约束不一致工具调用前tool call 之前权限检查、参数校验漏检危险工具名工具调用后tool call 之后结果清洗、幂等重试对非幂等工具盲目重试循环控制每轮结束终止判断、预算控制无进展检测缺失导致死循环这张表我建议贴在显示器边上。写 Hook 的时候先问自己我要干预的是哪一类动作对应哪个 Hookcontext 里有没有我需要的信息想清楚这三个问题大部分 Hook 都能一次写对。3. 两种范式装饰器式注册 vs 图节点式编排3.1 两种范式到底在争什么DeepAgents 的 Hook 有两种接入范式一种更接近传统 middleware 的装饰器式注册一种更接近 LangGraph 的图节点式编排。这两种范式不是“新旧替代”关系而是面向不同复杂度场景的两套工具。选错了不会跑不起来但会让代码在后期变得难以维护。装饰器式注册的核心是“声明”你写一个函数用装饰器标注它是哪类 Hook框架在运行时自动把它挂到对应位置。优点是写起来快、读起来直观适合 Hook 数量少、逻辑独立的场景。缺点是当 Hook 之间有依赖、需要条件性启用、或者需要动态调整顺序时装饰器就不够用了。图节点式编排的核心是“显式连接”你把 Hook 当作图里的节点自己定义节点之间的边和条件。优点是控制力强、顺序明确、便于调试和可视化。缺点是样板代码多简单场景下显得杀鸡用牛刀。3.2 装饰器式什么时候它是最优解如果你的项目满足这几个条件装饰器式基本就是最优解Hook 数量在十个以内、每个 Hook 职责单一、Hook 之间没有顺序依赖、不需要运行时动态开关。比如一个内部用的文档处理 agent只需要在模型调用前裁剪上下文、在工具调用前检查文件路径合法性两个 Hook 各管各的装饰器写起来五行代码搞定。hook(before_model_call) def trim_context(state, config): ... hook(before_tool_call) def check_path(state, config): ...这种写法的心智负担极低新人接手也能一眼看懂。我个人的经验是能用装饰器解决的就别上图图带来的灵活性在简单场景里是纯负担。3.3 图节点式复杂度上来了才值得什么时候必须上图我总结了几条触发线Hook 之间有明确的前后依赖比如必须先做权限检查再做参数脱敏、需要根据运行时状态决定是否执行某个 Hook、需要把 Hook 的执行结果反馈到 agent loop 的控制流里、或者需要把 Hook 链路可视化给非技术同事看。图节点式的一个典型场景是“分级审批”。低风险工具直接放行中风险工具需要参数校验通过高风险工具需要人工确认节点介入。这种带条件分支和人工介入的流程用装饰器写会变成一团乱麻用图来表达则一目了然。graph.add_node(risk_check, risk_check_node) graph.add_node(human_approval, human_approval_node) graph.add_conditional_edges( risk_check, route_by_risk, {low: execute, mid: validate, high: human_approval} )3.4 混用是常态但要有边界实际项目里纯装饰器或纯图的情况都少混用才是常态。我的建议是划一条清晰的边界无状态、无依赖的横切关注点日志、token 统计、简单校验用装饰器有状态、有分支、涉及控制流的用图。这条边界一旦模糊代码就会变成“一半在图里一半在装饰器里谁也说不清执行顺序”的灾难。提示混用时务必在文档或代码注释里明确标注每个 Hook 用的是哪种范式、挂在哪一层。我吃过这个亏——半年后回看自己的代码花了半小时才理清某个校验到底是在装饰器层还是图节点层执行的。4. 把 Hook 挂进 agent loop一次完整的执行链路复盘4.1 一轮循环里 Hook 的触发顺序光知道有六种 Hook 还不够得知道它们在一轮循环里的实际触发顺序。我按一次典型的“模型推理 → 工具调用 → 状态更新 → 判断是否继续”流程把触发点串一遍。循环开始前 Hook 最先触发负责初始化这一轮需要的上下文。接着进入模型调用前 Hook此时你可以修改即将发给模型的消息。模型返回后模型调用后 Hook 触发你可以校验或修正输出。如果模型决定调用工具工具调用前 Hook 触发做检查工具执行完工具调用后 Hook 触发做结果处理。工具结果写回状态时状态更新 Hook 触发。一轮结束循环控制 Hook 判断是否继续。这个顺序不是随便定的它反映了数据在系统里的自然流向。理解顺序的意义在于你知道在某个 Hook 里能拿到什么、改了什么会影响后面的谁。比如你在模型调用后 Hook 里改了消息内容那工具调用前 Hook 看到的就是改过之后的内容。4.2 一个真实的多步任务拆解拿一个“读取项目里的配置文件修改某个字段然后写回”的任务举例。这个任务看起来简单但涉及读文件、改内容、写文件三个工具调用中间还有模型推理。第一轮循环开始前 Hook 初始化任务状态。模型调用前 Hook 注入“先读后写”的约束。模型决定调用读文件工具。工具调用前 Hook 检查路径是否在允许目录内。工具执行返回文件内容。工具调用后 Hook 把内容规整成模型易读的格式。状态更新 Hook 记录“已读取”。第二轮模型基于文件内容生成修改后的版本。模型调用后 Hook 校验输出是否是合法配置格式。模型决定调用写文件工具。工具调用前 Hook 检查是否已经读过这个文件如果状态里没有“已读取”记录拦截。这是防止 agent 盲目覆盖的关键。第三轮写文件成功。循环控制 Hook 检测到任务完成终止循环。这个链路里如果没有“先读后写”的检查agent 完全可能直接覆盖原文件造成数据丢失。Hook 在这里扮演的不是“锦上添花”而是“底线保障”。4.3 Hook 之间的数据怎么传Hook 之间传递数据靠的是共享的 state 对象。这里有个设计上的取舍state 是全局可变的好还是每轮返回新对象好DeepAgents 倾向于后者——每个 Hook 返回一个增量框架负责合并。这样做的好处是 Hook 之间解耦坏处是你得清楚合并规则。我踩过的坑是两个 Hook 都往同一个 key 写值后执行的覆盖了先执行的而且没有任何警告。排查了半天才发现是 key 冲突。后来我养成的习惯是给每个 Hook 写的 state key 加前缀比如auth_check_passed、token_count_this_turn避免撞车。5. 那些文档不会告诉你的 Hook 实战坑5.1 异常处理Hook 抛异常了会怎样这是最容易被忽略的问题。Hook 里抛异常框架是吞掉继续、还是中断整个 loop不同 Hook 的行为可能不一样。我的经验是模型调用前和工具调用前的 Hook 抛异常通常应该中断当前操作因为检查没通过就不该继续而日志类、统计类的 Hook 抛异常应该被吞掉不能因为记日志失败就搞挂整个 agent。所以写 Hook 时要有意识地区分“关键 Hook”和“辅助 Hook”。关键 Hook 里该抛就抛辅助 Hook 里一律 try-except 包住。我见过因为一个统计 token 的 Hook 里除了零导致整个任务失败的案例非常不值。5.2 性能Hook 不是免费的每个 Hook 都是一次函数调用如果 Hook 里做了重活比如调外部 API 做内容审核那它会直接拖慢整个 loop。我实测过一个场景在模型调用后 Hook 里同步调用一个审核服务每次增加 300ms一个十轮的任务就多花 3 秒。后来改成异步 缓存才把开销压下去。原则是Hook 里只做必要的、快的操作。重活要么异步化要么挪到 loop 外面批量做。别让 Hook 成为性能瓶颈。5.3 调试怎么知道 Hook 到底跑没跑Hook 不生效是高频问题。原因通常有三类注册的 Hook 名字拼错了、Hook 挂在了错误的范式层、或者条件判断让它根本没进。我的调试方法是在每个 Hook 入口打一行日志带上 Hook 名和关键 state 字段。跑一次任务看日志顺序对不对。这比盯着代码猜快得多。5.4 顺序依赖谁先谁后不是小事同一类 Hook 注册了多个时执行顺序由注册顺序决定。这个顺序在“检查类”和“修改类” Hook 混在一起时特别关键。比如一个 Hook 做权限检查、另一个 Hook 做参数脱敏如果脱敏先执行权限检查看到的就不是原始参数可能漏判。我的做法是把检查类 Hook 统一注册在修改类之前并在代码里用注释标明依赖关系。6. 从 LangGraph 的视角重新理解 Hook6.1 Hook 本质上是图上的拦截节点把 DeepAgents 的 Hook 放到 LangGraph 的语境里看它其实就是图执行过程中的拦截节点。LangGraph 的图由节点和边组成Hook 相当于在特定边上插入的一个“检查站”。这个视角的价值在于你可以用图论的方式思考 Hook 的编排——哪些是串行的、哪些可以并行、哪些需要条件分支。一旦这么想很多设计问题就清晰了。比如“多个独立校验能不能并行”这个问题在图视角下就是“这几个节点之间有没有边”没有边就可以并行。装饰器范式下你很难表达并行图范式下这是天然的。6.2 middleware 思想在 agent 场景的迁移传统 web 框架里的 middleware 是“请求进来、层层处理、响应出去”的洋葱模型。DeepAgents 的 Hook 借鉴了这个思想但做了适配agent 的“请求”不是一次性的而是循环往复的所以 Hook 也不是一次性的洋葱而是每轮都要过的关卡。理解这个差异很重要。web middleware 里你写一次逻辑请求生命周期内只跑一次agent Hook 里你写的逻辑每一轮循环都会跑。这意味着 Hook 里的逻辑必须考虑“重复执行”的语义——比如计数、比如状态累积不能假设只跑一次。6.3 什么时候该跳出 Hook 思维Hook 不是万能的。有些需求用 Hook 实现会非常别扭比如“根据任务类型动态选择不同的 agent 拓扑”。这种需求本质上是“编排”而不是“拦截”应该在图构建层面解决而不是硬塞进 Hook。我的判断标准是如果这个逻辑需要知道“整个任务的全貌”而不只是“当前这一步”那它大概率不该是 Hook。7. 选型建议什么项目该用哪种范式7.1 按项目阶段选项目早期我强烈建议用装饰器式。快速验证、快速迭代别过早引入图的复杂度。等 Hook 逻辑稳定了、依赖关系清晰了再考虑要不要迁移到图。反过来一上来就上图往往会在需求还没定型时被图的样板代码拖累。7.2 按团队规模选一个人开发装饰器足够。三个人以上协作尤其是有人负责 Hook 逻辑、有人负责 agent 主流程时图节点式的显式连接会大幅降低沟通成本——因为执行顺序是画出来的不是猜出来的。7.3 按可观测性需求选如果这个 agent 要上生产、要给别人看执行过程、要做审计图节点式几乎是必选。因为图天然可以可视化每个节点的输入输出都能被记录。装饰器式的执行链路是隐式的做审计要额外埋很多点。场景推荐范式理由原型验证、单人开发装饰器式上手快样板少Hook 逻辑稳定、数量少装饰器式心智负担低多 Hook 有顺序依赖图节点式顺序显式可控需要人工介入节点图节点式条件分支天然支持生产环境、需审计图节点式可可视化、可追溯横切关注点日志、统计装饰器式无状态、无依赖这张表不是绝对的但它覆盖了我遇到的大部分决策场景。核心判断依据就一条这个 Hook 需不需要知道“全局”和“顺序”需要就上图不需要就装饰器。8. 我在实际项目里沉淀下来的几条经验写 Hook 这件事写得越多越觉得它像给 agent 装护栏。护栏装得好agent 跑得野一点也没关系护栏装得差agent 稍微一偏就出事。我自己的几条经验都是踩坑换来的。第一条先写循环控制 Hook再写其他。很多人从模型调用 Hook 开始写结果 agent 跑飞了才发现没有终止条件。循环控制 Hook 是保命的应该最先到位。第二条每个 Hook 只做一件事。我见过一个 Hook 里同时做权限检查、参数脱敏、日志记录、结果缓存后来想改其中任何一项都不敢动因为牵一发动全身。拆开写哪怕 Hook 数量多一点维护成本反而低。第三条Hook 里的判断要保守。宁可多拦一次让 agent 重试也不要放过一次危险操作。拦截的代价是重试放过的代价可能是数据损坏。这个不对称性决定了 Hook 的默认姿态应该是“怀疑”。第四条给 Hook 写测试。Hook 是纯函数居多测试起来其实很容易。构造一个 state调用 Hook断言返回值。我现在的习惯是每个关键 Hook 都配一个单测改逻辑时先跑测试比手动跑 agent 快得多。第五条记录 Hook 的决策。每次 Hook 拦截或修改都往日志里写一条“谁、在什么条件下、做了什么决定”。出问题时这份日志就是排查的起点。没有它你只能看到 agent 行为异常却不知道是哪道关卡放行的。这六种 Hook 和两种范式说到底是一套“在正确的位置做正确干预”的方法论。工具本身不复杂难的是判断在哪个位置干预、用什么方式干预。这个判断力只能靠一次次实际项目里踩坑积累。我到现在也不敢说自己完全摸透了但至少知道哪些坑不该再踩第二遍。