· Laravel · Laravel AI SDK · AI Agents
Laravel AI SDK 1.4: agents recover from tool failures
Laravel AI SDK 1.4 stops a throwing tool from ending an agent's run. What the model now sees, and when to retry, fail or stop.

Laravel AI SDK 1.4, released on 10 November 2026, changes what happens when one of your agent's tools throws an exception. Until now, a tool that threw ended the whole run: the exception came straight out of prompt() and the user got an error instead of an answer. From 1.4, the failure goes back to the model as a failed tool result, so the agent can explain what went wrong or try something else. If you have Laravel agents that call tools which touch databases, payment providers or third-party APIs, this changes how you should write those tools.
What changed in 1.4
The change is pull request #1191, "Let agents recover from tool failures". Its description puts it simply: a tool that throws no longer ends the run. The SDK catches the exception, reports it to your exception handler as before, and sends the model a tool result that reads The tool call failed: followed by the exception's message. When streaming, the failure appears as a failed tool result rather than an aborted stream.
This brings exceptions in line with the other ways a tool call can go wrong, which already fed back to the model:
- Invalid arguments. If you validate with
$request->validate(), the validation messages are returned to the model so it can correct them and call the tool again. - Unknown tools. With the
#[RepairToolCalls]attribute, a call to a tool that doesn't exist is returned with the names of the tools that do. - Running out of steps. A tool call on the final allowed step is answered with "The agent reached its maximum number of steps without running this tool call."
- Approvals. The pull request notes that tools needing human approval already worked this way, so every tool now behaves the same.
Two details are worth knowing. Only the tool's own exception is recovered: an exception thrown by an event listener, such as one listening for InvokingTool, still fails the run. And the failed result is visible to your code: each entry in the response's toolResults has successful() and error() methods, so you can tell a failed call from one that returned normally.
A worked example: a refund tool
The pull request's own example is a RefundOrder tool that throws "Order 1234 can no longer be refunded." That's a good case to build out, because a refund can fail in three quite different ways: the model passes bad arguments, the business rules say no, or the payment provider is having a bad day. Here's a tool that handles each one deliberately:
<?php
namespace App\Ai\Tools;
use App\Exceptions\RefundRefused;
use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Illuminate\Http\Client\ConnectionException;
use Illuminate\Http\Client\RequestException;
use Illuminate\Support\Facades\Http;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;
class RefundOrder implements Tool
{
public function description(): Stringable|string
{
return 'Refund a customer order in full. Only use this once the customer has confirmed.';
}
public function handle(Request $request): Stringable|string
{
// 1. Bad arguments: the messages go back to the model to fix.
$validated = $request->validate([
'order_id' => 'required|integer|exists:orders,id',
]);
$order = Order::findOrFail($validated['order_id']);
// 2. A business rule: a clear, customer-safe reason.
if (! $order->isRefundable()) {
throw new RefundRefused("Order {$order->id} was dispatched more than 30 days ago, so it can no longer be refunded.");
}
// 3. A flaky dependency: retry here, not in the model.
try {
$refund = Http::withToken(config('services.payments.key'))
->withHeaders(['Idempotency-Key' => "refund-{$order->id}"])
->retry([200, 1000, 3000], when: fn ($e) => $e instanceof ConnectionException || $e->response->serverError())
->post("https://payments.example.com/orders/{$order->id}/refunds")
->json();
} catch (ConnectionException|RequestException $e) {
report($e);
throw new RefundRefused("The payment provider didn't confirm the refund for order {$order->id}. Don't tell the customer it has been refunded; tell them the team will confirm by email.");
}
return "Refunded order {$order->id} (refund {$refund['id']}).";
}
public function schema(JsonSchema $schema): array
{
return [
'order_id' => $schema->integer()->required(),
];
}
}
And the agent that uses it. The instructions matter more than they used to: the model now sees failures, so tell it what to do with them.
<?php
namespace App\Ai\Agents;
use App\Ai\Tools\LookupOrder;
use App\Ai\Tools\RefundOrder;
use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Attributes\RepairToolCalls;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;
use Stringable;
#[MaxSteps(6)]
#[RepairToolCalls]
class SupportAgent implements Agent, HasTools
{
use Promptable;
public function instructions(): Stringable|string
{
return 'You help customers with their orders. If a tool call fails, do not retry it with the same arguments. '
.'Explain the problem in plain language and offer what you can do instead. '
.'Never say a refund has been made unless the RefundOrder tool succeeded.';
}
public function tools(): iterable
{
return [new LookupOrder, new RefundOrder];
}
}
Your exception messages are now prompts
This is the part that's easy to miss. Whatever your exception says is sent, word for word, to the model, and quite possibly on to the user. A QueryException includes the SQL, an HTTP client exception can include the response body, and some SDK exceptions include request IDs or more. None of that belongs in a prompt.
So treat a tool's exceptions as part of its interface. Catch infrastructure failures inside the tool and rethrow something short and safe, as the example does with RefundRefused. Write the message for the model: what happened, and what it should or shouldn't tell the customer. The original exception still reaches your logs if you report it before rethrowing.
It's also worth knowing that the SDK reports every tool exception to your exception handler. That's what you want for genuine errors, but a refund refused under policy isn't an error, and you probably don't want it in Sentry or Flare. Either return a plain string for expected outcomes (the call then counts as successful), or keep throwing and exclude the exception from reporting in bootstrap/app.php:
->withExceptions(function (Exceptions $exceptions): void {
$exceptions->dontReport([
RefundRefused::class,
]);
})
When to retry, when to fail, and when to stop
With the model in the loop, it's tempting to let it handle everything. I'd be more deliberate than that, because every retry the model makes is another step, another round trip and more tokens, and it's bounded by MaxSteps rather than any sense of whether retrying makes sense. Roughly:
- Transient failures (timeouts, rate limits, 5xx responses): retry inside the tool, with backoff, using
Http::retry()or theretry()helper. The model can't do anything useful about a 503 except try again, and your code can do that faster and cheaper. If the call moves money or changes state, send an idempotency key so a retry can't do it twice. - Bad input: validate with
$request->validate()and let the model correct itself. This is where the model really is the right thing to recover. - Business rules (not refundable, out of stock, not allowed): throw, or return, a clear reason and let the model explain it. This is the case 1.4 makes much nicer.
- Things that should stop the run: if a failure leaves you unsure of the state of something important, you may not want the model improvising. The SDK's tests show that a
ToolFailedlistener that rethrows the exception still fails the run, and theStopmiddleware can end a run before its next step.
use App\Exceptions\PaymentStateUnknown;
use Illuminate\Support\Facades\Event;
use Laravel\Ai\Events\ToolFailed;
Event::listen(function (ToolFailed $event) {
if ($event->exception instanceof PaymentStateUnknown) {
throw $event->exception;
}
});
That rethrowing behaviour comes from the SDK's tests rather than its documentation, so I'd cover it with a test of your own and re-check it when you upgrade.
Testing it
Agent fakes can return tool calls as well as text, which makes the failure path easy to test without a real model. The SDK's own tests for this feature use the same approach:
use App\Ai\Agents\SupportAgent;
use App\Models\Order;
use Laravel\Ai\Responses\Data\ToolCall;
test('a refused refund is explained, not crashed', function () {
$order = Order::factory()->create(['dispatched_at' => now()->subDays(45)]);
SupportAgent::fake([
new ToolCall('call_1', 'RefundOrder', ['order_id' => $order->id]),
"Sorry, that order is too old to refund, but I can help with an exchange.",
]);
$response = SupportAgent::make()->prompt("Please refund order {$order->id}");
expect($response->toolResults[0]->successful())->toBeFalse()
->and($response->toolResults[0]->error())->toContain('can no longer be refunded');
});
What I'd do
- Upgrade with
composer require laravel/ai:^1.4. It supports Laravel 12 and 13 on PHP 8.3 or later. - Read through every tool's exceptions and ask what the model, and the user, would see. Wrap anything that could leak SQL, URLs or response bodies.
- Move retries for flaky dependencies into the tools, with backoff and idempotency keys.
- Add a line to each agent's instructions about what to do when a tool fails, especially for tools with side effects.
- Decide which failures should still end the run, and make that explicit with a listener or middleware.
- Add a test for at least one failure path per tool.
It's a small change in the code, but a meaningful one for users: an agent that says "that order's too old to refund, but I can help with an exchange" is a lot better than one that falls over with a 500.
Sources
- Laravel AI SDK v1.4.0 release notes (GitHub, 10 November 2026)
- Let agents recover from tool failures, pull request #1191 (GitHub, merged 29 October 2026), including its tests
- Laravel AI SDK: Tools, Agent configuration, Stopping runs and Testing (Laravel documentation)
- HTTP Client: Retries and the retry helper (Laravel documentation)