【免费下载链接】aiThe Laravel AI SDK provides a unified, expressive API for interacting with AI providers such as OpenAI, Anthropic, Gemini, and more.项目地址https://gitcode.com/gh_mirrors/ai89/ai点击查看免费下载Laravel AI SDK为统一调用 OpenAI、Anthropic、Gemini 等 AI 提供商提供了简洁、Laravel 风格的 API。本文带你快速掌握Laravel AI 中间件Agent Middleware与Laravel AI 事件系统Events——这正是扩展 Agent 行为最核心的两大扩展点帮助你在不改动核心代码的前提下实现日志、审计、模型切换、历史压缩、优雅终止等高级能力。无论你是刚上手 Agent还是想给现有项目加一层可观测性这份完整清单都能帮你 3 分钟找到对应的钩子位置。 先搞懂中间件和事件有何不同Laravel AI 把 Agent 的一次运行拆成多个生成步骤step。在这条流水线上有两类扩展点扩展点作用方式能否改变流程典型用途中间件 Middleware包裹每个生成步骤像洋葱一样层层嵌套✅ 能改模型、消息、工具甚至短路响应切换模型、压缩上下文、改写指令、终止运行事件 Event在关键节点派发旁观式订阅❌ 只读不影响执行日志、监控、审计、发通知、记指标一句话想「改流程」用中间件想「看流程」用事件。两者可以搭配使用。相关源码目录src/Middleware/、src/Events/。 中间件包裹每一个生成步骤每个 Agent 步骤执行时中间件都会按顺序被调用。你拿到的是一个PendingStep对象和Closure $next既可以「先做点什么再放行」也可以「直接短路、不调用模型」。你可以通过withMiddleware([...])动态注入或在 Agent 上实现 HasMiddleware 接口的middleware()方法全局生效。中间件能看到当前模型、累计 token 用量、是否最终步骤并通过$step-withModel() / withMessages() / withInstructions() / onlyTools() / withoutTools()等改写本次请求。想快速生成骨架可运行命令make:agent-middleware模板见 stubs/agent-middleware.stub命令实现在 MakeAgentMiddlewareCommand。一个最小可用形态闭包写法-withMiddleware([function (PendingStep $step, Closure $next) { // 在步骤发出前按需压缩上下文 return $next($step); }]) 完整行为示例含短路、换模型、换工具、流式处理见 AgentMiddlewareTest可直接对照学习。 内置 Stop 中间件优雅终止 Agent 运行当你希望「满足某个条件就停止后续模型调用」时无需自己写循环SDK 内置了 Stop 中间件Stop::when(fn (PendingStep $step) ...)条件成立时停止运行。Stop::unless(...)条件不成立时停止运行。Stop::when(true)直接跳过所有步骤返回空响应。这让「最多跑 N 步」「用户取消即停」这类控制逻辑变得非常直观也便于在长工具循环里省 token。 事件系统监听 Agent 的完整生命周期Agent 从收到提示到产出结果沿途会在固定节点派发事件。所有事件都位于 src/Events/字段自解释拿来即用。一、Agent 运行级事件事件触发时机PromptingAgent非流式提示发起前AgentPrompted非流式提示完成StreamingAgent流式提示发起前AgentStreamed流式提示完成AgentFailed运行抛出异常AgentFailedOver提供商故障转移failover二、步骤级事件由 RunContext 派发事件触发时机StartingStep每个生成步骤开始前StepCompleted步骤成功结束StepFailed步骤失败这些定义可参见 RunContext。三、工具调用事件事件触发时机InvokingTool工具开始执行前ToolInvoked工具执行完成ToolFailed工具执行失败四、工具审批事件事件触发时机ToolApprovalRequested请求工具人工审批ToolApprovalResolved审批被处理五、文件 / 存储事件StoringFile、FileStored、CreatingStore、StoreCreated、AddingFileToStore、FileAddedToStore、RemovingFileFromStore、FileRemovedFromStore、FileDeleted、StoreDeleted六、多模态生成事件图像GeneratingImage/ImageGenerated音频GeneratingAudio/AudioGenerated转写GeneratingTranscription/TranscriptionGenerated向量GeneratingEmbeddings/EmbeddingsGenerated分类Classifying/Classified重排Reranking/Reranked故障转移ProviderFailedOver 每个事件类都带public属性如 ToolInvoked 会暴露tool、arguments、result、time毫秒方便直接落库或打点。⚡ 三步接入实战第 1 步给 Agent 挂中间件。在调用处用-withMiddleware([...])或在 Agent 类中实现middleware()方法全局生效。第 2 步订阅你关心的事件。在 Laravel 的 Event 监听里捕获StartingStep、StepCompleted、ToolInvoked等把关键信息写入日志或监控系统。第 3 步用 Stop 控制边界。需要限制步数或提前停止时加入Stop::when(...)避免不必要的模型调用。这套组合拳中间件改流程 事件做观测 Stop 控边界就是 Laravel AI 扩展 Agent 的标准姿势。❓ 常见问题FAQ中间件和事件可以一起用吗可以且推荐。中间件负责改写请求/响应事件负责旁路观测互不干扰。中间件短路不调用模型会影响后续吗会。一旦某层中间件直接返回StepResponse外层中间件的then回调仍会收到该响应运行会按短路结果继续或结束。流式场景下中间件回调何时执行在流被消费完drained后才触发确保你拿到的是完整步骤数据。 小结中间件包裹每个生成步骤可改模型、上下文、工具也能短路入口 src/Middleware/。事件覆盖提示、步骤、工具、审批、存储与多模态全流程旁路观测最佳入口 src/Events/。Stop内置优雅终止器省 token、控边界src/Middleware/Stop.php。掌握这两大扩展点你就拥有了在不触碰核心代码的前提下自由定制 Laravel AI Agent 的全部能力。赞分享【免费下载链接】aiThe Laravel AI SDK provides a unified, expressive API for interacting with AI providers such as OpenAI, Anthropic, Gemini, and more.项目地址https://gitcode.com/gh_mirrors/ai89/ai点击查看免费下载相关推荐Vortex 扩展事件系统详解EVENTS.md 全量事件清单与 emitAndAwait 源码实现Vortex 扩展事件系统详解EVENTS.md 全量事件清单与 emitAndAwait 源码实现 本篇基于 Vortex API 官方事件参考 https桌面应用Olib 插件系统完整指南声明式清单驱动的架构原理与 AI Agent 插件开发实战Olib 插件系统完整指南声明式清单驱动的架构原理与 AI Agent 插件开发实战 本文基于 OlibOlibTauri 仓库的 dev_docs/pl桌面应用Jspreadsheet 事件系统完全指南事件清单、分发机制与图表联动实战Jspreadsheet 事件系统完全指南事件清单、分发机制与图表联动实战 Jspreadsheet 是一套轻量级的 JavaScript 数据表格组件其事前端UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/15 18:59:17 · 阅读 1.2k Laravel AI 中间件与事件系统：Agent 扩展点的完整清单与实战指南
【免费下载链接】aiThe Laravel AI SDK provides a unified, expressive API for interacting with AI providers such as OpenAI, Anthropic, Gemini, and more.项目地址https://gitcode.com/gh_mirrors/ai89/ai点击查看免费下载Laravel AI SDK为统一调用 OpenAI、Anthropic、Gemini 等 AI 提供商提供了简洁、Laravel 风格的 API。本文带你快速掌握Laravel AI 中间件Agent Middleware与Laravel AI 事件系统Events——这正是扩展 Agent 行为最核心的两大扩展点帮助你在不改动核心代码的前提下实现日志、审计、模型切换、历史压缩、优雅终止等高级能力。无论你是刚上手 Agent还是想给现有项目加一层可观测性这份完整清单都能帮你 3 分钟找到对应的钩子位置。 先搞懂中间件和事件有何不同Laravel AI 把 Agent 的一次运行拆成多个生成步骤step。在这条流水线上有两类扩展点扩展点作用方式能否改变流程典型用途中间件 Middleware包裹每个生成步骤像洋葱一样层层嵌套✅ 能改模型、消息、工具甚至短路响应切换模型、压缩上下文、改写指令、终止运行事件 Event在关键节点派发旁观式订阅❌ 只读不影响执行日志、监控、审计、发通知、记指标一句话想「改流程」用中间件想「看流程」用事件。两者可以搭配使用。相关源码目录src/Middleware/、src/Events/。 中间件包裹每一个生成步骤每个 Agent 步骤执行时中间件都会按顺序被调用。你拿到的是一个PendingStep对象和Closure $next既可以「先做点什么再放行」也可以「直接短路、不调用模型」。你可以通过withMiddleware([...])动态注入或在 Agent 上实现 HasMiddleware 接口的middleware()方法全局生效。中间件能看到当前模型、累计 token 用量、是否最终步骤并通过$step-withModel() / withMessages() / withInstructions() / onlyTools() / withoutTools()等改写本次请求。想快速生成骨架可运行命令make:agent-middleware模板见 stubs/agent-middleware.stub命令实现在 MakeAgentMiddlewareCommand。一个最小可用形态闭包写法-withMiddleware([function (PendingStep $step, Closure $next) { // 在步骤发出前按需压缩上下文 return $next($step); }]) 完整行为示例含短路、换模型、换工具、流式处理见 AgentMiddlewareTest可直接对照学习。 内置 Stop 中间件优雅终止 Agent 运行当你希望「满足某个条件就停止后续模型调用」时无需自己写循环SDK 内置了 Stop 中间件Stop::when(fn (PendingStep $step) ...)条件成立时停止运行。Stop::unless(...)条件不成立时停止运行。Stop::when(true)直接跳过所有步骤返回空响应。这让「最多跑 N 步」「用户取消即停」这类控制逻辑变得非常直观也便于在长工具循环里省 token。 事件系统监听 Agent 的完整生命周期Agent 从收到提示到产出结果沿途会在固定节点派发事件。所有事件都位于 src/Events/字段自解释拿来即用。一、Agent 运行级事件事件触发时机PromptingAgent非流式提示发起前AgentPrompted非流式提示完成StreamingAgent流式提示发起前AgentStreamed流式提示完成AgentFailed运行抛出异常AgentFailedOver提供商故障转移failover二、步骤级事件由 RunContext 派发事件触发时机StartingStep每个生成步骤开始前StepCompleted步骤成功结束StepFailed步骤失败这些定义可参见 RunContext。三、工具调用事件事件触发时机InvokingTool工具开始执行前ToolInvoked工具执行完成ToolFailed工具执行失败四、工具审批事件事件触发时机ToolApprovalRequested请求工具人工审批ToolApprovalResolved审批被处理五、文件 / 存储事件StoringFile、FileStored、CreatingStore、StoreCreated、AddingFileToStore、FileAddedToStore、RemovingFileFromStore、FileRemovedFromStore、FileDeleted、StoreDeleted六、多模态生成事件图像GeneratingImage/ImageGenerated音频GeneratingAudio/AudioGenerated转写GeneratingTranscription/TranscriptionGenerated向量GeneratingEmbeddings/EmbeddingsGenerated分类Classifying/Classified重排Reranking/Reranked故障转移ProviderFailedOver 每个事件类都带public属性如 ToolInvoked 会暴露tool、arguments、result、time毫秒方便直接落库或打点。⚡ 三步接入实战第 1 步给 Agent 挂中间件。在调用处用-withMiddleware([...])或在 Agent 类中实现middleware()方法全局生效。第 2 步订阅你关心的事件。在 Laravel 的 Event 监听里捕获StartingStep、StepCompleted、ToolInvoked等把关键信息写入日志或监控系统。第 3 步用 Stop 控制边界。需要限制步数或提前停止时加入Stop::when(...)避免不必要的模型调用。这套组合拳中间件改流程 事件做观测 Stop 控边界就是 Laravel AI 扩展 Agent 的标准姿势。❓ 常见问题FAQ中间件和事件可以一起用吗可以且推荐。中间件负责改写请求/响应事件负责旁路观测互不干扰。中间件短路不调用模型会影响后续吗会。一旦某层中间件直接返回StepResponse外层中间件的then回调仍会收到该响应运行会按短路结果继续或结束。流式场景下中间件回调何时执行在流被消费完drained后才触发确保你拿到的是完整步骤数据。 小结中间件包裹每个生成步骤可改模型、上下文、工具也能短路入口 src/Middleware/。事件覆盖提示、步骤、工具、审批、存储与多模态全流程旁路观测最佳入口 src/Events/。Stop内置优雅终止器省 token、控边界src/Middleware/Stop.php。掌握这两大扩展点你就拥有了在不触碰核心代码的前提下自由定制 Laravel AI Agent 的全部能力。赞分享【免费下载链接】aiThe Laravel AI SDK provides a unified, expressive API for interacting with AI providers such as OpenAI, Anthropic, Gemini, and more.项目地址https://gitcode.com/gh_mirrors/ai89/ai点击查看免费下载相关推荐Vortex 扩展事件系统详解EVENTS.md 全量事件清单与 emitAndAwait 源码实现Vortex 扩展事件系统详解EVENTS.md 全量事件清单与 emitAndAwait 源码实现 本篇基于 Vortex API 官方事件参考 https桌面应用Olib 插件系统完整指南声明式清单驱动的架构原理与 AI Agent 插件开发实战Olib 插件系统完整指南声明式清单驱动的架构原理与 AI Agent 插件开发实战 本文基于 OlibOlibTauri 仓库的 dev_docs/pl桌面应用Jspreadsheet 事件系统完全指南事件清单、分发机制与图表联动实战Jspreadsheet 事件系统完全指南事件清单、分发机制与图表联动实战 Jspreadsheet 是一套轻量级的 JavaScript 数据表格组件其事前端UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考