Laravel AI SDK 0.11: Agent Run Observability | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://msaied.com) [ Projects ](https://msaied.com/projects) [ Articles ](https://msaied.com/articles) [ Certificates ](https://msaied.com/certificates) [ Contact ](https://msaied.com#contact-section) [ home ](https://msaied.com) [ articles ](https://msaied.com/articles) Agent Run Observability in Laravel AI SDK 0.11 On this page 1. [ What Changed in Laravel AI SDK 0.11 ](#what-changed-in-laravel-ai-sdk-011) 2. [ Per-Run Invocation IDs ](#per-run-invocation-ids) 3. [ Lifecycle Events ](#lifecycle-events) 4. [ Hosted Tool Search ](#hosted-tool-search) 5. [ Broader Failover Coverage ](#broader-failover-coverage) 6. [ Provider Additions ](#provider-additions) 7. [ Testing ](#testing) 8. [ Upgrade Notes ](#upgrade-notes) ![Agent Run Observability in Laravel AI SDK 0.11](https://cdn.msaied.com/576/2c65c83715560433872bec3ae0eb2bf6.png) [ Laravel ](https://msaied.com/articles?category=laravel) [ AI ](https://msaied.com/articles?category=ai) #Laravel AI #AI SDK #Observability #PHP #Agent Agent Run Observability in Laravel AI SDK 0.11 ================================================ 20 Aug 2026 4 min read ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said Table of contents 1. [ 01 What Changed in Laravel AI SDK 0.11 ](#what-changed-in-laravel-ai-sdk-011) 2. [ 02 Per-Run Invocation IDs ](#per-run-invocation-ids) 3. [ 03 Lifecycle Events ](#lifecycle-events) 4. [ 04 Hosted Tool Search ](#hosted-tool-search) 5. [ 05 Broader Failover Coverage ](#broader-failover-coverage) 6. [ 06 Provider Additions ](#provider-additions) 7. [ 07 Testing ](#testing) 8. [ 08 Upgrade Notes ](#upgrade-notes) What Changed in Laravel AI SDK 0.11 ----------------------------------- Released on August 19, 2026, Laravel AI v0.11.0 ships 36 merged pull requests from twelve first-time contributors. The headline feature is end-to-end observability for agent runs: every run now carries a single correlation ID, and a set of lifecycle events fires around every provider round-trip and every tool call. ### Per-Run Invocation IDs Before this release, `prompt()` never minted a run-level invocation ID, so synchronous middleware always saw `$prompt->invocationId === null`. Streaming middleware saw a real value, and a three-provider failover produced three unrelated IDs for the same logical run. `prompt()` now mints the ID up front, and every provider reuses whatever the caller supplied. Nested tool calls had a related bug: an agent invoked as a tool overwrote the shared mutable ID before the outer `ToolInvoked` event fired, so the outer event carried the inner call's ID. The ID is now minted inside `executeTool()`, and tools can read it with `Request::toolInvocationId()`. ### Lifecycle Events Five events now fire across both the synchronous and streaming paths: - **`StartingStep`** — carries the messages, resolved options, and the run's full message history sent to the provider. - **`StepCompleted`** — carries the complete step response. - **`StepFailed`** — fires when a step fails; both end events include wall time in milliseconds, matching `QueryExecuted::$time`. - **`ToolFailed`** — reports which tool threw and carries the same tool invocation ID as the `InvokingTool` that opened it; the exception is still rethrown. - **`AgentFailed`** — fires exactly once per run, after failover has exhausted the provider chain. A tool call also publishes its run and tool invocation IDs for its own duration, so any agent prompted while it runs picks them up as `parentInvocationId` and `parentToolInvocationId`. This links sub-agents back to the run that delegated to them without requiring `AgentTool`. ### Hosted Tool Search Every tool was previously sent to the provider on every request. The new `ToolSearch` wrapper defers tools so OpenAI and Anthropic load them on demand through their own hosted search: ```php public function tools(): iterable { return [ new WeatherTool, new ToolSearch(tools: [new SearchInvoices, new RefundOrder]), ]; } ``` Anthropic's search strategy is a constructor argument validated against `regex` and `bm25`: ```php new ToolSearch(tools: [new SearchInvoices], strategy: 'bm25') ``` Providers that do not support hosted search throw a clear exception before the request is sent. Only one wrapper may be registered per request, and OpenAI hosted search requires stored responses, so pairing `ToolSearch` with `store=false` throws. ### Broader Failover Coverage Three production failure modes now trigger failover where they previously did not: 1. **Connection failures** — `ConnectionException` (unreachable host, refused connection, local Ollama not running) is rethrown as `ProviderConnectionException` implementing `FailoverableException`. 2. **Gateway error codes** — the overloaded-provider status list grew from `503` alone to `502`, `503`, `504`, `520`, `522`, and `524`. A bare `500` is deliberately excluded. 3. **Anthropic spend caps** — Anthropic returns HTTP 400 with a `usage limit` message when an organisation hits its spend cap. Adding that pattern to the failover handler prevents ~990 unhandled exceptions per month in affected setups. ### Provider Additions - xAI: web search and file search - Groq and OpenAI-compatible providers: transcription - OpenRouter: web fetch server tool - Anthropic: web fetch citations now appear on `$response->meta->citations` - Gemini: default text model moved to `gemini-3.7-flash` ### Testing `assertPromptedTimes()` works like `Bus::assertDispatchedTimes()`: ```php SalesCoach::assertPromptedTimes(3); ``` Faked queued generation of transcriptions, images, audio, and embeddings now runs the `then(...)` callback, so tests can assert on callback behaviour instead of stopping at the dispatch. ### Upgrade Notes - Stream errors now throw `StreamErrorException` instead of silently ending the step. - `AgentFailedOver` requires a new `string $invocationId` argument; `ToolInvoked` requires a new `float $time` argument. Only code constructing these events by hand needs updating. - `AgentFailedOver` no longer fires for the final provider in a chain; `AgentFailed` handles that case. - Applications relying on Gemini's default text model will move to `gemini-3.7-flash`; set the model explicitly to keep the old one. **Key takeaways:** - Every agent run now has a single correlation ID across failover attempts. - Five lifecycle events with wall timings make multi-step runs fully traceable. - `ToolSearch` reduces token usage by deferring tool loading to the provider. - Failover now handles connection errors, gateway timeouts, and Anthropic spend caps. - `assertPromptedTimes()` simplifies agent test assertions. Upgrade with `composer update laravel/ai`. Full details at the [Laravel News source article](https://laravel-news.com/laravel-ai-sdk-0-11). Found this useful? [ ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fmsaied.com%2Farticles%2Fagent-run-observability-in-laravel-ai-sdk-011&text=Agent+Run+Observability+in+Laravel+AI+SDK+0.11) [ ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fmsaied.com%2Farticles%2Fagent-run-observability-in-laravel-ai-sdk-011) Frequently Asked Questions ---------------------------- 3 questions Q01 What is the invocation ID in Laravel AI SDK 0.11 and why does it matter? Every agent run now receives a single invocation ID minted at the start of `prompt()` or `streamPrompt()`. That ID is threaded through all provider round-trips and failover attempts, so middleware, listeners, and logs can correlate every event in a multi-step run back to one originating call. Q02 How does ToolSearch reduce token usage in Laravel AI? Wrapping tools in `new ToolSearch(tools: [...])` defers them so OpenAI and Anthropic load them on demand through their own hosted search, rather than sending the full tool catalogue to the provider on every request. The tools themselves need no changes. Q03 What breaking changes does Laravel AI SDK 0.11 introduce? Stream errors now throw `StreamErrorException` instead of silently ending the step. `AgentFailedOver` requires a new `string $invocationId` argument, and `ToolInvoked` requires a new `float $time` argument — only code constructing these events by hand needs updating. Gemini's default text model also moves to `gemini-3.7-flash`. Continue reading More Articles --------------- [ View all ](https://msaied.com/articles) [ ![Practical RAG in Laravel: pgvector, Embeddings, and Retrieval Pipelines](https://cdn.msaied.com/575/21de38adc44ef949b9bdc13ad6f6166b.png) laravel ai pgvector ### Practical RAG in Laravel: pgvector, Embeddings, and Retrieval Pipelines Build a production-ready Retrieval-Augmented Generation pipeline in Laravel using pgvector, OpenAI embeddings,... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 21 Aug 2026 3 min read Read ](https://msaied.com/articles/practical-rag-in-laravel-pgvector-embeddings-and-retrieval-pipelines-3) [ ![Statamic Mailables Viewer: Preview Laravel Emails in the Control Panel](https://cdn.msaied.com/574/5ecb785e581163f6a143b14cec070996.png) Statamic Laravel Email ### Statamic Mailables Viewer: Preview Laravel Emails in the Control Panel Mailables Viewer is a free Statamic add-on by Jack McDade that auto-discovers Laravel mailables and renders li... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 20 Aug 2026 3 min read Read ](https://msaied.com/articles/statamic-mailables-viewer-preview-laravel-emails-in-the-control-panel) [ ![Advanced Authorization in Laravel: Gates, Policies, and Response-Based Access Control](https://cdn.msaied.com/571/e2c97418f4d543aac16e77c5dfd1055a.png) laravel authorization security ### Advanced Authorization in Laravel: Gates, Policies, and Response-Based Access Control Go beyond simple boolean gates. Learn how Laravel's response-based authorization lets you return rich denial r... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 20 Aug 2026 3 min read Read ](https://msaied.com/articles/advanced-authorization-in-laravel-gates-policies-and-response-based-access-control-4) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://msaied.com)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. Explore - [Home](https://msaied.com) - [Projects](https://msaied.com/projects) - [Articles](https://msaied.com/articles) - [Certificates](https://msaied.com/certificates) - [Contact](https://msaied.com#contact-section) Connect - [ hello@msaied.com ](mailto:hello@msaied.com) - [ +20 109 461 9204 ](tel:+201094619204) © 2026 Mohamed Said. All rights reserved. [ ](https://github.com/EG-Mohamed) [ ](https://www.linkedin.com/in/msaiedm/) [ ](https://wa.me/201094619204) [ ](mailto:hello@msaied.com) [ ](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)