Laravel AI SDK 1.4: Agent Tool Failure Recovery | Mohamed Said       [Skip to content](#main)  [ ![](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed SaidLaravel Backend Engineer ](https://www.msaied.com) - [Home](https://www.msaied.com)
- [Projects](https://www.msaied.com/projects)
- [Articles](https://www.msaied.com/articles)
- [Certificates](https://www.msaied.com/certificates)
- [About](https://www.msaied.com#about)

           [  Contact](https://www.msaied.com#contact) Menu 

Menu
----

Close 

 - [HomeStart here](https://www.msaied.com)
- [ProjectsCase studies](https://www.msaied.com/projects)
- [ArticlesEngineering notes](https://www.msaied.com/articles)
- [CertificatesCredentials](https://www.msaied.com/certificates)
- [AboutHow I work](https://www.msaied.com#about)
- [ContactGet in touch](https://www.msaied.com#contact)

  [Start a conversation](https://www.msaied.com#contact) [WhatsApp](https://wa.me/201094619204) [Email](mailto:hello@msaied.com) 

 1. [Home](https://www.msaied.com)
2. /
3. [Articles](https://www.msaied.com/articles)
4. /
5. [Laravel](https://www.msaied.com/articles?category=laravel)
6. /
7. Laravel AI SDK 1.4: Agents Now Recover From Tool Failures

   [Laravel](https://www.msaied.com/articles?category=laravel) [AI](https://www.msaied.com/articles?category=ai) 

 Laravel AI SDK 1.4: Agents Now Recover From Tool Failures
==========================================================

 Laravel AI SDK v1.4.0 lets agents recover from tool exceptions instead of failing the run, improves fake agent testing for approval flows, exposes raw HTTP responses on more response types, and fixes OpenAI billing error handling.

 ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://www.msaied.com#person) Published 12 Nov 2026 · Updated 15 Nov 2026 · 4 min read

ShareCopy linkCopied

 ![Laravel AI SDK 1.4: Agents Now Recover From Tool Failures](https://cdn.msaied.com/824/9cedece04b58444cb565a8bec2be1737.png) 

  On this page +1. [Laravel AI SDK 1.4: Agents Now Recover From Tool Failures](#laravel-ai-sdk-14-agents-now-recover-from-tool-failures)
2. [Agents Recover From Tool Failures](#agents-recover-from-tool-failures)
3. [Test Tool Approval Flows With Agent Fakes](#test-tool-approval-flows-with-agent-fakes)
4. [Raw HTTP Responses on More Response Types](#raw-http-responses-on-more-response-types)
5. [OpenAI Billing Errors Throw InsufficientCreditsException](#openai-billing-errors-throw-codeinsufficientcreditsexceptioncode)
6. [Stream Errors Broadcast Under a Fixed Name](#stream-errors-broadcast-under-a-fixed-name)
7. [Other Fixes](#other-fixes)
8. [Key Takeaways](#key-takeaways)

 Laravel AI SDK 1.4: Agents Now Recover From Tool Failures
---------------------------------------------------------

Laravel AI SDK v1.4.0 ships a meaningful change to how agents handle tool exceptions, along with several quality-of-life improvements for testing, debugging, and provider error handling. Here is what changed and what you need to update.

### Agents Recover From Tool Failures

Previously, an unhandled exception inside a tool ended the entire agent run and fired `AgentFailed`. In v1.4.0, the SDK catches the exception and forwards its message to the model as a failed tool result. The model can then explain the problem to the user or attempt a different tool.

For example, if a `RefundOrder` tool throws `"Order 1234 can no longer be refunded."`, the model receives:

```yaml
The tool call failed: Order 1234 can no longer be refunded.

```

The exception is still reported via `report()`, the `ToolFailed` event still fires, and streamed runs emit a `ToolResult` event with `successful` set to `false`. Only the tool's own exception is recovered — an exception thrown inside an event listener still fails the run.

**Upgrade note:** If your code relied on a tool exception triggering `AgentFailed`, rethrow from a `ToolFailed` listener:

```php
use Illuminate\Support\Facades\Event;
use Laravel\Ai\Events\ToolFailed;

Event::listen(ToolFailed::class, fn (ToolFailed $event) => throw $event->exception);

```

### Test Tool Approval Flows With Agent Fakes

Human-in-the-loop approval pauses a run until someone approves or rejects a tool call. Under `Agent::fake()`, resuming a paused run previously skipped the tool entirely, making end-to-end approval testing impossible.

Faked agents now behave like a real provider on resume: approved tools run and their results are stored, rejected tools receive a denied result. Here is a complete example:

```php
SupportAgent::fake([
    new ToolCall('call-1', 'SendEmail', ['to' => 'john@example.com']),
    'The email is on its way.',
]);

$paused = (new SupportAgent)->forUser($user)->prompt('Email John the release notes');

$response = (new SupportAgent)
    ->continue($paused->conversationId, as: $user)
    ->prompt(Decisions::from(['call-1' => Decision::approve()]));

$response->toolResults[0]->result; // "Email sent to john@example.com."
$response->text;                   // "The email is on its way."

```

**Upgrade note:** A rejection without a reason now ends the turn. Tests that expected a reply after a bare rejection should pass a reason, such as `Decision::reject('Not now.')`.

### Raw HTTP Responses on More Response Types

The `raw` property — which holds the provider's original HTTP response — was previously available only on text responses. It is now available on classification, embeddings, transcription, image, and reranking responses. This lets you read provider-specific fields the SDK does not map, such as the `usage.cost` value OpenRouter returns:

```php
$response = Classification::of($ticket)
    ->questions($questions)
    ->classify(provider: 'openrouter');

$cost = $response->raw->json('usage.cost');

```

The property is `null` after serialization and `null` on embeddings when every vector came from the cache.

### OpenAI Billing Errors Throw `InsufficientCreditsException`

OpenAI returns HTTP 429 for both rate limits and billing problems (`insufficient_quota`, `credit_balance_exhausted`). The SDK previously treated every 429 as a rate limit, which could cause billing errors to be retried unnecessarily.

A 429 with a billing error code now throws `InsufficientCreditsException` and is not retried. Standard rate-limit 429s still throw `RateLimitedException`. Both exceptions remain failoverable.

**Upgrade note:** Code that catches `RateLimitedException` to handle OpenAI quota or billing errors must catch `InsufficientCreditsException` instead.

### Stream Errors Broadcast Under a Fixed Name

Provider errors in broadcast streams previously used the provider's error code (e.g., `403` or `PERMISSION_DENIED`) as the event name, making it impossible for a frontend to know which name to listen for. Provider errors now always broadcast as `error`. The payload's `type` field still carries the provider's code.

### Other Fixes

- Anthropic tool calls run when the message ends with `end_turn`; streamed text is joined across `pause_turn` continuations
- OpenAI-compatible tool calls run when sent without an index or finished with `stop`
- OpenAI batch embeddings preserve input order; custom voices are sent as an object
- Conversation title generation now fires the standard agent events and tracks token usage
- Mistral models updated to their latest versions

Key Takeaways
-------------

- Tool exceptions no longer kill the agent run; the model receives the failure and can respond gracefully
- Fake agents now fully simulate approval flows, enabling complete end-to-end tests
- `raw` is available on five additional response types for reading unmapped provider fields
- OpenAI billing errors are correctly distinguished from rate limits and are not retried
- Stream error events now broadcast under the predictable name `error`

Upgrade with `composer update laravel/ai`. Full details are in the [Laravel AI SDK 1.4.0 release notes](https://laravel-news.com/laravel-ai-sdk-1-4).

- [Laravel AI SDK](https://www.msaied.com/articles?search=Laravel%20AI%20SDK)
- [AI Agents](https://www.msaied.com/articles?search=AI%20Agents)
- [Laravel](https://www.msaied.com/articles?search=Laravel)
- [PHP](https://www.msaied.com/articles?search=PHP)
- [Tool Exceptions](https://www.msaied.com/articles?search=Tool%20Exceptions)
- [Release](https://www.msaied.com/articles?search=Release)

 Frequently asked questions 
---------------------------

  What happens when a tool throws an exception in Laravel AI SDK 1.4?Instead of ending the agent run and firing AgentFailed, the SDK catches the exception and sends its message back to the model as a failed tool result. The model can then explain the problem to the user or try a different tool. The exception is still reported via report() and the ToolFailed event still fires.

   How do I handle OpenAI billing errors differently from rate limit errors in Laravel AI SDK 1.4?In v1.4.0, a 429 response with an OpenAI billing code such as insufficient\_quota or credit\_balance\_exhausted throws InsufficientCreditsException instead of RateLimitedException, and is not retried. Update any catch blocks that previously caught RateLimitedException for billing scenarios to catch InsufficientCreditsException instead.

   Can I now test human-in-the-loop tool approval flows with Agent::fake()?Yes. In v1.4.0, faked agents resume paused tool calls the same way a real provider does. Approved tools run and their results are stored; rejected tools receive a denied result. This allows you to write end-to-end tests covering approve, reject, and edit decisions.

   ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp)About the author
----------------

[Mohamed Said](https://www.msaied.com#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#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 Read Replicas: Check if a Replica Has Caught Up with Commit IDs](https://www.msaied.com/articles/laravel-read-replicas-check-if-a-replica-has-caught-up-with-commit-ids)  

   On this page
-------------

1. [Laravel AI SDK 1.4: Agents Now Recover From Tool Failures](#laravel-ai-sdk-14-agents-now-recover-from-tool-failures)
2. [Agents Recover From Tool Failures](#agents-recover-from-tool-failures)
3. [Test Tool Approval Flows With Agent Fakes](#test-tool-approval-flows-with-agent-fakes)
4. [Raw HTTP Responses on More Response Types](#raw-http-responses-on-more-response-types)
5. [OpenAI Billing Errors Throw InsufficientCreditsException](#openai-billing-errors-throw-codeinsufficientcreditsexceptioncode)
6. [Stream Errors Broadcast Under a Fixed Name](#stream-errors-broadcast-under-a-fixed-name)
7. [Other Fixes](#other-fixes)
8. [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#contact) 

   Related articles
-----------------

 [ ![](https://cdn.msaied.com/822/5e40cb946aeac937ab3dc0017777ec8b.png) Laravel · 4 min read### Laravel Read Replicas: Check if a Replica Has Caught Up with Commit IDs

11 Nov 2026 ](https://www.msaied.com/articles/laravel-read-replicas-check-if-a-replica-has-caught-up-with-commit-ids) [ ![](https://cdn.msaied.com/823/3443348a15b03db8960a1180670529ff.png) Laravel · 4 min read### Replay Missed Laravel Scheduled Tasks With Schedule Catchup

9 Nov 2026 ](https://www.msaied.com/articles/replay-missed-laravel-scheduled-tasks-with-schedule-catchup) [ ![](https://cdn.msaied.com/821/88459f9998da0239229cdbcb6f7daa6c.png) Laravel · 3 min read### Insert Middleware Before or After Existing Laravel Middleware (Laravel 13.40)

6 Nov 2026 ](https://www.msaied.com/articles/insert-middleware-before-or-after-existing-laravel-middleware-laravel-1340) 

  Have a technical challenge?
----------------------------

Tell me what you’re building. I reply within two working days.

 [Discuss your project ↗](https://www.msaied.com#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)
- [Articles](https://www.msaied.com/articles)
- [Certificates](https://www.msaied.com/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/sitemap.xml)
