Ehsan Bagherzadegan
Back to articles
5 min read

Laravel AI SDK 1.4: Agents That Recover From Tool Failures

Laravel AI SDK 1.4 changes how agents handle tool exceptions — failures no longer crash the run. The model receives the error as a tool result and can explain it to the user or try a different tool.

Laravel AI SDK 1.4 shipped on November 10 with a fundamental change to how agents handle tool failures. Previously, any exception thrown inside a tool would immediately terminate the agent run. Now the SDK catches the exception, reports it, and feeds the failure back to the model as a tool result — giving the agent a chance to explain the problem to the user or try a different approach.

This shift makes agents significantly more resilient in production. It also aligns the behavior of regular tools with approval-required tools, which have worked this way since earlier versions.

What changed

In v1.3 and earlier, a tool exception bubbled up and ended the run with an AgentFailed event. The conversation stopped there. The user saw an error, and the agent had no opportunity to recover.

In v1.4, the execution loop wraps each tool call in a try/catch. When a tool throws, the SDK:

  1. Reports the exception via Laravel's exception handler (so your Sentry/Flare integration still sees it)
  2. Fires a ToolFailed event for any listeners
  3. Constructs a failed ToolResult containing the exception message
  4. Sends that result back to the model as the tool's "return value"
  5. Continues the run — the model now decides what to do next

The model receives something like:

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

It can then apologize to the user, explain why the refund isn't possible, or call a different tool (perhaps CheckOrderStatus or EscalateToHuman).

Streaming behavior

For streaming runs, the failed tool result arrives as a ToolResult event with successful: false. Your frontend can render this differently from successful results — for example, showing a warning icon instead of a checkmark — without breaking the stream.

Only the tool's own exception is recovered

This is an important boundary. If your tool code throws, the agent recovers. But if an event listener (like a ToolExecuted listener that logs to an external service) throws, that exception still crashes the run. The SDK only wraps the tool handler itself.

// This exception -> agent recovers, model sees the failure
public function handle(RefundOrder $tool): string
{
    if ($tool->order->cannotBeRefunded()) {
        throw new \Exception("Order {$tool->order->id} can no longer be refunded.");
    }
    // ...
}

// This exception -> run still fails
ToolExecuted::listen(function (ToolExecuted $event) {
    throw new \Exception('Logging service down'); // not recovered
});

Exception class rename

The base exception for tool failures has been renamed from ToolHandlerException to ToolExecutionException. If you catch this type explicitly, update your imports:

use Laravel\Ai\Exceptions\ToolExecutionException; // v1.4+
// use Laravel\Ai\Exceptions\ToolHandlerException; // v1.3 and earlier

Testing: Agent fakes now resume approval flows

A companion improvement in v1.4 (PR #1190) makes Agent::fake() properly handle tool approval pauses. Previously, approved tools in a fake would be skipped; now they actually execute and store results, letting you write full end-to-end tests for human-in-the-loop flows.

use Laravel\Ai\Facades\Agent;
use Laravel\Ai\Testing\Decisions;
use Laravel\Ai\Testing\Decision;

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');

// Simulate the user approving the tool
$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."

If you reject a tool without providing a reason, the turn ends. Use Decision::reject('Not now.') to let the conversation continue.

Related: #[RepairToolCalls] for hallucinated tools

Since v0.11 (August 2026), the #[RepairToolCalls] attribute handles a different failure mode: when the model invents a tool name that doesn't exist. Instead of throwing NoSuchToolException and aborting, the SDK returns the failed call to the model along with the list of available local tools, giving it a chance to correct itself.

use Laravel\Ai\Attributes\RepairToolCalls;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

#[RepairToolCalls]
class SupportAgent implements Agent, HasTools
{
    use Promptable;
    // ...
}

When Laravel auto-calculates MaxSteps, this attribute adds one extra step for the repaired call. Explicit MaxSteps limits are unchanged.

You can combine both resilience mechanisms: #[RepairToolCalls] catches hallucinated tool names; the new v1.4 behavior catches runtime exceptions from valid tools.

Upgrading considerations

If your codebase relies on the old "tool exception = run failure" behavior, you have two options:

  1. Rethrow from a ToolFailed listener — catch the event and throw again if you truly want the run to stop.
  2. Let the model handle it — most cases are better served by letting the agent explain the failure to the user.

The RateLimitedException for OpenAI billing errors has also been replaced with InsufficientCreditsException. Update any provider-specific catch blocks accordingly.

When this matters

Tool failure recovery shines in scenarios where external dependencies are unreliable:

  • Payment APIs that return business-rule errors (expired card, insufficient funds, refund window closed)
  • Third-party services with rate limits or temporary outages
  • Database constraints that surface as exceptions rather than validation errors
  • File storage operations that fail due to permissions or quota

Instead of surfacing a raw exception to the user, the agent can say: "I tried to process the refund, but the payment provider says the 30-day window has closed. Would you like me to check if a store credit is possible instead?"

Takeaway

Laravel AI SDK 1.4 makes agents behave more like a human assistant: when a tool fails, they don't just crash — they report the problem and keep going. For production agent workloads, this is the difference between a brittle demo and a system that degrades gracefully.

Upgrade to ^1.4, review any ToolHandlerException catches, and consider where letting the model handle failures improves your user experience over showing an error page.

Sources