Flue生命周期钩子实战useAgentStart与useAgentFinish拦截与清理【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flueFlue 是一个开源的沙箱智能体框架The Sandbox Agent Framework它的核心思想是智能体即函数。而真正让智能体可靠运转的是 Flue 提供的生命周期钩子useAgentStart在消息送达、模型开工前执行入场拦截useAgentFinish在模型准备收尾时执行离场检查。掌握这两个钩子你就能在 Agent 的关键节点上加载数据、写持久化状态、补发任务甚至阻止它草率收尾。为什么需要生命周期钩子在 Flue 中Agent 就是一个普通函数每次模型调用之前函数会重新渲染render一次并重新执行其中的钩子。除了useModel、useTool、useSkill等资源钩子外Flue 还提供了四个事件钩子分别对应一次响应生命周期的固定时机钩子触发时机特点useResponseStart响应真正开始时每响应一次同步观察器可写入 metadatauseAgentStart每条送达的消息被处理前支持异步是入场拦截点useAgentFinish模型想停下的每个潜在停止点可追加信号把模型叫回来useResponseFinish响应真正结束时每响应一次同步观察器读取最终 usage前两个负责观察后两个是真正的控制点——它们不会被动等待而是被 await回调没跑完响应就不会进入下一步。useAgentStart在模型开工前做数据准备useAgentStart的官方定位是intake seam入场缝隙输入消息已持久化之后、模型第一轮推理之前执行。它是唯一异步且天然适合加载数据的事件钩子回调上下文包含四个成员harness运行时能力面可访问沙箱文件系统和 shell惰性初始化log向会话流输出进度日志模型看不到signal本次提交的 AbortSignalappend低层信号写入器一般更推荐用useDispatchMessage()派发典型用法在回调里查一次 CRM 把客户信息写进持久化状态让模型醒来就知道该帮谁useAgentStart(async () { if (customer) return; // 持久化守卫整个会话只加载一次 setCustomer(await crm.lookupCustomer(id)); });源码实现非常轻量——它只是把回调登记到当前渲染帧上钩子实现use-agent-start.ts上下文类型定义message-output.ts几个必须记住的语义每条消息跑一次——多条消息合并进同一个响应时每条都会各触发一次同一消息的多个回调并发执行、顺序不保证模型会等最慢的那个需要严格顺序的工作请合并进一个回调回调里不能调用其他use钩子渲染帧之外的调用会直接抛错。useAgentFinish拦截想收工的模型如果说useAgentStart负责开工前的准备useAgentFinish就是执法缝隙enforcement seam当模型没有更多工具调用、响应即将落定时触发。你可以检查这次响应到底做了什么如果活没干完就append一条信号把模型送回同一响应里继续干活useAgentFinish(({ response, append }) { const posted response.toolCalls.some( (call) call.tool post_message !call.isError, ); if (posted) return; // 什么都没 append响应正常收尾 append({ kind: signal, type: reminder, body: 你还没调用 post_message用户什么也收不到。现在立刻调用。, }); });ctx.response.toolCalls会跨所有轮次、跨失败重试聚合本响应出现过的每一次工具调用ctx.response.usage则是当前的累计用量非常适合做预算感知的续跑决策。仓库里的 Discord 频道示例就用了这个套路——在模型结束前检查消息是否真的发出去了assistant.ts防失控也内置好了每次append都计入框架固定的32 次续跑上限无脑 append 的钩子会响亮地失败而不是无限循环续跑的每一轮都会形成一个响应控制检查点并原子落盘进程重启后不会重复执行已完成的检查周期回调抛错 整个提交失败失败是显式的。清理与幂等钩子实战的三条避坑法则Flue 对事件钩子采用的是at-least-once至少一次语义持久化的产出信号追加、状态写入按缝隙原子提交崩溃重试时不会重复但网络请求、写文件这类外部副作用在极端重试下可能偶发执行两次。因此✅一次性工作要用持久化状态守卫if (loaded) return;是最经典的恰好一次写法见 agent-hooks 指南✅append只在回调执行窗口内有效把引用存起来、回调结束后再调用会直接抛错✅子智能体subagent中不可用useAgentStart/useAgentFinish只在根智能体渲染时可用委派任务的收尾校验应放在父智能体侧实现处可见 use-agent-finish.ts 中的显式报错。延伸阅读与核心文件事件钩子完整契约append/dispatch 区别、32 次续跑上限、检查点机制agent-hooks-api.mdAgent 钩子入门指南含usePersistentState与自定义钩子agent-hooks.md钩子源码目录packages/runtime/src/hooks/完整框架介绍README.mduseAgentStart管入场useAgentFinish管离场两者配合持久化状态就能把 Agent 生命周期的关键动作变成可审计、可恢复、防失控的确定行为。【免费下载链接】flueThe sandbox agent framework.项目地址: https://gitcode.com/GitHub_Trending/flue1/flue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考