Laravel AI SDK - Knowledge of Laravel

Introduzione

Laravel AI SDK fornisce un’API unificata ed espressiva per dialogare con provider AI come OpenAI, Anthropic, Gemini. Con l’AI SDK puoi realizzare, tramite un’interfaccia coerente e nello stile di Laravel, tante funzionalità AI: costruire agenti intelligenti dotati di tool e output strutturato, generare immagini, sintetizzare/trascrivere audio, creare embedding vettoriali e molto altro.

Laravel AI SDK è il pacchetto ufficiale aggiunto in Laravel 13. È distribuito come laravel/ai e permette di usare più provider AI attraverso la stessa API.

Provider supportati

Funzionalità	Provider supportati
Generazione testo	OpenAI, OpenAI Compatible, Anthropic, Gemini, Azure, Bedrock, Groq, xAI, DeepSeek, Mistral, Ollama, OpenRouter
Generazione immagini	OpenAI, Gemini, xAI, Azure, Bedrock, OpenRouter
Sintesi vocale (TTS)	OpenAI, ElevenLabs, Gemini
Riconoscimento vocale (STT)	OpenAI, ElevenLabs, Mistral, Gemini
Embedding	OpenAI, Gemini, Azure, Bedrock, Cohere, Mistral, Jina, VoyageAI, Ollama, OpenRouter
Reranking	Cohere, Jina, VoyageAI
File	OpenAI, Anthropic, Gemini, Azure

Installazione

Installa il pacchetto

Installa Laravel AI SDK tramite Composer.

composer require laravel/ai

Pubblica file di configurazione e migrazioni

Pubblica i file di configurazione e le migrazioni con il comando Artisan vendor:publish.

php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

Esegui le migrazioni

Esegui le migrazioni del database. Vengono create le tabelle agent_conversations e agent_conversation_messages, usate per salvare lo storico delle conversazioni.

php artisan migrate

Configurazione

Variabili d’ambiente

Imposta nel file .env le API key dei provider AI che utilizzi.

ANTHROPIC_API_KEY=
AZURE_OPENAI_API_KEY=
COHERE_API_KEY=
DEEPSEEK_API_KEY=
ELEVENLABS_API_KEY=
GEMINI_API_KEY=
GROQ_API_KEY=
MISTRAL_API_KEY=
OLLAMA_API_KEY=
OPENAI_API_KEY=
OPENROUTER_API_KEY=
JINA_API_KEY=
VOYAGEAI_API_KEY=
XAI_API_KEY=

I modelli predefiniti per testo, immagini, audio, trascrizioni ed embedding possono essere configurati in config/ai.php.

Base URL personalizzate

Se vuoi passare per un servizio proxy, puoi impostare una URL personalizzata per ciascun provider.

'providers' => [
    'openai' => [
        'driver' => 'openai',
        'key' => env('OPENAI_API_KEY'),
        'url' => env('OPENAI_URL'),
    ],
    'anthropic' => [
        'driver' => 'anthropic',
        'key' => env('ANTHROPIC_API_KEY'),
        'url' => env('ANTHROPIC_BASE_URL'),
    ],
],

La base URL personalizzata è supportata per OpenAI, Anthropic, Gemini, Groq, Cohere, DeepSeek, xAI e OpenRouter.

Provider OpenAI-Compatible

Se usi API compatibili con OpenAI (LM Studio, vLLM, Together, Fireworks, gateway locali ecc.), puoi configurare il provider con il driver openai-compatible. url è obbligatoria e, se specifichi key, viene inviata come Bearer token.

'providers' => [
    'local' => [
        'driver' => 'openai-compatible',
        'url' => env('LOCAL_AI_URL'),
        'key' => env('LOCAL_AI_API_KEY'),
    ],
],

Dopo la configurazione, puoi indicarlo per nome come qualsiasi altro provider.

agent()->prompt('What is Laravel?', provider: 'local', model: 'local-model');

Impostando un modello di testo predefinito, puoi usarlo senza specificare il modello a ogni chiamata.

'local' => [
    'driver' => 'openai-compatible',
    'url' => env('LOCAL_AI_URL'),
    'key' => env('LOCAL_AI_API_KEY'),
    'models' => [
        'text' => [
            'default' => env('LOCAL_AI_MODEL'),
        ],
    ],
],

Il provider OpenAI-Compatible supporta generazione di testo, streaming, tool, output strutturato e allegati immagine. Se l’endpoint richiede campi aggiuntivi nel body della richiesta, usa le opzioni del provider.

Enum Lab

Per riferirti ai provider dal codice usa l’enum Lab.

use Laravel\Ai\Enums\Lab;

Lab::Anthropic;
Lab::OpenAI;
Lab::Gemini;

Agenti

Gli agenti sono il mattone fondamentale di Laravel AI SDK. Puoi generare una classe agente con il comando make:agent.

php artisan make:agent SalesCoach

# generazione di un agente con output strutturato
php artisan make:agent SalesCoach --structured

L’agente generato viene collocato nella directory app/Ai/Agents/. Ecco un esempio di agente che implementa tutte le principali interfacce.

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\RetrievePreviousTranscripts;
use App\Models\History;
use App\Models\User;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Messages\Message;
use Laravel\Ai\Promptable;
use Stringable;

class SalesCoach implements Agent, Conversational, HasTools, HasStructuredOutput
{
    use Promptable;

    public function __construct(public User $user) {}

    public function instructions(): Stringable|string
    {
        return 'You are a sales coach, analyzing transcripts and providing feedback and an overall sales strength score.';
    }

    public function messages(): iterable
    {
        return History::where('user_id', $this->user->id)
            ->latest()
            ->limit(50)
            ->get()
            ->reverse()
            ->map(function ($message) {
                return new Message($message->role, $message->content);
            })->all();
    }

    public function tools(): iterable
    {
        return [new RetrievePreviousTranscripts];
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'feedback' => $schema->string()->required(),
            'score' => $schema->integer()->min(1)->max(10)->required(),
        ];
    }
}

Prompt

Invia un messaggio all’agente con il metodo prompt().

$response = (new SalesCoach)->prompt('Analyze this sales transcript...');
return (string) $response;

Con il metodo statico make() puoi creare un’istanza risolvendo le dipendenze dal container.

$agent = SalesCoach::make(user: $user);

Provider, modello e timeout possono essere sovrascritti dagli argomenti di prompt().

$response = (new SalesCoach)->prompt(
    'Analyze this sales transcript...',
    provider: Lab::Anthropic,
    model: 'claude-haiku-4-5-20251001',
    timeout: 120,
);

Contesto conversazionale

Implementando l’interfaccia Conversational e definendo il metodo messages(), puoi passare all’AI lo storico delle conversazioni precedenti. Usando il trait RemembersConversations puoi salvare e recuperare automaticamente lo storico delle conversazioni nel database.

use Laravel\Ai\Concerns\RemembersConversations;

class SalesCoach implements Agent, Conversational
{
    use Promptable, RemembersConversations;

    public function instructions(): string
    {
        return 'You are a sales coach...';
    }
}

Con forUser() inizi una conversazione; usando il conversationId restituito puoi continuare la conversazione con continue().

$response = (new SalesCoach)->forUser($user)->prompt('Hello!');
$conversationId = $response->conversationId;

$response = (new SalesCoach)->continue($conversationId, as: $user)->prompt('Tell me more about that.');

Output strutturato

Implementando l’interfaccia HasStructuredOutput e definendo lo schema JSON nel metodo schema(), puoi ricevere la risposta dell’AI come dato strutturato.

public function schema(JsonSchema $schema): array
{
    return ['score' => $schema->integer()->required()];
}

$response = (new SalesCoach)->prompt('Analyze this...');
return $response['score'];

Oggetti annidati

public function schema(JsonSchema $schema): array
{
    return [
        'score' => $schema->integer()->required(),
        'metadata' => $schema->object(fn ($schema) => [
            'confidence' => $schema->string()->enum(['low', 'medium', 'high'])->required(),
            'language' => $schema->string()->required(),
        ])->required(),
    ];
}

Array di oggetti

public function schema(JsonSchema $schema): array
{
    return [
        'feedback' => $schema->array()->items(
            $schema->object(fn ($schema) => [
                'comment' => $schema->string()->required(),
                'score' => $schema->integer()->required(),
            ])
        )->required(),
    ];
}

anyOf (scelta tra più schemi)

Quando un valore deve corrispondere a uno tra diversi schemi, usa il metodo anyOf.

public function schema(JsonSchema $schema): array
{
    return [
        'content' => $schema->anyOf([
            $schema->object(fn ($schema) => [
                'type' => $schema->string()->enum(['article'])->required(),
                'title' => $schema->string()->required(),
            ]),
            $schema->object(fn ($schema) => [
                'type' => $schema->string()->enum(['image'])->required(),
                'url' => $schema->string()->required(),
            ]),
        ])->required(),
    ];
}

Allegati

Puoi passare documenti o immagini all’agente tramite l’argomento attachments.

use Laravel\Ai\Files;

$response = (new SalesCoach)->prompt(
    'Analyze the attached sales transcript...',
    attachments: [
        Files\Document::fromStorage('transcript.pdf'),
        Files\Document::fromPath('/home/laravel/transcript.md'),
        $request->file('transcript'),
    ]
);

Le immagini si allegano allo stesso modo.

$response = (new ImageAnalyzer)->prompt('What is in this image?', attachments: [
    Files\Image::fromStorage('photo.jpg'),
    Files\Image::fromPath('/home/laravel/photo.jpg'),
    $request->file('photo'),
]);

Streaming

Con il metodo stream() puoi restituire la risposta in chunk. Utile per inviare in tempo reale al frontend risposte molto lunghe.

Route::get('/coach', function () {
    return (new SalesCoach)->stream('Analyze this sales transcript...');
});

Con la callback then() puoi definire il post-processing dopo il completamento dello streaming.

use Laravel\Ai\Responses\StreamedAgentResponse;

Route::get('/coach', function () {
    return (new SalesCoach)
        ->stream('Analyze this sales transcript...')
        ->then(function (StreamedAgentResponse $response) {
            // $response->text, $response->events, $response->usage...
        });
});

Puoi anche iterare manualmente sullo stream.

$stream = (new SalesCoach)->stream('Analyze this sales transcript...');

foreach ($stream as $event) {
    // ...
}

Protocollo Vercel AI SDK

Se usi Vercel AI SDK sul frontend, chiama usingVercelDataProtocol().

Route::get('/coach', function () {
    return (new SalesCoach)->stream('Analyze...')->usingVercelDataProtocol();
});

Broadcasting

Puoi inviare gli eventi dello stream ai canali di broadcasting, ad esempio Laravel Echo.

use Illuminate\Broadcasting\Channel;

$stream = (new SalesCoach)->stream('Analyze this sales transcript...');

foreach ($stream as $event) {
    $event->broadcast(new Channel('channel-name'));
}

Con broadcastOnQueue() puoi trasmettere passando per una coda.

(new SalesCoach)->broadcastOnQueue(
    'Analyze this sales transcript...',
    new Channel('channel-name'),
);

Saltare eventi troppo grandi

Alcune piattaforme di broadcasting limitano il messaggio WebSocket a circa 10 KB. Alcuni eventi dello stream con molti dati (ad esempio grandi risultati di tool) possono superare questo limite e fallire la trasmissione. Usa l’attributo WithoutBroadcasting per escludere dal broadcasting specifici tipi di evento.

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Attributes\WithoutBroadcasting;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;
use Laravel\Ai\Streaming\Events\ToolCall;
use Laravel\Ai\Streaming\Events\ToolResult;

#[WithoutBroadcasting(ToolCall::class, ToolResult::class)]
class SearchAgent implements Agent, HasTools
{
    use Promptable;

    // ...
}

Gli eventi esclusi non vengono trasmessi, ma vengono comunque salvati nella tabella agent_conversation_messages. Il frontend può quindi recuperare tutti i dati del tool a fine stream. Funziona sia in modalità coda (broadcastOnQueue) sia sincrona (broadcast / broadcastNow).

Code

Con il metodo queue() puoi accodare il prompt per l’elaborazione asincrona.

use Laravel\Ai\Responses\AgentResponse;

Route::post('/coach', function (Request $request) {
    (new SalesCoach)
        ->queue($request->input('transcript'))
        ->then(function (AgentResponse $response) { /* ... */ })
        ->catch(function (Throwable $e) { /* ... */ });

    return back();
});

Tool

I tool permettono all’AI di chiamare funzioni del tuo codice. Puoi generare una classe tool con il comando make:tool.

php artisan make:tool RandomNumberGenerator

<?php

namespace App\Ai\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class RandomNumberGenerator implements Tool
{
    public function description(): Stringable|string
    {
        return 'This tool may be used to generate cryptographically secure random numbers.';
    }

    public function handle(Request $request): Stringable|string
    {
        return (string) random_int($request['min'], $request['max']);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'min' => $schema->integer()->min(0)->required(),
            'max' => $schema->integer()->required(),
        ];
    }
}

Registra i tool dal metodo tools() dell’agente.

public function tools(): iterable
{
    return [new RandomNumberGenerator];
}

Tool di ricerca per similarità

Puoi aggiungere facilmente un tool di ricerca per similarità basato su embedding vettoriali.

use App\Models\Document;
use Laravel\Ai\Tools\SimilaritySearch;

public function tools(): iterable
{
    return [
        SimilaritySearch::usingModel(Document::class, 'embedding'),
    ];
}

Puoi passare anche opzioni.

SimilaritySearch::usingModel(
    model: Document::class,
    column: 'embedding',
    minSimilarity: 0.7,
    limit: 10,
    query: fn ($query) => $query->where('published', true),
),

Puoi anche definire una logica di ricerca personalizzata con una closure.

new SimilaritySearch(using: function (string $query) {
    return Document::query()
        ->where('user_id', $this->user->id)
        ->whereVectorSimilarTo('embedding', $query)
        ->limit(10)
        ->get();
}),

Con withDescription() puoi personalizzare la descrizione del tool.

SimilaritySearch::usingModel(Document::class, 'embedding')
    ->withDescription('Search the knowledge base for relevant articles.'),

Tool di storage file

Con la factory di tool FileStorage puoi dare all’agente l’accesso a un disco filesystem di Laravel. Il metodo all restituisce l’intero set di tool per elencare, leggere, generare URL, scrivere, cancellare e copiare file sul disco indicato.

use Laravel\Ai\Tools\FileStorage;

public function tools(): iterable
{
    return FileStorage::all('local');
}

Per concedere solo l’accesso in sola lettura usa il metodo readOnly.

return FileStorage::readOnly('local');

Questi metodi restituiscono una Illuminate\Support\Collection, quindi puoi restringere ulteriormente i tool forniti.

use Laravel\Ai\Tools\Filesystem\DeleteFile;

return FileStorage::all('s3')
    ->reject(fn ($tool) => $tool instanceof DeleteFile);

Tool MCP

Se nella tua applicazione usi Laravel MCP, puoi mettere a disposizione dell’agente i tool esposti da un server Model Context Protocol. Usando il client MCP di Laravel puoi connetterti a un server MCP remoto o locale e passarne i tool direttamente all’agente.

Per usare i tool MCP nella tua applicazione deve essere installato il pacchetto Laravel MCP.

Il metodo tools del client MCP restituisce una collection, quindi usa l’operatore di spread ... per espanderla nell’array tools dell’agente.

use App\Ai\Tools\RandomNumberGenerator;
use Laravel\Mcp\Client;

/**
 * Get the tools available to the agent.
 *
 * @return Tool[]
 */
public function tools(): iterable
{
    return [
        ...Client::web('https://mcp.example.com')
            ->withToken($token)
            ->tools(),

        new RandomNumberGenerator,
    ];
}

L’AI SDK avvolge automaticamente ogni tool MCP in modo che l’agente possa richiamarlo come qualsiasi altro tool. Puoi anche usare client MCP con nome.

use Laravel\Mcp\Facades\Mcp;

public function tools(): iterable
{
    return [
        ...Mcp::client('github')->tools(),
    ];
}

Oppure connetterti a un server MCP locale.

use Laravel\Mcp\Client;

public function tools(): iterable
{
    return [
        ...Client::local('php', ['artisan', 'mcp:start'])->tools(),
    ];
}

Per la creazione del client MCP e l’autenticazione (Bearer token, OAuth ecc.) consulta la documentazione del client MCP.

Tool del provider

Tool speciali implementati nativamente dai provider AI.

Ricerca web

Aggiunge una ricerca web all’agente. Supportata da Anthropic, OpenAI, Gemini e OpenRouter.

use Laravel\Ai\Providers\Tools\WebSearch;

public function tools(): iterable
{
    return [new WebSearch];
}

Puoi specificare opzionalmente il numero di risultati, la restrizione di dominio e le informazioni di località.

(new WebSearch)->max(5)->allow(['laravel.com', 'php.net']),
(new WebSearch)->location(city: 'New York', region: 'NY', country: 'US');

Recupero web

Un tool per recuperare il contenuto di un URL indicato. Supportato da Anthropic e Gemini.

use Laravel\Ai\Providers\Tools\WebFetch;

public function tools(): iterable
{
    return [new WebFetch];
}

(new WebFetch)->max(3)->allow(['docs.laravel.com']),

Ricerca file

Un tool per cercare documenti in un vector store. Supportato da OpenAI e Gemini.

use Laravel\Ai\Providers\Tools\FileSearch;

public function tools(): iterable
{
    return [new FileSearch(stores: ['store_id'])];
}

// più store
new FileSearch(stores: ['store_1', 'store_2']);

// filtro sui metadati
new FileSearch(stores: ['store_id'], where: ['author' => 'Taylor Otwell', 'year' => 2026]);

Puoi anche specificare filtri complessi con FileSearchQuery.

use Laravel\Ai\Providers\Tools\FileSearchQuery;

new FileSearch(stores: ['store_id'], where: fn (FileSearchQuery $query) =>
    $query->where('author', 'Taylor Otwell')
          ->whereNot('status', 'draft')
          ->whereIn('category', ['news', 'updates'])
);

Sub-agenti

Un agente può essere restituito anche dal metodo tools() di un altro agente. Registrando un agente come tool, un agente principale può delegare a un sub-agente compiti specifici e integrarne il risultato nella risposta originale. È utile quando un agente generico deve accedere a un agente specializzato con istruzioni, tool, configurazioni di modello e provider dedicati. Ad esempio, un agente di customer support delega le domande sulla politica di rimborso a un agente specializzato in rimborsi.

<?php

namespace App\Ai\Agents;

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

class CustomerSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You help customers with account, order, and billing questions. Delegate refund policy questions to the refunds specialist.';
    }

    public function tools(): iterable
    {
        return [
            new RefundsAgent,
        ];
    }
}

Per personalizzare come il sub-agente viene presentato all’agente principale, implementa nel sub-agente l’interfaccia CanActAsTool e definisci nome e descrizione da usare come tool.

<?php

namespace App\Ai\Agents;

use App\Ai\Tools\LookupOrder;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\CanActAsTool;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

#[Provider(Lab::Anthropic)]
class RefundsAgent implements Agent, CanActAsTool, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a refunds specialist. Use order details and the refund policy to give concise eligibility guidance.';
    }

    public function name(): string
    {
        return 'refunds_specialist';
    }

    public function description(): string
    {
        return 'Determine whether an order is eligible for a refund and explain the next step.';
    }

    public function tools(): iterable
    {
        return [
            new LookupOrder,
        ];
    }
}

Per i sub-agenti che non implementano CanActAsTool, Laravel usa il nome della classe come nome del tool e genera automaticamente una descrizione generica. Ogni chiamata di sub-agente avviene in modo indipendente e non eredita lo storico della conversazione dell’agente principale.

Middleware

Puoi aggiungere middleware all’agente per intercettare prompt e risposte.

php artisan make:agent-middleware LogPrompts

Implementa nell’agente l’interfaccia HasMiddleware e registra i middleware nel metodo middleware().

<?php

namespace App\Ai\Agents;

use App\Ai\Middleware\LogPrompts;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasMiddleware;
use Laravel\Ai\Promptable;

class SalesCoach implements Agent, HasMiddleware
{
    use Promptable;

    public function middleware(): array
    {
        return [new LogPrompts];
    }
}

Esempio di implementazione di un middleware.

<?php

namespace App\Ai\Middleware;

use Closure;
use Laravel\Ai\Prompts\AgentPrompt;

class LogPrompts
{
    public function handle(AgentPrompt $prompt, Closure $next)
    {
        Log::info('Prompting agent', ['prompt' => $prompt->prompt]);
        return $next($prompt);
    }
}

Con then() puoi aggiungere anche logica successiva alla risposta.

public function handle(AgentPrompt $prompt, Closure $next)
{
    return $next($prompt)->then(function (AgentResponse $response) {
        Log::info('Agent responded', ['text' => $response->text]);
    });
}

Agenti anonimi

Con l’helper agent() puoi usare un agente anonimo senza definire una classe.

use function Laravel\Ai\{agent};

$response = agent(
    instructions: 'You are an expert at software development.',
    messages: [],
    tools: [],
)->prompt('Tell me about Laravel');

Puoi anche creare agenti anonimi con output strutturato.

use Illuminate\Contracts\JsonSchema\JsonSchema;

$response = agent(
    schema: fn (JsonSchema $schema) => ['number' => $schema->integer()->required()],
)->prompt('Generate a random number less than 100');

Configurazione dell’agente (attributi PHP)

Con gli attributi PHP puoi descrivere in modo dichiarativo le impostazioni predefinite dell’agente.

Attributo	Descrizione
`#[Provider]`	Indica il provider da usare
`#[Model]`	Indica il modello da usare
`#[MaxSteps]`	Numero massimo di step nelle chiamate di tool
`#[MaxTokens]`	Numero massimo di token
`#[Temperature]`	Parametro temperature (0.0–1.0)
`#[TopP]`	Probabilità di nucleus sampling (0.0–1.0)
`#[Timeout]`	Timeout (secondi)
`#[UseCheapestModel]`	Seleziona automaticamente il modello più economico
`#[UseSmartestModel]`	Seleziona automaticamente il modello più performante

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Attributes\MaxTokens;
use Laravel\Ai\Attributes\Model;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Attributes\Timeout;
use Laravel\Ai\Attributes\TopP;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

#[Provider(Lab::Anthropic)]
#[Model('claude-haiku-4-5-20251001')]
#[MaxSteps(10)]
#[MaxTokens(4096)]
#[Temperature(0.7)]
#[Timeout(120)]
#[TopP(0.9)]
class SalesCoach implements Agent
{
    use Promptable;
}

Sono disponibili anche attributi scorciatoia per la scelta del modello.

// usa il modello più economico
#[UseCheapestModel]
class SimpleSummarizer implements Agent
{
    use Promptable;
}

// usa il modello più performante
#[UseSmartestModel]
class ComplexReasoner implements Agent
{
    use Promptable;
}

Opzioni del provider

Implementando l’interfaccia HasProviderOptions puoi passare opzioni specifiche del provider.

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasProviderOptions;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

class SalesCoach implements Agent, HasProviderOptions
{
    use Promptable;

    public function providerOptions(Lab|string $provider): array
    {
        return match ($provider) {
            Lab::OpenAI => [
                'reasoning' => ['effort' => 'low'],
                'frequency_penalty' => 0.5,
                'presence_penalty' => 0.3,
            ],
            Lab::Anthropic => [
                'thinking' => ['budget_tokens' => 1024],
            ],
            default => [],
        };
    }
}

Approvazione umana (Human Tool Approval)

Per usare l’approvazione dei tool è necessario un agente Conversational con storico della conversazione persistente. Per riprendere una chiamata sospesa, il trait RemembersConversations fornisce la persistenza necessaria.

Per i tool che eseguono operazioni sensibili o irreversibili — come cancellare file o effettuare bonifici — puoi richiedere l’approvazione umana prima dell’esecuzione. Per rendere un tool soggetto ad approvazione, implementa il contract Approvable e usa il trait InteractsWithApprovals. Per default, i tool soggetti ad approvazione la richiedono sempre.

<?php

namespace App\Ai\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Illuminate\Support\Facades\Storage;
use Laravel\Ai\Concerns\InteractsWithApprovals;
use Laravel\Ai\Contracts\Approvable;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class DeleteFile implements Approvable, Tool
{
    use InteractsWithApprovals;

    /**
     * Ottieni la descrizione dello scopo del tool
     */
    public function description(): Stringable|string
    {
        return 'Cancella un file dallo storage.';
    }

    /**
     * Esegue il tool
     */
    public function handle(Request $request): Stringable|string
    {
        Storage::delete($request['path']);

        return "Cancellato: [{$request['path']}]";
    }

    /**
     * Ottieni la definizione dello schema del tool
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'path' => $schema->string()->required(),
        ];
    }
}

Se vuoi decidere se richiedere o meno l’approvazione in base agli argomenti della chiamata del tool, definisci il metodo needsApproval sul tool. Questo metodo può restituire un booleano oppure un’istanza Approval che include il motivo dell’approvazione.

use Laravel\Ai\Approvals\Approval;

/**
 * Determina se il tool richiede approvazione per la richiesta data
 */
protected function needsApproval(Request $request): Approval|bool
{
    return str_starts_with($request['path'], 'temporary/')
        ? false
        : Approval::required('Questo file verrà cancellato definitivamente.');
}

Puoi anche sovrascrivere il requisito di approvazione quando restituisci il tool dal metodo tools dell’agente.

public function tools(): iterable
{
    return [
        (new SendNotification)->withoutApproval(),
        (new DeleteFile)->requireApproval('La cancellazione richiede conferma.'),
    ];
}

Quando viene invocato un tool soggetto ad approvazione, l’agente si mette in pausa prima dell’esecuzione. Ispezionando pendingApprovals nella risposta puoi controllare ID, nome del tool, argomenti e motivo dell’approvazione per ciascuna chiamata.

$response = (new FileAssistant)
    ->forUser($user)
    ->prompt('Cancella le vecchie fatture.');

if ($response->hasPendingApprovals()) {
    foreach ($response->pendingApprovals as $approval) {
        // $approval->id
        // $approval->tool
        // $approval->arguments
        // $approval->reason
    }
}

Per riprendere l’agente, continua la conversazione passando un’istanza Decisions che contiene la decisione per ogni chiamata di tool in sospeso. Ogni decisione può approvare, rifiutare o modificare gli argomenti prima dell’esecuzione.

use Laravel\Ai\Approvals\Decision;
use Laravel\Ai\Approvals\Decisions;

$response = (new FileAssistant)
    ->continue($conversationId, as: $user)
    ->prompt(Decisions::from([
        'call_abc' => Decision::approve(),
        'call_ghi' => Decision::reject('Questa fattura va conservata.'),
    ]));

I booleani true e false sono scorciatoie per rispettivamente approvare e rifiutare. Per tutte le chiamate di tool in sospeso è necessaria una decisione. Passare ID di chiamate di tool sconosciuti, mancanti o già risolti solleva una ApprovalMismatchException. Per le chiamate senza una decisione esplicita puoi indicare una decisione di default con i metodi approveRemaining o rejectRemaining.

$decisions = Decisions::from([
    'call_abc' => true,
])->rejectRemaining('Non approvata.');

$response = (new FileAssistant)
    ->continue($conversationId, as: $user)
    ->prompt($decisions);

Rifiutando con un risultato come Decision::reject('Non approvata.'), il risultato viene restituito al modello e la risposta continua. Rifiutando senza risultato, il ciclo di generazione si arresta al momento in cui il rifiuto viene registrato. L’approvazione dei tool è supportata dai metodi prompt, stream, queue, broadcast, broadcastNow e broadcastOnQueue. Durante streaming e broadcasting, la sospensione è rappresentata come evento tool_approval_request. Se stai usando il protocollo stream di Vercel AI SDK, le richieste e i risultati di approvazione vengono emessi come part nativa di approvazione dei tool del protocollo. Per gli agenti in coda, la risposta risultante viene passata alla callback then e Laravel dispatcha anche l’evento ToolApprovalRequested. Laravel salva il risultato dell’esecuzione dei tool approvati prima di chiedere al modello di proseguire. Se la generazione successiva fallisce, le approvazioni sono già risolte. Non rinviare le stesse decisioni di approvazione: continua invece la conversazione con un normale prompt testuale.

Flusso completo di approvazione

Le route seguenti mostrano il flusso di approvazione completo. La route GET restituisce la schermata di chat, mentre la route POST riceve dal frontend un nuovo prompt testuale oppure una decisione di approvazione. Questo esempio presuppone che il modello User dell’applicazione usi il trait HasConversations.

use App\Ai\Agents\FileAssistant;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Gate;
use Illuminate\Support\Facades\Route;
use Illuminate\Validation\Rule;
use Laravel\Ai\Approvals\Decision;
use Laravel\Ai\Approvals\Decisions;
use Laravel\Ai\Models\Conversation;

Route::get('/chat/{conversation}', function (Request $request, Conversation $conversation) {
    Gate::authorize('view', $conversation);

    return view('chat', [
        'conversation' => $conversation,
    ]);
})->middleware('auth');

Route::post('/chat/{conversation}', function (Request $request, Conversation $conversation) {
    Gate::authorize('view', $conversation);

    $validated = $request->validate([
        'message' => ['nullable', 'string', 'required_without:decisions', 'prohibited_with:decisions'],
        'decisions' => ['nullable', 'array', 'required_without:message', 'prohibited_with:message'],
        'decisions.*.action' => ['required_with:decisions', Rule::in(['approve', 'reject'])],
        'decisions.*.result' => ['nullable', 'string'],
    ]);

    $prompt = isset($validated['decisions'])
        ? Decisions::from($validated->collect('decisions')->map(
            fn (array $decision) => match ($decision['action']) {
                'approve' => Decision::approve(),
                'reject' => Decision::reject($decision['result'] ?? null),
            }
        )->all())
        : $validated['message'];

    $response = (new FileAssistant)
        ->continue($conversation->id, as: $request->user())
        ->prompt($prompt);

    return [
        'conversation_id' => $response->conversationId,
        'status' => $response->hasPendingApprovals() ? 'awaiting_approval' : 'complete',
        'message' => $response->text,
        'approvals' => $response->pendingApprovals,
    ];
})->middleware('auth');

Se lo status della risposta è awaiting_approval, la schermata di chat deve mostrare le approvazioni in sospeso e inviare allo stesso endpoint la scelta dell’utente, usando come chiave l’ID della chiamata di tool.

{
    "decisions": {
        "call_abc": {
            "action": "approve"
        },
        "call_def": {
            "action": "reject",
            "result": "Questa fattura va conservata."
        }
    }
}

Per un normale messaggio di chat, invia invece il valore di message.

{
    "message": "Cancella le vecchie fatture."
}

Il flusso di approvazione è un meccanismo che dà agli agenti AI poteri operativi molto forti, ma consente di inserire una verifica umana prima dell’esecuzione. Sfruttalo per i tool che comportano operazioni irreversibili come cancellazione di file, elaborazione di pagamenti o scritture verso API esterne.

Generazione di immagini

Puoi generare immagini con la classe Image. Supportata da OpenAI, Gemini e xAI.

use Laravel\Ai\Image;

$image = Image::of('A donut sitting on the kitchen counter')->generate();
$rawContent = (string) $image;

Puoi specificare qualità, aspect ratio e timeout.

$image = Image::of('A donut sitting on the kitchen counter')
    ->quality('high')
    ->landscape()
    ->timeout(120)
    ->generate();

Puoi anche allegare un’immagine di riferimento da elaborare.

use Laravel\Ai\Files;

$image = Image::of('Update this photo to be in the style of an impressionist painting.')
    ->attachments([Files\Image::fromStorage('photo.jpg')])
    ->landscape()
    ->generate();

Salvataggio dell’immagine

$path = $image->store();
$path = $image->storeAs('image.jpg');
$path = $image->storePublicly();
$path = $image->storePubliclyAs('image.jpg');

Generazione di immagini in coda

use Laravel\Ai\Responses\ImageResponse;

Image::of('A donut sitting on the kitchen counter')
    ->portrait()
    ->queue()
    ->then(function (ImageResponse $image) {
        $path = $image->store();
    });

Sintesi vocale (TTS)

Puoi convertire testo in audio con la classe Audio. Supportata da OpenAI ed ElevenLabs.

use Laravel\Ai\Audio;

$audio = Audio::of('I love coding with Laravel.')->generate();
$rawContent = (string) $audio;

Puoi specificare il genere della voce, un voice ID specifico e istruzioni di stile.

$audio = Audio::of('I love coding with Laravel.')->female()->generate();
$audio = Audio::of('I love coding with Laravel.')->voice('voice-id-or-name')->generate();
$audio = Audio::of('I love coding with Laravel.')->female()->instructions('Said like a pirate')->generate();

Salvataggio dell’audio

$path = $audio->store();
$path = $audio->storeAs('audio.mp3');
$path = $audio->storePublicly();
$path = $audio->storePubliclyAs('audio.mp3');

Generazione dell’audio in coda

use Laravel\Ai\Responses\AudioResponse;

Audio::of('I love coding with Laravel.')
    ->queue()
    ->then(function (AudioResponse $audio) {
        $path = $audio->store();
    });

Trascrizione (STT)

Puoi convertire file audio in testo con la classe Transcription. Supportata da OpenAI, ElevenLabs e Mistral.

use Laravel\Ai\Transcription;

$transcript = Transcription::fromPath('/home/laravel/audio.mp3')->generate();
$transcript = Transcription::fromStorage('audio.mp3')->generate();
$transcript = Transcription::fromUpload($request->file('audio'))->generate();

return (string) $transcript;

Diarizzazione (separazione degli speaker)

Con diarize() ottieni una trascrizione separata per parlante.

$transcript = Transcription::fromStorage('audio.mp3')->diarize()->generate();

Trascrizione in coda

use Laravel\Ai\Responses\TranscriptionResponse;

Transcription::fromStorage('audio.mp3')
    ->queue()
    ->then(function (TranscriptionResponse $transcript) { /* ... */ });

Riassunto di testi (Text Summarization)

Con il metodo summarize fornito dalla classe Stringable di Laravel puoi riassumere un testo. Per default il riassunto è entro tre frasi e viene usato il modello di testo più economico del provider configurato.

use Illuminate\Support\Str;

$summary = Str::of($article)->summarize();

Puoi specificare anche il numero massimo di frasi, il provider, il modello e il timeout. La classe Str fornisce anche una versione statica del metodo.

use Laravel\Ai\Enums\Lab;

$summary = Str::of($article)->summarize(
    sentences: 4,
    provider: Lab::Anthropic,
    model: 'claude-sonnet-5',
    timeout: 30,
);

$summary = Str::summarize($article, sentences: 4);

Embedding

Puoi trasformare il testo in rappresentazioni vettoriali per la ricerca per similarità e altri scenari.

use Illuminate\Support\Str;

// tramite Stringable
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings();

use Laravel\Ai\Embeddings;

// più testi in un'unica chiamata
$response = Embeddings::for(['Napa Valley has great wine.', 'Laravel is a PHP framework.'])->generate();
$response->embeddings; // [[0.123, 0.456, ...], [0.789, 0.012, ...]]

Puoi specificare provider, modello e numero di dimensioni.

$response = Embeddings::for(['Napa Valley has great wine.'])
    ->dimensions(1536)
    ->generate(Lab::OpenAI, 'text-embedding-3-small');

Embedding multimodali

Il metodo Embeddings::for non accetta solo stringhe: accetta anche input di immagini, audio, documenti e video, così puoi generare embedding anche per contenuti non testuali. Gemini supporta embedding di immagini, audio, documenti e video, mentre VoyageAI supporta embedding di immagini e video.

use Laravel\Ai\Embeddings;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Files\Image;
use Laravel\Ai\Files\Video;

$response = Embeddings::for([
    'A vineyard at sunset.',
    Image::fromStorage('vineyard.jpg'),
    Video::fromPath('/home/laravel/tour.mp4'),
])->generate(Lab::Gemini);

Per gli input multimodali si usano le stesse classi di file degli allegati. Queste possono essere create da path locali, dischi filesystem, URL remote o contenuti Base64. Immagini, documenti e video possono essere creati anche da file caricati, e i documenti anche da contenuti stringa raw.

use Laravel\Ai\Files\Audio;
use Laravel\Ai\Files\Document;
use Laravel\Ai\Files\Image;
use Laravel\Ai\Files\Video;

Image::fromPath('/home/laravel/photo.jpg');
Image::fromStorage('photo.jpg');
Image::fromUpload($request->file('photo'));

Audio::fromPath('/home/laravel/clip.mp3');
Audio::fromStorage('clip.mp3');
Audio::fromUpload($request->file('clip.mp3'));

Video::fromPath('/home/laravel/video.mp4');
Video::fromStorage('video.mp4');
Video::fromUpload($request->file('video'));

Document::fromUrl('https://example.com/report.pdf');
Document::fromString('Laravel is a PHP framework.', 'text/plain');
Document::fromUpload($request->file('report'));

VoyageAI non consente di mescolare in una stessa richiesta media da URL remoto e media Base64. File locali, dallo storage e caricati vengono inviati come contenuto Base64; l’input testuale può essere combinato con entrambe le sorgenti media. Consulta la documentazione dei singoli provider per i modelli multimodali disponibili e i tipi di input supportati.

Ricerca vettoriale (pgvector)

Esempio di configurazione per la ricerca vettoriale con PostgreSQL e l’estensione pgvector.

Creazione della migrazione

Schema::ensureVectorExtensionExists();

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->vector('embedding', dimensions: 1536);
    $table->timestamps();
});

// aggiunge un indice HNSW
$table->vector('embedding', dimensions: 1536)->index();

Configurazione del modello

protected function casts(): array
{
    return ['embedding' => 'array'];
}

Query per similarità

// ricerca tramite vettore di embedding
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();

// passando una stringa genera automaticamente l'embedding
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();

Sono disponibili anche metodi di più basso livello.

$documents = Document::query()
    ->select('*')
    ->selectVectorDistance('embedding', $queryEmbedding, as: 'distance')
    ->whereVectorDistanceLessThan('embedding', $queryEmbedding, maxDistance: 0.3)
    ->orderByVectorDistance('embedding', $queryEmbedding)
    ->limit(10)
    ->get();

Cache degli embedding

Puoi mettere in cache gli embedding per evitare di rigenerare quello dello stesso testo. Imposta la cache di default in config/ai.php.

'caching' => [
    'embeddings' => [
        'cache' => true,
        'store' => env('CACHE_STORE', 'database'),
    ],
],

Puoi anche controllare la cache per singola richiesta.

$response = Embeddings::for(['Napa Valley has great wine.'])->cache()->generate();
$response = Embeddings::for(['Napa Valley has great wine.'])->cache(seconds: 3600)->generate();

// stessa cosa con Stringable
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings(cache: true);
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings(cache: 3600);

Reranking

Puoi ri-ordinare (rerank) i risultati di una ricerca in base alla rilevanza rispetto alla query. Supportato da Cohere e Jina.

use Laravel\Ai\Reranking;

$response = Reranking::of([
    'Django is a Python web framework.',
    'Laravel is a PHP web application framework.',
    'React is a JavaScript library for building user interfaces.',
])->rerank('PHP frameworks');

$response->first()->document; // "Laravel is a PHP web application framework."
$response->first()->score;    // 0.95
$response->first()->index;    // 1

Con limit() puoi restringere il numero di risultati.

$response = Reranking::of($documents)->limit(5)->rerank('search query');

Reranking di collection

Puoi rerankare direttamente collection Eloquent.

// campo singolo
$posts = Post::all()->rerank('body', 'Laravel tutorials');

// più campi (inviati come JSON)
$reranked = $posts->rerank(['title', 'body'], 'Laravel tutorials');

// generazione del testo personalizzata tramite closure
$reranked = $posts->rerank(fn ($post) => $post->title.': '.$post->body, 'Laravel tutorials');

// con opzioni
$reranked = $posts->rerank(
    by: 'content',
    query: 'Laravel tutorials',
    limit: 10,
    provider: Lab::Cohere,
);

Gestione dei file

Puoi caricare file sul provider AI e riferirti a essi in seguito.

use Laravel\Ai\Files\Document;
use Laravel\Ai\Files\Image;

// da path
$response = Document::fromPath('/home/laravel/document.pdf')->put();
$response = Image::fromPath('/home/laravel/photo.jpg')->put();

// dallo storage
$response = Document::fromStorage('document.pdf', disk: 'local')->put();
$response = Image::fromStorage('photo.jpg', disk: 'local')->put();

// da URL
$response = Document::fromUrl('https://example.com/document.pdf')->put();
$response = Image::fromUrl('https://example.com/photo.jpg')->put();

return $response->id;

Puoi gestire anche stringhe e upload da form.

$stored = Document::fromString('Hello, World!', 'text/plain')->put();
$stored = Document::fromUpload($request->file('document'))->put();

Riferimento a file salvati

Puoi allegare all’agente file già caricati usando il loro ID.

use Laravel\Ai\Files;

$response = (new SalesCoach)->prompt(
    'Analyze the attached sales transcript...',
    attachments: [Files\Document::fromId('file-id')]
);

Recupero e cancellazione file

// recupero
$file = Document::fromId('file-id')->get();
$file->id;
$file->mimeType();

// cancellazione
Document::fromId('file-id')->delete();

Specificare il provider

$response = Document::fromPath('/home/laravel/document.pdf')->put(provider: Lab::Anthropic);

Specificare opzioni proprie del provider

Con il metodo withProviderOptions puoi passare opzioni di upload specifiche del provider. Ad esempio puoi impostare il purpose del file di OpenAI.

use Laravel\Ai\Files\Document;

$response = Document::fromPath('/home/laravel/knowledge.txt')
    ->withProviderOptions(['purpose' => 'assistants'])
    ->put();

Per differenziare le opzioni per provider, passa una closure.

use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Files\Document;

$response = Document::fromPath('/home/laravel/training.jsonl')
    ->withProviderOptions(fn (Lab|string $provider) => match ($provider) {
        Lab::OpenAI => ['purpose' => 'fine-tune'],
        default => [],
    })
    ->put();

Vector store

I vector store ti permettono di far gestire i documenti dal provider.

use Laravel\Ai\Stores;

// creazione
$store = Stores::create('Knowledge Base');
$store = Stores::create(
    name: 'Knowledge Base',
    description: 'Documentation.',
    expiresWhenIdleFor: days(30),
);
return $store->id;

// recupero
$store = Stores::get('store_id');
$store->id;
$store->name;
$store->fileCounts;
$store->ready;

// cancellazione
Stores::delete('store_id');
$store->delete();

Aggiungere file allo store

$store = Stores::get('store_id');

// aggiungi file in vari modi
$document = $store->add('file_id');
$document = $store->add(Document::fromId('file_id'));
$document = $store->add(Document::fromPath('/path/to/document.pdf'));
$document = $store->add(Document::fromStorage('manual.pdf'));
$document = $store->add($request->file('document'));

$document->id;
$document->fileId;

Puoi anche allegare metadata.

$store->add(
    Document::fromPath('/path/to/document.pdf'),
    metadata: [
        'author' => 'Taylor Otwell',
        'department' => 'Engineering',
        'year' => 2026,
    ]
);

Rimuovere file dallo store

$store->remove('file_id');

// per cancellare anche il file
$store->remove('file_abc123', deleteFile: true);

Failover

Specificando un array di provider, se il primo fallisce si passa automaticamente al successivo.

use App\Ai\Agents\SalesCoach;
use Laravel\Ai\Image;

// failover per l'agente
$response = (new SalesCoach)->prompt(
    'Analyze this sales transcript...',
    provider: [Lab::OpenAI, Lab::Anthropic],
);

// failover per la generazione di immagini
$image = Image::of('A donut sitting on the kitchen counter')
    ->generate(provider: [Lab::Gemini, Lab::xAI]);

Test

Laravel AI SDK offre funzionalità di fake per i test, permettendoti di testare senza chiamare realmente le API.

Test degli agenti

use App\Ai\Agents\SalesCoach;
use Laravel\Ai\Prompts\AgentPrompt;

// fake con risposte fisse
SalesCoach::fake();
SalesCoach::fake(['First response', 'Second response']);

// risposte dinamiche con closure
SalesCoach::fake(function (AgentPrompt $prompt) {
    return 'Response for: '.$prompt->prompt;
});

// asserzioni
SalesCoach::assertPrompted('Analyze this...');
SalesCoach::assertPrompted(function (AgentPrompt $prompt) {
    return $prompt->contains('Analyze');
});
SalesCoach::assertNotPrompted('Missing prompt');
SalesCoach::assertNeverPrompted();

Sono disponibili anche asserzioni per l’accodamento.

use Laravel\Ai\QueuedAgentPrompt;

SalesCoach::assertQueued('Analyze this...');
SalesCoach::assertQueued(function (QueuedAgentPrompt $prompt) {
    return $prompt->contains('Analyze');
});
SalesCoach::assertNotQueued('Missing prompt');
SalesCoach::assertNeverQueued();

Con preventStrayPrompts() viene lanciata un’eccezione se viene chiamato un prompt non definito nella fake.

SalesCoach::fake()->preventStrayPrompts();

Per fingere agenti con output strutturato puoi specificare la risposta come array. L’agente restituirà una risposta strutturata contenente i dati indicati.

SalesCoach::fake([
    ['score' => 87],
]);

Se fake() viene chiamato su un agente con output strutturato senza passare esplicitamente i dati fake, Laravel genera automaticamente dati fake conformi allo schema definito dall’agente.

Per testare gli agenti anonimi usa AnonymousAgent::fake().

use Laravel\Ai\AnonymousAgent;

AnonymousAgent::fake(['Test response']);

Test della generazione di immagini

use Laravel\Ai\Image;
use Laravel\Ai\Prompts\ImagePrompt;

Image::fake();
Image::fake([base64_encode($firstImage), base64_encode($secondImage)]);
Image::fake(function (ImagePrompt $prompt) {
    return base64_encode('...');
});

Image::assertGenerated(function (ImagePrompt $prompt) {
    return $prompt->contains('sunset') && $prompt->isLandscape();
});
Image::assertNotGenerated('Missing prompt');
Image::assertNothingGenerated();

Image::assertQueued(fn (QueuedImagePrompt $prompt) => $prompt->contains('sunset'));
Image::assertNotQueued('Missing prompt');
Image::assertNothingQueued();

Image::fake()->preventStrayImages();

Test della sintesi vocale

use Laravel\Ai\Audio;
use Laravel\Ai\Prompts\AudioPrompt;

Audio::fake();
Audio::fake([base64_encode($firstAudio), base64_encode($secondAudio)]);
Audio::fake(function (AudioPrompt $prompt) {
    return base64_encode('...');
});

Audio::assertGenerated(function (AudioPrompt $prompt) {
    return $prompt->contains('Hello') && $prompt->isFemale();
});
Audio::assertNotGenerated('Missing prompt');
Audio::assertNothingGenerated();

Audio::assertQueued(fn (QueuedAudioPrompt $prompt) => $prompt->contains('Hello'));
Audio::assertNotQueued('Missing prompt');
Audio::assertNothingQueued();

Audio::fake()->preventStrayAudio();

Test delle trascrizioni

use Laravel\Ai\Transcription;
use Laravel\Ai\Prompts\TranscriptionPrompt;

Transcription::fake();
Transcription::fake(['First transcription text.', 'Second transcription text.']);
Transcription::fake(function (TranscriptionPrompt $prompt) {
    return 'Transcribed text...';
});

Transcription::assertGenerated(function (TranscriptionPrompt $prompt) {
    return $prompt->language === 'en' && $prompt->isDiarized();
});
Transcription::assertNotGenerated(fn (TranscriptionPrompt $prompt) => $prompt->language === 'fr');
Transcription::assertNothingGenerated();

Transcription::assertQueued(fn (QueuedTranscriptionPrompt $prompt) => $prompt->isDiarized());
Transcription::assertNotQueued(fn (QueuedTranscriptionPrompt $prompt) => $prompt->language === 'fr');
Transcription::assertNothingQueued();

Transcription::fake()->preventStrayTranscriptions();

Test degli embedding

use Laravel\Ai\Embeddings;
use Laravel\Ai\Prompts\EmbeddingsPrompt;

Embeddings::fake();
Embeddings::fake([[$firstEmbeddingVector], [$secondEmbeddingVector]]);
Embeddings::fake(function (EmbeddingsPrompt $prompt) {
    return array_map(
        fn () => Embeddings::fakeEmbedding($prompt->dimensions),
        $prompt->inputs
    );
});

Embeddings::assertGenerated(function (EmbeddingsPrompt $prompt) {
    return $prompt->contains('Laravel') && $prompt->dimensions === 1536;
});
Embeddings::assertNotGenerated(fn (EmbeddingsPrompt $prompt) => $prompt->contains('Other'));
Embeddings::assertNothingGenerated();

Embeddings::assertQueued(fn (QueuedEmbeddingsPrompt $prompt) => $prompt->contains('Laravel'));
Embeddings::assertNotQueued(fn (QueuedEmbeddingsPrompt $prompt) => $prompt->contains('Other'));
Embeddings::assertNothingQueued();

Embeddings::fake()->preventStrayEmbeddings();

Test del reranking

use Laravel\Ai\Reranking;
use Laravel\Ai\Prompts\RerankingPrompt;
use Laravel\Ai\Responses\Data\RankedDocument;

Reranking::fake();
Reranking::fake([[
    new RankedDocument(index: 0, document: 'First', score: 0.95),
    new RankedDocument(index: 1, document: 'Second', score: 0.80),
]]);

Reranking::assertReranked(function (RerankingPrompt $prompt) {
    return $prompt->contains('Laravel') && $prompt->limit === 5;
});
Reranking::assertNotReranked(fn (RerankingPrompt $prompt) => $prompt->contains('Django'));
Reranking::assertNothingReranked();

Test dei file

use Laravel\Ai\Files;
use Laravel\Ai\Contracts\Files\StorableFile;
use Laravel\Ai\Files\Document;

Files::fake();

Document::fromString('Hello, Laravel!', mimeType: 'text/plain')->as('hello.txt')->put();

Files::assertStored(fn (StorableFile $file) =>
    (string) $file === 'Hello, Laravel!' && $file->mimeType() === 'text/plain'
);
Files::assertNotStored(fn (StorableFile $file) => (string) $file === 'Hello, World!');
Files::assertNothingStored();

Files::assertDeleted('file-id');
Files::assertNotDeleted('file-id');
Files::assertNothingDeleted();

Test dei vector store

use Laravel\Ai\Stores;

Stores::fake(); // anche le operazioni sui file vengono finte

$store = Stores::create('Knowledge Base');

Stores::assertCreated('Knowledge Base');
Stores::assertCreated(fn (string $name, ?string $description) => $name === 'Knowledge Base');
Stores::assertNotCreated('Other Store');
Stores::assertNothingCreated();

Stores::assertDeleted('store_id');
Stores::assertNotDeleted('other_store_id');
Stores::assertNothingDeleted();

Puoi anche fare asserzioni sulle operazioni file su uno store.

$store = Stores::get('store_id');
$store->add('added_id');
$store->remove('removed_id');

$store->assertAdded('added_id');
$store->assertRemoved('removed_id');
$store->assertNotAdded('other_file_id');
$store->assertNotRemoved('other_file_id');

// verifica del contenuto tramite closure
$store->add(Document::fromString('Hello, World!', 'text/plain')->as('hello.txt'));
$store->assertAdded(fn (StorableFile $file) => $file->name() === 'hello.txt');
$store->assertAdded(fn (StorableFile $file) => $file->content() === 'Hello, World!');

Eventi

Laravel AI SDK dispatcha i seguenti eventi. Ascoltandoli puoi implementare log, monitoring e altro.

Relativi agli agenti

PromptingAgent — prima dell’invio del prompt
AgentPrompted — dopo l’invio del prompt
StreamingAgent — all’inizio dello streaming
AgentStreamed — al termine dello streaming
InvokingTool — prima della chiamata di un tool
ToolInvoked — dopo la chiamata di un tool
ToolApprovalRequested — quando è richiesta l’approvazione di un tool
ToolApprovalResolved — dopo la risoluzione dell’approvazione del tool

Relativi a immagini, audio e trascrizioni

GeneratingImage — prima della generazione dell’immagine
ImageGenerated — dopo la generazione dell’immagine
GeneratingAudio — prima della generazione dell’audio
AudioGenerated — dopo la generazione dell’audio
GeneratingTranscription — prima della trascrizione
TranscriptionGenerated — dopo la trascrizione

Relativi a embedding e reranking

GeneratingEmbeddings — prima della generazione degli embedding
EmbeddingsGenerated — dopo la generazione degli embedding
Reranking — prima del reranking
Reranked — dopo il reranking

Relativi a file e store

StoringFile — prima del salvataggio del file
FileStored — dopo il salvataggio del file
FileDeleted — dopo la cancellazione del file
CreatingStore — prima della creazione dello store
StoreCreated — dopo la creazione dello store
AddingFileToStore — prima dell’aggiunta di un file allo store
FileAddedToStore — dopo l’aggiunta di un file allo store
RemovingFileFromStore — prima della rimozione di un file dallo store
FileRemovedFromStore — dopo la rimozione di un file dallo store

Ultima modifica il 2 agosto 2026

Argomenti correlati

Riepilogo delle novità di Laravel 13 Aggiornamenti Laravel di marzo 2026 Integrazione con Laravel AI SDK Integrazione con Laravel AI SDK - VOICEVOX for Laravel Driver Amazon Bedrock per Laravel AI SDK

Laravel MCP

Laravel Sail

​Introduzione

​Provider supportati

​Installazione

​Configurazione

​Variabili d’ambiente

​Base URL personalizzate

​Provider OpenAI-Compatible

​Enum Lab

​Agenti

​Prompt

​Contesto conversazionale

​Output strutturato

​Oggetti annidati

​Array di oggetti

​anyOf (scelta tra più schemi)

​Allegati

​Streaming

​Protocollo Vercel AI SDK

​Broadcasting

​Saltare eventi troppo grandi

​Code

​Tool

​Tool di ricerca per similarità

​Tool di storage file

​Tool MCP

​Tool del provider

​Ricerca web

​Recupero web

​Ricerca file

​Sub-agenti

​Middleware

​Agenti anonimi

​Configurazione dell’agente (attributi PHP)

​Opzioni del provider

​Approvazione umana (Human Tool Approval)

​Flusso completo di approvazione

​Generazione di immagini

​Salvataggio dell’immagine

​Generazione di immagini in coda

​Sintesi vocale (TTS)

​Salvataggio dell’audio

​Generazione dell’audio in coda

​Trascrizione (STT)

​Diarizzazione (separazione degli speaker)

​Trascrizione in coda

​Riassunto di testi (Text Summarization)

​Embedding

​Embedding multimodali

​Ricerca vettoriale (pgvector)

​Cache degli embedding

​Reranking

​Reranking di collection

​Gestione dei file

​Riferimento a file salvati

​Recupero e cancellazione file

​Specificare il provider

​Specificare opzioni proprie del provider

​Vector store

​Aggiungere file allo store

​Rimuovere file dallo store

​Failover

​Test

​Test degli agenti

​Test della generazione di immagini

​Test della sintesi vocale

​Test delle trascrizioni

​Test degli embedding

​Test del reranking

​Test dei file

​Test dei vector store

​Eventi

Introduzione

Provider supportati

Installazione

Configurazione

Variabili d’ambiente

Base URL personalizzate

Provider OpenAI-Compatible

Enum Lab

Agenti

Prompt

Contesto conversazionale

Output strutturato

Oggetti annidati

Array di oggetti

anyOf (scelta tra più schemi)

Allegati

Streaming

Protocollo Vercel AI SDK

Broadcasting

Saltare eventi troppo grandi

Code

Tool

Tool di ricerca per similarità

Tool di storage file

Tool MCP

Tool del provider

Ricerca web

Recupero web

Ricerca file

Sub-agenti

Middleware

Agenti anonimi

Configurazione dell’agente (attributi PHP)

Opzioni del provider

Approvazione umana (Human Tool Approval)

Flusso completo di approvazione

Generazione di immagini

Salvataggio dell’immagine

Generazione di immagini in coda

Sintesi vocale (TTS)

Salvataggio dell’audio

Generazione dell’audio in coda

Trascrizione (STT)

Diarizzazione (separazione degli speaker)

Trascrizione in coda

Riassunto di testi (Text Summarization)

Embedding

Embedding multimodali

Ricerca vettoriale (pgvector)

Cache degli embedding

Reranking

Reranking di collection

Gestione dei file

Riferimento a file salvati

Recupero e cancellazione file

Specificare il provider

Specificare opzioni proprie del provider

Vector store

Aggiungere file allo store

Rimuovere file dallo store

Failover

Test

Test degli agenti

Test della generazione di immagini

Test della sintesi vocale

Test delle trascrizioni

Test degli embedding

Test del reranking

Test dei file

Test dei vector store

Eventi