Laravel AI SDK 1.0 aggiunge la classificazione e le approvazioni degli strumenti

Il team di Laravel ha appena rilasciato la versione 1.0 del Laravel AI SDK, il pacchetto first-party che offre un'unica API per lavorare con i provider AI in un'app Laravel.

L'SDK era stato annunciato per la prima volta a febbraio. Questa release aggiunge una nuova funzionalità di classificazione, il supporto per due protocolli di chat frontend e un nuovo formato di archiviazione per le conversazioni. Include anche breaking changes, quindi controllate le note di aggiornamento qui sotto prima di aggiornare.

composer require laravel/ai

Classificazione

La classificazione è ora una funzionalità a sé stante, accanto a testo, immagini, audio ed embeddings. Copre decisioni rapide come l'instradamento di un ticket di supporto o la segnalazione di un commento. Funziona sui modelli Jev di TypeSafe e, secondo il post, Jev può rispondere a queste domande "in millisecondi a una frazione del prezzo dei tradizionali LLM".

Si pone un insieme di domande e si ottiene una risposta tipizzata per ognuna:

use Laravel\Ai\Classification;
use Laravel\Ai\Classification\Boolean;
use Laravel\Ai\Classification\Choice;

$response = Classification::of($ticket->body)->questions([
    'is_urgent' => new Boolean('Does this message convey urgency?'),
    'department' => new Choice('Which team should handle this?', [
        'billing' => 'Payments, invoicing, refunds',
        'technical' => 'Bugs, outages, integrations',
        'sales' => 'Pricing, plans, upgrades',
    ]),
])->classify();

$response['is_urgent']->isTrue();
$response['department']->choice; // 'technical'

Esiste anche un tipo di domanda Score che restituisce un valore da 0.0 a 1.0. Per una singola domanda sì/no, la nuova macro Str::decide restituisce un boolean, e un argomento threshold imposta quanto deve essere sicuro il modello:

Str::of($message)->decide('Is this spam?');

Oggi la classificazione funziona con TypeSafe e OpenRouter. Il team prevede di aggiungere altri provider dietro la stessa API man mano che rilasciano modelli simili.

Streaming con Vercel Chat e AG-UI

L'SDK ora può leggere le richieste e fare streaming delle risposte usando i protocolli Vercel Chat e AG-UI, così potete abbinarlo a librerie frontend che li parlano già. Ecco una route di chat Vercel:

use Illuminate\Http\Request;
use Laravel\Ai\Vercel\Vercel;

Route::post('/chat', function (Request $request) {
    $chat = Vercel::chat($request);

    return (new SupportAgent)
        ->withMessages($chat->history())
        ->stream($chat)
        ->usingProtocol($chat->protocol());
});

Questa route legge il nuovo messaggio, aggiorna la cronologia della conversazione nel vostro database ed elabora le eventuali approvazioni degli strumenti inviate dall'utente. Per i client AG-UI come CopilotKit, chiamate invece usingAgentUserInteractionProtocol() sullo stream. Vercel::toUiMessages() converte i messaggi memorizzati nel formato del client quando dovete ricostruire una schermata di chat dopo un ricaricamento della pagina.

Chiamate agli strumenti approvabili

Uno strumento che implementa il contract Approvable e usa il trait InteractsWithApprovals mette in pausa l'agent finché qualcuno non lo approva. Funziona benissimo per uno strumento che elimina file:

use Laravel\Ai\Concerns\InteractsWithApprovals;
use Laravel\Ai\Contracts\Approvable;
use Laravel\Ai\Contracts\Tool;

class DeleteFile implements Approvable, Tool
{
    use InteractsWithApprovals;

    // ...
}

La risposta elenca ogni chiamata in sospeso con gli argomenti scelti dal modello. Si riprende la conversazione con una decisione per ciascuna. Una decisione può approvare la chiamata, rifiutarla con una motivazione che il modello vede, oppure modificare gli argomenti prima che lo strumento venga eseguito. Le approvazioni funzionano con prompt, stream, queue e i metodi di broadcast. Abbiamo trattato le approvazioni degli strumenti quando sono arrivate a luglio.

Altre novità nella 1.0

• Middleware per-step: il middleware dell'agent ora viene eseguito a ogni step di generazione invece che una volta per prompt. Ogni step arriva come un PendingStep che potete modificare con metodi come withModel, withTools, withoutTools e withMaxTokens. Per esempio, potete rimuovere uno strumento costoso dopo che l'agent l'ha usato una volta.
• Ricerca degli strumenti: racchiudete gli strumenti usati di rado in ToolSearch e il provider li caricherà solo quando un prompt ne ha bisogno. Funziona su OpenAI e Anthropic.
• Esecuzione di codice: lo strumento provider CodeExecution esegue codice nella sandbox del provider, su Anthropic, OpenAI, Azure, Gemini e xAI.
• Step delle conversazioni: i messaggi ora memorizzano un'unica colonna JSON steps con una voce per ogni round-trip, e ogni risultato di uno strumento viene memorizzato insieme alla chiamata che l'ha prodotto.
• Report sull'utilizzo: promptTokens e completionTokens ora sono inputTokens e outputTokens, e includono i conteggi completi del provider su tutti i provider.

Aggiornamento alla 1.0

Le breaking changes riguardano soprattutto l'archiviazione delle conversazioni, il middleware degli agent, l'utilizzo dei token e i protocolli di stream. Se eseguite SQL grezzo sulle colonne tool_calls o tool_results, dovrete spostarlo su steps. La guida all'aggiornamento include anche una migration di backfill che dovete eseguire una volta prima di fare il deploy della 1.0.

Il team consiglia di affidare gran parte dell'aggiornamento a un assistente AI con Laravel Boost:

composer require laravel/boost --dev
php artisan boost:install

Poi eseguite lo slash command /upgrade-ai-sdk-v1 in Claude Code, Cursor, OpenCode, Gemini o VS Code, e Boost guiderà il vostro assistente attraverso la guida una modifica alla volta.

Leggete l'annuncio completo per tutti gli esempi di codice e consultate la documentazione dell'AI SDK per iniziare.