Laravel AI v0.11: Agent Run Lifecycle Events | Mohamed Said [Skip to content](#main) [ ![](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed SaidLaravel Backend Engineer ](https://www.msaied.com/public) - [Home](https://www.msaied.com/public) - [Projects](https://www.msaied.com/public/projects) - [Articles](https://www.msaied.com/public/articles) - [Certificates](https://www.msaied.com/public/certificates) - [About](https://www.msaied.com/public#about) [ Contact](https://www.msaied.com/public#contact) Menu Menu ---- Close - [HomeStart here](https://www.msaied.com/public) - [ProjectsCase studies](https://www.msaied.com/public/projects) - [ArticlesEngineering notes](https://www.msaied.com/public/articles) - [CertificatesCredentials](https://www.msaied.com/public/certificates) - [AboutHow I work](https://www.msaied.com/public#about) - [ContactGet in touch](https://www.msaied.com/public#contact) [Start a conversation](https://www.msaied.com/public#contact) [WhatsApp](https://wa.me/201094619204) [Email](mailto:hello@msaied.com) 1. [Home](https://www.msaied.com/public) 2. / 3. [Articles](https://www.msaied.com/public/articles) 4. / 5. [Laravel](https://www.msaied.com/public/articles?category=laravel) 6. / 7. Laravel AI v0.11: Trace Agent Runs With Lifecycle Events [Laravel](https://www.msaied.com/public/articles?category=laravel) [AI](https://www.msaied.com/public/articles?category=ai) Laravel AI v0.11: Trace Agent Runs With Lifecycle Events ========================================================= Laravel AI v0.11.0 adds per-step lifecycle events to the agent generation loop, giving every run a single invocation ID and reporting start, completion, and failure events for each provider round-trip and tool call. ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://www.msaied.com/public#person) Published 21 Aug 2026 · Updated 25 Aug 2026 · 4 min read ShareCopy linkCopied ![Laravel AI v0.11: Trace Agent Runs With Lifecycle Events](https://cdn.msaied.com/590/748f53f5b6a1080f23bc5bc038aa37be.png) On this page +1. [What Changed in Laravel AI v0.11.0](#what-changed-in-laravel-ai-v0110) 2. [One Invocation ID for the Whole Run](#one-invocation-id-for-the-whole-run) 3. [Step Events](#step-events) 4. [Tool Events](#tool-events) 5. [Run Failure and Sub-Agent Linking](#run-failure-and-sub-agent-linking) 6. [Key Takeaways](#key-takeaways) What Changed in Laravel AI v0.11.0 ---------------------------------- Before v0.11.0, the Laravel AI SDK reported only two events for an entire agent run: `PromptingAgent` at the start and `AgentPrompted` at the end. A run that made five provider round-trips looked identical to one that made a single call, and a run that threw an exception midway reported nothing at all because `AgentPrompted` was never dispatched. Seven pull requests from [@pushpak1300](https://github.com/pushpak1300), merged as [\#870–#876](https://github.com/laravel/ai/pull/870), change that completely. Every run now carries one stable ID, and every round-trip and tool call fires start and end events with wall timings. One Invocation ID for the Whole Run ----------------------------------- `streamPrompt()` already generated a run-level invocation ID, but `prompt()` did not. Synchronous middleware saw `$prompt->invocationId === null` while streaming middleware saw a real value. Worse, failover across three providers produced three unrelated IDs for what was logically one run. `prompt()` now generates the ID up front, and the provider reuses whatever the caller supplied. Every event carries it as its first constructor argument: ```php public function __construct( public string $invocationId, public int $stepNumber, // ... ) {} ``` `AgentFailedOver` also gained the ID as a required first argument. Any code constructing that event manually needs updating. Step Events ----------- `StartingStep`, `StepCompleted`, and `StepFailed` fire around every provider round-trip on both the synchronous and streaming paths. `StartingStep` carries the full message history sent for that step, the resolved options, `stepNumber`, and `isFinalStep`. `StepCompleted` carries the whole `StepResponse` plus a `float $time` in milliseconds — the same unit as `QueryExecuted::$time`: ```php use Laravel\Ai\Events\StepCompleted; Event::listen(StepCompleted::class, function (StepCompleted $event) { Log::info('AI step completed', [ 'invocation' => $event->invocationId, 'step' => $event->stepNumber, 'ms' => $event->time, 'prompt_tokens' => $event->response->usage->promptTokens, 'finish' => $event->response->finishReason->value, ]); }); ``` Per-step usage was available before through `$response->steps`, but only as a bulk payload on the terminal event with no timing attached. Now cost and duration are reported as the run progresses. `StepFailed` covers steps that end without a response, carrying the `Throwable` and the time spent before it threw. Tool Events ----------- `InvokingTool` and `ToolInvoked` already existed, but a shared mutable property on the provider caused the outer `ToolInvoked` to report the inner call's ID when an agent was invoked as a tool. A `RunContext` now owns the run identity and dispatches events directly, and each invocation receives its own ID inside `executeTool()`. The new `ToolFailed` event closes the gap for tool exceptions: ```php use Laravel\Ai\Events\ToolFailed; Event::listen(ToolFailed::class, function (ToolFailed $event) { Log::error('AI tool failed', [ 'invocation' => $event->invocationId, 'tool_invocation' => $event->toolInvocationId, 'tool' => class_basename($event->tool), 'ms' => $event->time, 'exception' => $event->exception->getMessage(), ]); }); ``` The exception is still rethrown, so existing behavior is unchanged. `ToolInvoked` also gained a required `float $time`; update any manual constructor calls. Run Failure and Sub-Agent Linking --------------------------------- `AgentFailed` fires once per run after the entire chain is exhausted, carrying the invocation ID, the prompt, and the exception. `AgentFailedOver` no longer fires for the final provider in a chain — that attempt is now reported as the run's failure instead. Sub-agents invoked as tools now receive `parentInvocationId` and `parentToolInvocationId` on their prompt, correlating nested runs to their parent. The link does not cross a queue boundary; a prompt dispatched with `promptOnQueue()` starts its own unparented run. Key Takeaways ------------- - Every agent run now has a single `invocationId` shared across `prompt()` and `streamPrompt()`. - `StartingStep`, `StepCompleted`, and `StepFailed` give per-round-trip visibility with millisecond timings. - `ToolFailed` closes the silent-exception gap in tool execution. - `AgentFailed` fires once per failed run; `AgentFailedOver` no longer fires on the final provider. - Sub-agent runs are linked to their parent via `parentInvocationId` and `parentToolInvocationId`. - If you only need timings and token counts, prefer `StepCompleted` over `StartingStep` to avoid serializing the full message history in queued listeners. --- Source: [Laravel News — Laravel AI: Trace Agent Runs With Lifecycle Events](https://laravel-news.com/laravel-ai-agent-run-events) - [Laravel AI](https://www.msaied.com/public/articles?search=Laravel%20AI) - [AI Agents](https://www.msaied.com/public/articles?search=AI%20Agents) - [Laravel Events](https://www.msaied.com/public/articles?search=Laravel%20Events) - [Observability](https://www.msaied.com/public/articles?search=Observability) - [v0.11.0](https://www.msaied.com/public/articles?search=v0.11.0) Frequently asked questions --------------------------- What is the difference between StartingStep and StepCompleted, and which should I listen to in a queued listener?StartingStep carries the run's entire message history up to that point, so a queued listener will serialize all messages and attachments. StepCompleted carries only the step's own response plus wall-time and token usage. If you only need timings and token counts, listen for StepCompleted to keep queued payloads small. Does AgentFailed fire for every provider failure when failover is configured?No. With failover configured, a provider that throws a FailoverableException is not terminal, so AgentFailed only fires after the entire provider chain is exhausted. AgentFailedOver also no longer fires for the last provider in the chain; that attempt is reported as the run's failure instead. How are sub-agent runs linked to their parent run in Laravel AI v0.11?When an agent is invoked as a tool, the tool call tracks the current run and tool invocation IDs. Any agent prompted during that tool execution receives parentInvocationId and parentToolInvocationId on its prompt. This works for hand-written tools as well as AgentTool, but the link does not cross a queue boundary. ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp)About the author ---------------- [Mohamed Said](https://www.msaied.com/public#person)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. [About](https://www.msaied.com/public#about) [GitHub ↗](https://github.com/EG-Mohamed) [LinkedIn ↗](https://www.linkedin.com/in/msaiedm/) [WhatsApp ↗](https://wa.me/201094619204) [Email Address ↗](mailto:hello@msaied.com) [My CV ↗](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) [Previous articleLaravel AI SDK: Access Raw HTTP Responses and Rate Limit Headers](https://www.msaied.com/public/articles/laravel-ai-sdk-access-raw-http-responses-and-rate-limit-headers) [Next articleFilament v4 Render Hooks: Injecting UI Into Any Panel Without Hacking Core](https://www.msaied.com/public/articles/filament-v4-render-hooks-injecting-ui-into-any-panel-without-hacking-core) On this page ------------- 1. [What Changed in Laravel AI v0.11.0](#what-changed-in-laravel-ai-v0110) 2. [One Invocation ID for the Whole Run](#one-invocation-id-for-the-whole-run) 3. [Step Events](#step-events) 4. [Tool Events](#tool-events) 5. [Run Failure and Sub-Agent Linking](#run-failure-and-sub-agent-linking) 6. [Key Takeaways](#key-takeaways) ### Have a technical challenge? Tell me what you’re building. I reply within two working days. [Start a conversation](https://www.msaied.com/public#contact) Related articles ----------------- [ ![](https://cdn.msaied.com/740/cce86edc21eddcbdd2f2454fadaf9c70.png) · 3 min read### The Pipeline Pattern in Laravel: Custom Pipelines Beyond Middleware 5 Oct 2026 ](https://www.msaied.com/public/articles/the-pipeline-pattern-in-laravel-custom-pipelines-beyond-middleware-1) [ ![](https://cdn.msaied.com/739/2d6897fdcdcf090613f96f72a64b8a78.png) · 4 min read### MySQL Full-Text Search in Laravel: Indexes, Relevance Scoring, and Boolean Mode 4 Oct 2026 ](https://www.msaied.com/public/articles/mysql-full-text-search-in-laravel-indexes-relevance-scoring-and-boolean-mode) [ ![](https://cdn.msaied.com/738/073696a3fefe18bec825beec5ac658f5.png) · 4 min read### Laravel Queue Rate-Limited Middleware: Throttling Jobs Without Losing Work 4 Oct 2026 ](https://www.msaied.com/public/articles/laravel-queue-rate-limited-middleware-throttling-jobs-without-losing-work) Have a technical challenge? ---------------------------- Tell me what you’re building. I reply within two working days. [Discuss your project ↗](https://www.msaied.com/public#contact) © 2026 Mohamed Said · Built with Laravel, meant to last.Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. - [Home](https://www.msaied.com/public) - [Articles](https://www.msaied.com/public/articles) - [Certificates](https://www.msaied.com/public/certificates) - [GitHub](https://github.com/EG-Mohamed) - [LinkedIn](https://www.linkedin.com/in/msaiedm/) - [WhatsApp](https://wa.me/201094619204) - [Email Address](mailto:hello@msaied.com) - [My CV](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) - [Sitemap](https://www.msaied.com/public/sitemap.xml)