Mastering Non-Blocking AI: Background Agents with Laravel AI SDK 0.10.1

Large language models take time to think. Waiting three seconds for an HTTP response frustrates users. Modern web applications require instant feedback and seamless performance.

Laravel AI SDK 0.10.1 solves this friction. It moves intelligent workloads off the main thread and into background queues. You keep your application responsive while heavy models do the heavy lifting.

Artisan make:agent: Generating Your AI Classes

Building an AI agent starts in the terminal. You use standard artisan commands to scaffold your classes. This integrates neatly into your existing workflow as a PHP developer.

Run the generator to create a new agent:

php artisan make:agent SalesCoachAgent

This places a clean stub inside your app/Ai/Agents directory. You configure system instructions and provider models directly inside the class. Your codebase stays organized without boilerplate clutter.

Swapping .prompt() for .queue(): Non-Blocking Execution

Synchronous calls freeze your request lifecycle. When you call ->prompt(), your PHP process waits for external API roundtrips. That hurts throughput under heavy traffic.

Version 0.10.1 introduces the ->queue() method. You dispatch the payload to a background worker instantly:

use App\Ai\Agents\SalesCoachAgent;

Route::post('/analyze', function (Request $request) {
    (new SalesCoachAgent)->queue($request->input('transcript'));
    
    return response()->json(['status' => 'processing']);
});

The HTTP request returns immediately. Your users experience zero lag while the php web framework handles execution asynchronously.

Handling Workers: The Power of .then() and .catch()

Background jobs need robust error handling. The queue() method returns a dispatch builder supporting callback closures. These closures execute entirely on your queue worker.

Chain your success and failure callbacks directly onto the invocation:

(new SalesCoachAgent)
    ->queue($transcript)
    ->then(function (AgentResponse $response) {
        Log::info('Agent finished', ['text' => $response->text]);
    })
    ->catch(function (Throwable $e) {
        Log::error('Agent failed', ['error' => $e->getMessage()]);
    });

This pattern keeps business logic clean. Workers process tokens reliably without leaking state to the web tier.

Tracking Progress: Creating a Custom AiRun Model

Background jobs run detached from the original HTTP cycle. Users need a way to check status updates without guessing. You build a queryable status table using a custom AiRun model.

Create your migration and Eloquent model before dispatching:

$run = AiRun::create([
    'uuid' => Str::uuid(),
    'status' => 'pending',
    'user_id' => auth()->id(),
]);

(new SalesCoachAgent)
    ->queue($transcript)
    ->then(function (AgentResponse $response) use ($run) {
        $run->update([
            'status' => 'completed',
            'output' => $response->text,
        ]);
    });

Persisting state gives you a complete audit trail. It forms the backbone of any robust system designed to build rest api with php endpoints.

Frontend Integration: Livewire and wire:poll

Displaying background results requires reactive frontend components. Livewire makes this trivial with polling directives. You check the database record status at regular intervals.

Set up your Livewire component view:

<div wire:poll.2s="checkRunStatus">
    @if($run->isCompleted())
        <p>{{ $run->output }}</p>
    @else
        <p>AI is thinking in the background...</p>
    @endif
</div>

The interface updates automatically when the worker finishes. Users get a modern, snappy application feel without writing complex JavaScript polling loops.

Preventing Double-Billing: Implementing Idempotency Keys

Queued jobs can occasionally retry due to network dropouts or worker restarts. Running an expensive AI prompt twice wastes tokens and budget. You secure your agent calls with idempotency keys.

Hash your incoming request payload before queuing:

$idempotencyKey = hash('sha256', $transcript . auth()->id());

if (AiRun::where('key', $idempotencyKey)->exists()) {
    return response()->json(['message' => 'Already processing'], 409);
}

This simple guard protects your application margins. You leverage powerful php developer tools to ship robust features with confidence.

Moving Forward with Background Intelligence

Offloading AI tasks protects your server resources and delights your users. You combine clean queue management with reactive frontends effortlessly.

Try implementing .queue() in your next feature. We would love to hear how you build faster applications with Laravel AI SDK 0.10.1.