LobeHub Agent Runtime Hooks 生命周期机制解析从 execAgent 注册到 HookDispatcher 分发的完整指南【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub导读LobeHub 将分散的 Agent 编排为 7×24 持续运行的操作体系而Agent Runtime HooksAgent 运行时生命周期钩子正是这套体系的可观测 可拦截基础设施它允许你在 Agent 单次执行的各个关键节点步骤开始/结束、工具调用前后、人工审批、上下文压缩、子 Agent 调用挂载回调实现成本与 Token 监控、结果拦截、工具 Mock、子 Agent 调度追踪等能力。读完本文你将掌握 LobeHub 钩子系统的完整骨架——16 种钩子如何按 5 大类组织、事件负载Event Payload包含哪些字段、本地内存模式与生产 Webhook 模式如何切换以及如何用真实代码在自己的execAgent({ hooks })调用中落地一套评测 / 观测 Hook。本文对应的权威来源是仓库内.agents/skills/agent-runtime-hooks/SKILL.md供 Agent 使用的运行时钩子技能文档其关键实现均可在packages/agent-runtime与apps/server下找到一一对应的源码。一、什么是 Agent Runtime Hooks为Agent 执行量身定制的观察点Agent 的一次execAgent执行也被称为一次 operation并不是一个黑盒在内部它会经历「思考call_llm→ 调用工具call_tool→ 请求人工审批request_human_approve→ 压缩上下文compress_context→ 调用子 AgentcallAgent」等多个子流程。LobeHub 把每个子流程的关键转折点抽象为一组Hook 事件类型Hook Type并通过HookDispatcher分发器统一负责注册与回调。理解这套机制要抓住三个关键词Per-operation按操作作用域Hooks 不是全局的而是通过execAgent({ hooks })针对某一次 Agent 操作临时注册操作结束即自动清理Observable Interceptable可观测且可拦截绝大多数钩子只做观察fire-and-forget唯独beforeToolCall支持通过event.mock()返回假结果从而跳过真实工具执行双模式分发本地模式local mode直接以内存方式调用 JS 处理函数生产模式queue/webhook 模式则把钩子序列化并通过 HTTP POST / QStash 投递给外部 Webhook 端点。整体拓扑可以直观地用 SKILL.md 中的分层图表达execAgent({ hooks }) │ ├─ beforeStep ──────────── Before each step executes │ │ │ ├─ [call_llm] LLM inference │ │ │ ├─ [call_tool] │ │ ├─ beforeToolCall ── Before tool executes (supports mocking) │ │ ├─ (tool execution) │ │ ├─ afterToolCall ─── After tool completes (observation only) │ │ └─ onToolCallError ─ Tool threw an exception │ │ │ ├─ [request_human_approve] │ │ ├─ beforeHumanIntervention ── Before agent pauses │ │ ├─ afterHumanIntervention ─── After approve/reject resume │ │ └─ onStopByHumanIntervention ── User rejected, agent halted │ │ │ ├─ [compress_context] │ │ ├─ beforeCompact ──── Before compression starts │ │ ├─ afterCompact ───── After compression completes │ │ └─ onCompactError ─── Compression failed │ │ │ ├─ [callAgent] (via execSubAgentTask) │ │ ├─ beforeCallAgent ── Before sub-agent starts │ │ ├─ afterCallAgent ─── After sub-agent completes │ │ └─ onCallAgentError ── Sub-agent failed │ │ │ └─ afterStep ──────────── After step completes │ ├─ (next step...) │ ├─ onComplete ───────────── Operation reaches terminal state └─ onError ──────────────── Error during execution二、五大类 16 种钩子总览SKILL.md 明确给出钩子系统共16 种 Hook 类型划分到 5 大类别。在packages/agent-runtime/src/types/hooks.ts中这 16 种被定义为一个字符串联合类型AgentHookType类别钩子类型触发时机主要事件负载类型步骤级 Step LevelbeforeStep/afterStep每一步执行前 / 每步完成后AgentHookEvent步骤级 Step LevelonComplete操作到达终态done/error/interrupted/max_steps/cost_limitAgentHookEvent步骤级 Step LevelonError执行过程中出错AgentHookEvent工具调用级 Tool CallbeforeToolCall工具执行前支持event.mock()拦截ToolCallHookEvent工具调用级 Tool CallafterToolCall工具执行完成后仅观察AfterToolCallHookEvent工具调用级 Tool CallonToolCallError工具抛出异常catch 块而非仅successfalseToolCallErrorHookEvent人工干预级 HumanbeforeHumanInterventionAgent 暂停等待审批前BeforeHumanInterventionHookEvent人工干预级 HumanafterHumanIntervention审批通过/拒绝并恢复后AfterHumanInterventionHookEvent人工干预级 HumanonStopByHumanIntervention用户拒绝、Agent 被中止StopByHumanInterventionHookEvent上下文压缩级 CompactbeforeCompact/afterCompact压缩开始前 / 完成后BeforeCompactHookEvent/AfterCompactHookEvent上下文压缩级 CompactonCompactError压缩失败CompactErrorHookEvent子 Agent 级 CallAgentbeforeCallAgent/afterCallAgent调用子 Agent 前 / 子 Agent 完成后BeforeCallAgentHookEvent/AfterCallAgentHookEvent子 Agent 级 CallAgentonCallAgentError子 Agent 失败CallAgentErrorHookEvent说明5 大类别即 Step Level4 种 Tool Call3 种 Human Intervention3 种 Context Compression3 种 Sub-Agent CallAgent3 种合计正好 16 种与AgentHookType定义逐一对应。所有事件负载Event类型都集中在 packages/agent-runtime/src/types/hooks.ts服务端则通过 apps/server/src/services/agentRuntime/hooks/types.ts 对这些纯数据类型做 re-export并追加服务端专有的AgentHook、AgentHookWebhook、SerializedHook等注册/序列化类型。事件类型放在共享的lobechat/agent-runtime包中注册与分发机制放在 server 层——这样保证了前端/服务端/Worker 等多端共享同一套事件契约。三、注册到分发一次 Hook 调用的完整生命周期3.1 最小注册示例SKILL.md 给出了最核心的用法——把 Hook 数组作为hooks参数传给execAgentconst hooks: AgentHook[] [ { id: my-hook, type: afterStep, handler: async (event) { /* ... */ } }, ]; await aiAgentService.execAgent({ agentId, prompt, hooks });内部流程可拆解为三步注释即 SKILL.md 给出的内部行为说明// Internally: hookDispatcher.register(operationId, hooks) // Cleanup: hookDispatcher.unregister(operationId)即execAgent在内部获得一个 operationIdHookDispatcher.register按operationId → AgentHook[]的关系把钩子存入内存 Map执行结束后由unregister(operationId)清理避免钩子泄漏到下一次操作。3.2 AgentHook 的四个字段在 apps/server/src/services/agentRuntime/hooks/types.ts 中AgentHook被定义为字段类型含义idstring唯一标识用于日志、调试与幂等判断typeAgentHookType挂在哪个生命周期点handler(event: AgentHookEvent) Promisevoid本地模式的回调函数进程内直接调用webhook可选AgentHookWebhook生产模式下的投递配置不配置则钩子只工作在本地模式其中handler统一返回Promisevoid这是「所有钩子都是 fire-and-forget、错误不影响主流程」这一设计约束的直接体现详见第六节。3.3 HookDispatcher注册 / 分发 / 查询 / 清理的中央枢纽实现位于 apps/server/src/services/agentRuntime/hooks/HookDispatcher.ts核心是一个模块级单例hookDispatcher内部维护Mapstring, AgentHook[]operationId → hooks。对外暴露以下方法register(operationId, hooks)把钩子追加进对应 operation 的列表并打 debug 日志Registered N hooks: type:id, ...unregister(operationId)删除该 operation 的全部钩子Scoped per operation的落地实现dispatch(operationId, type, event, serializedHooks?)按事件类型过滤出钩子并逐个执行/投递dispatchBeforeToolCall(operationId, event)专门处理beforeToolCall返回{ isMocked: true, result } | nullhasHooks(operationId)/hasHook(operationId, hookId)/getSerializedHooks(operationId)查询与序列化辅助。从apps/server/src/services/agentRuntime/AgentRuntimeService.ts的源码可以印证这套调用链的存在该服务在 operation 开始时调用hookDispatcher.register(operationId, hooks)对应源码中的 register 调用点随后在步骤、完成等节点调用hookDispatcher.dispatch(...)最终统一执行hookDispatcher.unregister(operationId)做收尾清理。步骤执行器则集中在 apps/server/src/modules/AgentRuntime/RuntimeExecutors.ts——它通过createAgentRuntimeExecutors(buildHost(ctx))生成工具、压缩、人工干预等各类指令执行器钩子的dispatchBeforeToolCall返回值mock 结果或 null正是在这里被消费决定后续是走真实工具还是直接采用假结果。3.4 生产模式Webhook 序列化投递本地模式的 handler 是 JS 函数无法跨进程/跨机器传递因此 LobeHub 提供了 Webhook 通道序列化getSerializedHooks()只保留id / type / webhookhandler 函数无法序列化服务端将序列化结果持久化到AgentState.metadata._hooks以及topic.metadata.runningOperation.hooks投递deliverWebhook()支持两种 delivery——fetch普通 HTTP POST与qstash通过 QStash 可靠投递且支持fallback: fetch | none策略。若配置了fallback: none投递失败会被当作关键错误抛出CriticalHookDeliveryError因为这类 Webhook 承载控制流例如子 Agent 的 resume 桥接丢失会导致消费方永久挂起事件字段裁剪eventFields?: (keyof AgentHookEvent)[]用于控制 payload 只包含指定字段无论是否裁剪finalState都会被排除它是本地模式才有的深状态不序列化进 Webhook payload。// AgentHookWebhook 的核心结构见 hooks/types.ts interface AgentHookWebhook { url: string; delivery?: fetch | qstash; // 默认 fetch fallback?: fetch | none; // qstash 失败时回退策略 eventFields?: (keyof AgentHookEvent)[]; // 默认包含全部可序列化字段 body?: Recordstring, unknown; // 附加自定义 metadata }Webhook 模式不支持beforeToolCall的 MockMock 依赖进程内共享的 handler 闭包这一点也符合下一节要讲的「Local only」设计约束。四、16 个钩子的事件负载逐个拆解4.1 步骤级beforeStep/afterStep/onComplete/onError四个步骤级钩子的event统一为AgentHookEvent。它是一份非常厚的通用事件在 packages/agent-runtime/src/types/hooks.ts 中定义了数十个可选字段按用途可分成几组标识字段agentId、userId、operationId、topicId步骤定位stepIndex、stepLabel如图谱节点名、stepTypecall_llm/call_tool、steps内容字段contentLLM 文本输出、reasoning思考内容、lastAssistantContent、lastLLMContent上一步的 LLM 内容用于工具执行期间展示上下文统计字段cost/stepCost/totalCost、duration/elapsedMs自操作开始以来的毫秒数、executionTimeMs本步耗时、llmCalls、toolCalls/totalToolCalls、totalInputTokens/totalOutputTokens/totalTokens决策字段shouldContinue、thinking下一步是否 LLM 思考、toolsCallingLLM 决定调用的工具、toolsResult工具执行结果终态字段主要在onComplete上statusdone | error | interrupted | waiting_for_human、reasondone | error | interrupted | max_steps | cost_limit错误字段主要在onError上errorMessage、errorDetail、errorType稳定错误码如NoAvailableProvider、InvalidProviderAPIKey、errorAttribution来自 model-runtime 错误分类user | provider | harness | system告诉消费方该由谁修复附件字段attachmentsHookEventAttachment[]onComplete时从最终助手消息的多模态 content 中提取的图片/文件/音视频附件供机器人回拨转发给 IM 平台元数据metadata调用方自定义来自 webhook.body。各钩子职责beforeStep每一步执行前触发。可结合shouldContinue之类字段做步进控制的前置判断注意shouldContinue的语义要以具体消费方为准SDK 未强制要求返回afterStep每步完成后触发携带本步内容、工具调用、费用与累计 token 等完整快照是做日志、成本核算、评测采样的主力钩子onComplete操作到达终态时触发一次reason会区分done / error / interrupted / max_steps / cost_limit并携带attachments与累计totalCostonError出错时触发消费方应优先 switcherrorType稳定错误码而不是对自由文本的errorMessage做模式匹配。4.2 工具调用级beforeToolCallMock/afterToolCall/onToolCallErrorbeforeToolCall—— 唯一的可拦截钩子event为ToolCallHookEvent{ (identifier, apiName, args, callIndex, stepIndex, operationId, mock); }字段含义identifier工具标识例如插件工具xxx.web-search、apiName工具具体 API 名、args调用参数对象、callIndex单步内第几次工具调用、stepIndex第几步、operationId。mock是回调函数签名在类型定义中为mock: (result: ToolRunResult) boolean——返回 false 表示更早的钩子已经抢占了 mock 名额。它让调用方在真实工具执行前注入假结果event.mock({ content: {error:rate limited} });分发层面dispatchBeforeToolCall只会对本地内存钩子生效返回{ isMocked: true, result } | null执行器拿到非空结果即可跳过真实工具调用。SKILL.md 特别提醒Mock 只在本地模式内存钩子有效Webhook 模式不支持 Mock。afterToolCall—— 纯观察event为AfterToolCallHookEvent在工具完成之后触发{ (identifier, apiName, args, callIndex, content, success, mocked, executionTimeMs, stepIndex); }其中mocked标记本次结果是否为 mock 所得success表示工具是否成功content为工具返回文本executionTimeMs为真实执行耗时。onToolCallError—— 异常专属event为ToolCallErrorHookEvent{ (identifier, apiName, args, callIndex, error, stepIndex); }它和afterToolCall的区别值得强调afterToolCall即使successfalse也属于正常返回路径而onToolCallError只在**工具真正抛出异常catch 块**时触发字段中的error为异常信息字符串。4.3 人工干预级审批三连当 Agent 需要执行高风险工具时会进入审批流程相关钩子负责把暂停/恢复/中止的边界暴露给外部// beforeHumanIntervention暂停前 { operationId, stepIndex, pendingTools: [{ identifier, apiName }] } // afterHumanIntervention用户 approve/reject 并恢复后 { operationId, action: approve | reject | rejectAndContinue, toolCallId?, rejectionReason? } // onStopByHumanIntervention用户拒绝导致 Agent 中止 { operationId, toolCallId?, rejectionReason? }三者语义递进beforeHumanIntervention给你一次预通知此时能拿到所有等待审批的工具清单pendingTools用户做出决定后afterHumanIntervention会携带actionapprove通过 /reject拒绝 /rejectAndContinue拒绝但让 Agent 继续以及被拒工具的toolCallId和rejectionReason而一旦用户拒绝导致整个 Agent 被中止halted则只有onStopByHumanIntervention会收到通知。审批的 resume/reject 动作由apps/server/src/services/agentRuntime/AgentRuntimeService.ts承接SKILL.md 的 Key Files 表中标注其为 Step hooks HumanIntervention resume/reject。4.4 上下文压缩级beforeCompact/afterCompact/onCompactError长对话逼近窗口上限时会触发上下文压缩compact压缩相关事件设计为压缩前测量、压缩后报告、失败时报警// beforeCompact压缩开始前 { (operationId, stepIndex, messageCount, tokenCount) } // afterCompact压缩完成后 { (operationId, stepIndex, groupId, messagesBefore, messagesAfter, summary) } // onCompactError压缩失败 { (operationId, stepIndex, tokenCount, error) }beforeCompact让你在压缩前记录当时的消息量与 token 量afterCompact给出压缩组的groupId、压缩前后的消息数messagesBefore/messagesAfter以及压缩摘要summary适合做上下文预算的统计归因onCompactError在压缩抛出异常时触发携带当时的tokenCount便于评估是不是因为上下文太大而失败。4.5 子 Agent 级CallAgent在父操作上监听子任务当主 Agent 通过execSubAgentTask调度子 Agent 时相关钩子统一在父 operation 上触发而不是子 operation 上// beforeCallAgent子 Agent 启动前 { (operationId, agentId, instruction) } // afterCallAgent子 Agent 完成后 { (operationId, agentId, subOperationId, threadId, success) } // onCallAgentError子 Agent 失败 { (operationId, agentId, error) }其中operationId是父操作 IDsubOperationId是子 Agent 对应的新 operation IDthreadId为子 Agent 使用的会话线程。SKILL.md 特意给出一个使用前提CallAgent 钩子要求ExecSubAgentTaskParams中携带parentOperationId否则无法把子任务关联回父操作的钩子作用域。子 Agent 调度路径的实现位于 apps/server/src/services/aiAgent/subAgentRuns.tsCallAgent 钩子的 dispatch 正是由它负责。五、设计要点解读这套机制的底层契约SKILL.md 的 Design Notes 值得逐条展开因为它们决定了你在实践中能做什么、不能做什么Fire-and-forget即发即弃所有 handler 都返回Promisevoid单次回调抛错不会影响主执行流。实现上HookDispatcher.dispatch对每个本地 hook 都包了 try/catch错误只进 debug 日志注释直接写明 Hook errors should NOT affect main execution flow。唯一例外是fallback: none的关键 Webhook——它会以CriticalHookDeliveryError的形式让队列执行失败以便重试而不是让消费方永久失联唯一的拦截点常规钩子只是看beforeToolCall是唯一能通过event.mock()篡改结果的能力。实现中dispatchBeforeToolCall()串行执行所有beforeToolCall钩子一旦某个 handler 调用了mock(result)后续钩子不再执行并直接返回 mock 结果同类型钩子按注册顺序串行执行register把钩子追加到数组尾部dispatch按数组顺序 await因此先注册的钩子优先拿到事件也优先抢占 mock 名额Mock 仅本地有效beforeToolCall的 mock 依赖进程内 handlerWebhook 模式只能投递观察事件类型层面也区分了ToolCallHookEvent与不带mock的BeforeToolCallObservationEvent按操作作用域自动清理operationId → hooks的 Map 设计 结束时unregister(operationId)保证钩子不会跨操作泄漏、也不会因长驻服务而膨胀Sandbox / MCP 没有独立钩子沙箱、MCP 工具最终都走executeTool这条统一出口因此beforeToolCall/afterToolCall天然覆盖它们只需用event.identifier做过滤即可区分具体工具来源。六、实战在 execAgent 中注册一套可复用的 Hook结合AgentHook结构、事件字段与上述设计约束一个同时覆盖「评测 成本 Mock」的完整示例大致如下import { aiAgentService } from /server/services/aiAgent; const hooks [ // 1) 每步结束后累计成本与 token观测 { id: cost-observer, type: afterStep, handler: async (event) { if (event.totalCost ! undefined) { console.log( [step ${event.stepIndex}] stepCost${event.stepCost} total${event.totalCost} tokens${event.totalTokens}, ); } }, }, // 2) 终态上报评测用例通过 onComplete 断言 reason / attachments { id: completion-reporter, type: onComplete, handler: async (event) { console.log(operation ${event.operationId} finished: reason${event.reason}); // event.attachments 里是 onComplete 才填充的图片/文件附件 }, }, // 3) 工具失败归因errorType 稳定码优于自由文本 { id: tool-error-tracer, type: onToolCallError, handler: async (event) { console.error(tool ${event.identifier}.${event.apiName} threw:, event.error); }, }, // 4) 工具 Mock让网络工具在测试中返回假结果仅本地模式生效 { id: web-search-mock, type: beforeToolCall, handler: async (event) { if (event.identifier.endsWith(web-search)) { event.mock({ content: {results:[]} }); } }, }, ] satisfies AgentHook[]; await aiAgentService.execAgent({ agentId: my-agent, prompt: ..., hooks, });使用注意点hooks的静态类型就是AgentHook[]见 apps/server/src/services/agentRuntime/hooks/types.tssatisfies AgentHook[]可以在编译期拦截类型名写错 / handler 签名不符当只关心某一个 operation 时hooks参数即传即用无需手动清理——unregister由服务在收尾时统一执行生产队列模式下若要让远端也能收到事件需要给对应的AgentHook补上webhook配置url/delivery: fetch | qstash/fallback/eventFields且这类钩子无法执行 mock。七、结合源码与测试的调用链验证以下证据链可以帮助你在阅读仓库时快速定位事件类型契约packages/agent-runtime/src/types/hooks.ts 定义了AgentHookType联合类型、AgentHookEvent及各事件负载接口顶部注释明确说明纯数据类型的钩子生命周期事件注册/分发机制位于 server 层服务端类型与再导出apps/server/src/services/agentRuntime/hooks/types.ts re-export 上述所有事件类型并定义AgentHook、AgentHookWebhook、SerializedHookRedis 持久化用三个服务端类型中央分发器apps/server/src/services/agentRuntime/hooks/HookDispatcher.ts 是注册与分发的唯一枢纽同时包含deliverWebhookfetch/QStash 双通道与CriticalHookDeliveryError执行器接线apps/server/src/modules/AgentRuntime/RuntimeExecutors.ts 生成 Tool / Compact / HumanIntervention 指令执行器消费dispatchBeforeToolCall的 mock 结果服务入口apps/server/src/services/agentRuntime/AgentRuntimeService.ts中可直接检索到hookDispatcher.register(...)、hookDispatcher.dispatch(...)、hookDispatcher.unregister(...)等调用点覆盖步骤级钩子与人工干预的 resume/reject 流程子 Agent 链路apps/server/src/services/aiAgent/subAgentRuns.ts 负责 CallAgent 钩子分发要求parentOperationId存在于ExecSubAgentTaskParams测试佐证apps/server/src/services/agentRuntime/AgentRuntimeService.test.ts与apps/server/src/services/agentRuntime/hooks/__tests__/HookDispatcher.test.ts覆盖了注册、按类型分发、beforeToolCallmock 返回等行为可作为阅读时的行为级参考。结语Agent Runtime Hooks 是 LobeHub 把Agent 长时运行做成可治理产品的关键一环用 16 个按语义分组的钩子点覆盖了一次 operation 从步骤、工具、审批、压缩到子 Agent 的全部生命周期转折用按 operation 注册 结束时自动清理的作用域模型保证安全再用本地内存 handler 生产 Webhook双通道兼顾进程内低延迟与跨进程可靠投递。对需要监控 Agent 成本、实现工具 Mock、桥接人工审批或构建 Agent 评测体系的开发者而言本文梳理的注册方式、事件负载与设计契约可以直接作为二次开发的起点——而每一处行为都能在上述源码文件中找到落点。【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考