Laravel AI SDK - Knowledge of Laravel

Introduction

Le Laravel AI SDK fournit une API expressive et unifiée pour dialoguer avec des fournisseurs d’IA tels que OpenAI, Anthropic ou Gemini. Grâce à ce SDK, vous pouvez construire des agents intelligents munis d’outils et de sorties structurées, générer des images, synthétiser ou transcrire de l’audio, produire des embeddings vectoriels, etc. — le tout via une interface cohérente et fidèle à l’esprit de Laravel.

Le Laravel AI SDK est un package officiel introduit dans Laravel 13. Distribué sous le nom laravel/ai, il permet d’utiliser plusieurs fournisseurs d’IA via une API unique.

Fournisseurs pris en charge

Fonctionnalité	Fournisseurs compatibles
Génération de texte	OpenAI, OpenAI Compatible, Anthropic, Gemini, Azure, Bedrock, Groq, xAI, DeepSeek, Mistral, Ollama, OpenRouter
Génération d’images	OpenAI, Gemini, xAI, Azure, Bedrock, OpenRouter
Synthèse vocale (TTS)	OpenAI, ElevenLabs, Gemini
Reconnaissance vocale (STT)	OpenAI, ElevenLabs, Mistral, Gemini
Embeddings	OpenAI, Gemini, Azure, Bedrock, Cohere, Mistral, Jina, VoyageAI, Ollama, OpenRouter
Reranking	Cohere, Jina, VoyageAI
Fichiers	OpenAI, Anthropic, Gemini, Azure

Installation

Installer le package

Installez le Laravel AI SDK avec Composer.

composer require laravel/ai

Publier le fichier de configuration et les migrations

Publiez le fichier de configuration et les migrations à l’aide de la commande Artisan vendor:publish.

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

Exécuter les migrations

Exécutez les migrations de base de données. Les tables agent_conversations et agent_conversation_messages sont créées et serviront à stocker l’historique des conversations.

php artisan migrate

Configuration

Variables d’environnement

Renseignez dans votre fichier .env les clés API des fournisseurs d’IA que vous souhaitez utiliser.

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=

Les modèles par défaut utilisés pour le texte, les images, l’audio, la transcription ou les embeddings peuvent également être définis dans config/ai.php.

URL de base personnalisée

Si vous passez par un service proxy, vous pouvez définir une URL personnalisée pour chaque fournisseur.

'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'),
    ],
],

Une URL de base personnalisée est disponible pour OpenAI, Anthropic, Gemini, Groq, Cohere, DeepSeek, xAI et OpenRouter.

Fournisseur compatible OpenAI

Pour utiliser une API compatible OpenAI (LM Studio, vLLM, Together, Fireworks, une passerelle locale, etc.), configurez un fournisseur avec le driver openai-compatible. url est obligatoire, et key est envoyé sous forme de jeton Bearer lorsqu’il est fourni.

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

Une fois configuré, vous l’utilisez par son nom comme n’importe quel autre fournisseur.

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

En définissant un modèle texte par défaut, vous n’avez plus besoin de le préciser à chaque appel.

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

Le fournisseur OpenAI-Compatible prend en charge la génération de texte, le streaming, les outils, les sorties structurées et les images en pièce jointe. Si l’endpoint attend des champs supplémentaires dans le corps de la requête, utilisez les options de fournisseur.

Enum Lab

Pour référencer un fournisseur dans votre code, utilisez l’enum Lab.

use Laravel\Ai\Enums\Lab;

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

Agents

Les agents sont l’élément de base du Laravel AI SDK. La commande make:agent permet de générer une classe d’agent.

php artisan make:agent SalesCoach

# Génération d'un agent avec sortie structurée
php artisan make:agent SalesCoach --structured

Les agents générés sont placés dans le répertoire app/Ai/Agents/. Voici un exemple d’agent implémentant toutes les principales interfaces.

<?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

La méthode prompt() envoie un message à l’agent.

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

La méthode statique make() permet de résoudre les dépendances depuis le container et de créer l’instance.

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

Le fournisseur, le modèle et le timeout peuvent être surchargés via les arguments de prompt().

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

Contexte conversationnel

En implémentant l’interface Conversational et en définissant la méthode messages(), vous pouvez transmettre l’historique de la conversation à l’IA. Le trait RemembersConversations permet d’enregistrer et de récupérer automatiquement l’historique en base de données.

use Laravel\Ai\Concerns\RemembersConversations;

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

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

Vous démarrez la conversation avec forUser(), puis reprenez la suite avec continue() en utilisant l’conversationId renvoyé.

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

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

Sortie structurée

En implémentant l’interface HasStructuredOutput et en définissant un schéma JSON via la méthode schema(), vous obtenez la réponse de l’IA sous forme de données structurées.

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

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

Objets imbriqués

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(),
    ];
}

Tableau d’objets

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 (choix parmi plusieurs schémas)

Quand une valeur peut correspondre à l’un de plusieurs schémas, utilisez la méthode 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(),
    ];
}

Pièces jointes

L’argument attachments permet de transmettre des documents ou des images à l’agent.

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

Les images se joignent de la même manière.

$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

La méthode stream() renvoie la réponse par morceaux (chunks). C’est idéal pour envoyer en temps réel une réponse longue au frontend.

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

Le callback then() permet d’exécuter du code une fois le streaming terminé.

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...
        });
});

Vous pouvez également itérer manuellement sur le flux.

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

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

Protocole Vercel AI SDK

Si vous utilisez le SDK Vercel AI côté frontend, appelez usingVercelDataProtocol().

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

Broadcast

Vous pouvez pousser les événements d’un flux vers un canal de broadcast (Laravel Echo, par exemple).

use Illuminate\Broadcasting\Channel;

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

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

broadcastOnQueue() permet de broadcaster via une file d’attente.

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

Ignorer les événements trop volumineux

Certaines plateformes de broadcast limitent la taille des messages WebSocket à environ 10 Ko. Les événements de streaming volumineux, comme les résultats d’outils, peuvent dépasser cette limite et échouer au broadcast. L’attribut WithoutBroadcasting permet d’exclure certains types d’événements du broadcast.

<?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;

    // ...
}

Les événements exclus ne sont pas broadcastés, mais restent enregistrés dans la table agent_conversation_messages. Le frontend peut donc récupérer toutes les données des outils une fois le flux terminé. Cela fonctionne aussi bien via une queue (broadcastOnQueue) qu’en synchrone (broadcast / broadcastNow).

Queue

La méthode queue() met le prompt en file d’attente pour un traitement asynchrone.

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();
});

Outils

Les outils permettent à l’IA d’appeler des fonctions de votre code. Vous générez une classe d’outil avec 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(),
        ];
    }
}

Vous enregistrez les outils dans la méthode tools() de l’agent.

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

Outil de recherche par similarité

Vous pouvez ajouter facilement un outil de recherche par similarité basé sur des embeddings vectoriels.

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

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

Vous pouvez également passer des options.

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

Une closure permet de définir votre propre logique de recherche.

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

withDescription() permet de personnaliser la description de l’outil.

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

Outils de stockage de fichiers

La fabrique d’outils FileStorage permet de donner à l’agent l’accès aux disques de système de fichiers de Laravel. La méthode all retourne un ensemble complet d’outils pour lister, lire, générer des URL, écrire, supprimer et copier des fichiers sur le disque spécifié.

use Laravel\Ai\Tools\FileStorage;

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

Utilisez readOnly pour ne donner qu’un accès en lecture seule.

return FileStorage::readOnly('local');

Ces méthodes retournent une Illuminate\Support\Collection, ce qui vous permet de filtrer les outils exposés.

use Laravel\Ai\Tools\Filesystem\DeleteFile;

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

Outils MCP

Si vous utilisez Laravel MCP dans votre application, vous pouvez exposer à l’agent les outils publiés par un serveur Model Context Protocol. Le client MCP de Laravel permet de se connecter à un serveur MCP distant ou local et de transmettre ses outils directement à l’agent.

Pour utiliser des outils MCP, le package Laravel MCP doit être installé dans l’application.

La méthode tools du client MCP renvoie une collection : utilisez l’opérateur de spread ... pour l’insérer dans le tableau tools de l’agent.

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 enveloppe automatiquement chaque outil MCP pour que l’agent puisse l’appeler comme n’importe quel autre outil. Vous pouvez aussi utiliser un client MCP nommé.

use Laravel\Mcp\Facades\Mcp;

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

Il est également possible de se connecter à un serveur MCP local.

use Laravel\Mcp\Client;

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

Pour la création du client MCP et l’authentification (jeton Bearer, OAuth…), reportez-vous à la documentation du client MCP.

Outils du fournisseur

Il s’agit d’outils spéciaux implémentés nativement par les fournisseurs d’IA.

Recherche web

Ajoute une recherche web à l’agent. Compatible avec Anthropic, OpenAI, Gemini et OpenRouter.

use Laravel\Ai\Providers\Tools\WebSearch;

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

Vous pouvez limiter le nombre de résultats, restreindre les domaines ou préciser une localisation.

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

Récupération de contenu web

Outil pour récupérer le contenu d’une URL donnée. Compatible avec Anthropic et Gemini.

use Laravel\Ai\Providers\Tools\WebFetch;

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

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

Recherche de fichiers

Outil qui recherche des documents dans un vector store. Compatible avec OpenAI et Gemini.

use Laravel\Ai\Providers\Tools\FileSearch;

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

// Plusieurs stores
new FileSearch(stores: ['store_1', 'store_2']);

// Filtrage par métadonnées
new FileSearch(stores: ['store_id'], where: ['author' => 'Taylor Otwell', 'year' => 2026]);

Vous pouvez aussi construire des filtres complexes avec 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'])
);

Sous-agents

Un agent peut également être renvoyé depuis la méthode tools() d’un autre agent. En enregistrant un agent comme outil, l’agent parent peut déléguer certaines tâches à un sous-agent et intégrer le résultat à sa propre réponse. C’est utile lorsqu’un agent généraliste doit accéder à un agent spécialisé disposant d’instructions, d’outils, d’un modèle ou d’une configuration de fournisseur dédiés. Par exemple, un agent de support client peut déléguer les questions sur la politique de remboursement à un agent spécialisé.

<?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,
        ];
    }
}

Pour personnaliser la manière dont le sous-agent est exposé à son parent, faites-lui implémenter l’interface CanActAsTool et définissez son nom et sa description en tant qu’outil.

<?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,
        ];
    }
}

Si le sous-agent n’implémente pas CanActAsTool, Laravel utilise le nom de la classe comme nom d’outil et génère automatiquement une description générique. Chaque appel à un sous-agent est indépendant : l’historique de conversation de l’agent parent n’est pas transmis.

Middleware

Vous pouvez ajouter des middlewares à un agent pour intercepter les prompts ou les réponses.

php artisan make:agent-middleware LogPrompts

Faites implémenter à l’agent l’interface HasMiddleware et déclarez les middlewares via 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];
    }
}

Voici un exemple d’implémentation d’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);
    }
}

Le callback then() permet d’exécuter du code après la réponse.

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

Agents anonymes

Sans définir de classe, vous pouvez utiliser un agent anonyme via le helper agent().

use function Laravel\Ai\{agent};

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

Il est aussi possible de créer un agent anonyme avec sortie structurée.

use Illuminate\Contracts\JsonSchema\JsonSchema;

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

Configuration d’un agent (attributs PHP)

Vous pouvez déclarer les paramètres par défaut d’un agent à l’aide d’attributs PHP.

Attribut	Description
`#[Provider]`	Fournisseur à utiliser
`#[Model]`	Modèle à utiliser
`#[MaxSteps]`	Nombre maximum d’étapes pour les appels d’outils
`#[MaxTokens]`	Nombre maximum de tokens
`#[Temperature]`	Paramètre de température (0.0 à 1.0)
`#[TopP]`	Probabilité de l’échantillonnage nucléaire (0.0 à 1.0)
`#[Timeout]`	Timeout (en secondes)
`#[UseCheapestModel]`	Sélectionner automatiquement le modèle le moins cher
`#[UseSmartestModel]`	Sélectionner automatiquement le modèle le plus performant

<?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;
}

Des raccourcis d’attributs pour la sélection du modèle sont également disponibles.

// Utiliser le modèle le moins cher
#[UseCheapestModel]
class SimpleSummarizer implements Agent
{
    use Promptable;
}

// Utiliser le modèle le plus performant
#[UseSmartestModel]
class ComplexReasoner implements Agent
{
    use Promptable;
}

Options de fournisseur

Implémentez l’interface HasProviderOptions pour passer des options propres à un fournisseur.

<?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 => [],
        };
    }
}

Approbation humaine (Human Tool Approval)

Pour utiliser l’approbation d’outils, vous devez avoir un agent Conversational dont l’historique de conversation est persisté. Le trait RemembersConversations fournit la persistance nécessaire pour reprendre les appels suspendus.

Pour les outils sensibles ou irréversibles (suppression de fichier, virement…), vous pouvez exiger une approbation humaine avant leur exécution. Rendez l’outil approuvable en implémentant le contrat Approvable et en utilisant le trait InteractsWithApprovals. Par défaut, un outil approuvable nécessite systématiquement une approbation.

<?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;

    /**
     * Description du but de l'outil.
     */
    public function description(): Stringable|string
    {
        return 'Supprimer un fichier du stockage.';
    }

    /**
     * Exécute l'outil.
     */
    public function handle(Request $request): Stringable|string
    {
        Storage::delete($request['path']);

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

    /**
     * Retourne la définition du schéma de l'outil.
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'path' => $schema->string()->required(),
        ];
    }
}

Pour décider dynamiquement si une approbation est nécessaire selon les arguments de l’appel, définissez une méthode needsApproval sur l’outil. Elle peut renvoyer un booléen ou une instance Approval contenant la raison de l’approbation.

use Laravel\Ai\Approvals\Approval;

/**
 * Détermine si l'outil nécessite une approbation pour la requête donnée.
 */
protected function needsApproval(Request $request): Approval|bool
{
    return str_starts_with($request['path'], 'temporary/')
        ? false
        : Approval::required('Ce fichier sera définitivement supprimé.');
}

Lorsque vous renvoyez les outils depuis la méthode tools de l’agent, vous pouvez également surcharger l’exigence d’approbation.

public function tools(): iterable
{
    return [
        (new SendNotification)->withoutApproval(),
        (new DeleteFile)->requireApproval('La suppression demande une confirmation.'),
    ];
}

Lorsqu’un outil approuvable est appelé, l’agent est mis en pause avant l’exécution. En inspectant pendingApprovals sur la réponse, vous obtenez l’ID de l’appel, le nom de l’outil, les arguments et la raison de l’approbation.

$response = (new FileAssistant)
    ->forUser($user)
    ->prompt('Supprime les anciennes factures.');

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

Pour reprendre l’agent, continuez la conversation en passant une instance Decisions contenant la décision pour chaque appel d’outil en attente. Les décisions permettent d’approuver, de rejeter ou de modifier les arguments avant exécution.

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('Cette facture doit être conservée.'),
    ]));

Les booléens true et false sont respectivement des raccourcis pour approuver ou rejeter. Chaque appel d’outil en attente doit avoir une décision. Un ID d’appel inconnu, manquant ou déjà résolu lève une ApprovalMismatchException. Pour les appels dépourvus de décision explicite, les méthodes approveRemaining ou rejectRemaining définissent une décision par défaut.

$decisions = Decisions::from([
    'call_abc' => true,
])->rejectRemaining('Approbation refusée.');

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

Rejeter avec un résultat comme Decision::reject('Approbation refusée.') renvoie ce résultat au modèle, qui poursuit sa réponse. Rejeter sans résultat arrête la boucle de génération à l’endroit où le rejet est enregistré. L’approbation d’outils est prise en charge par les méthodes prompt, stream, queue, broadcast, broadcastNow et broadcastOnQueue. Pendant le streaming et le broadcast, la pause est exprimée sous la forme d’un événement tool_approval_request. Si vous utilisez le protocole de flux Vercel AI SDK, les demandes et résultats d’approbation sont émis en tant que parties natives d’approbation d’outil du protocole. Pour les agents en file d’attente, la réponse finale est transmise au callback then, et Laravel émet également un événement ToolApprovalRequested. Laravel enregistre les résultats des outils approuvés avant de redemander au modèle de poursuivre. Si la génération échoue par la suite, les approbations sont déjà résolues. Plutôt que de renvoyer les mêmes décisions, poursuivez la conversation avec un prompt texte classique.

Un flux d’approbation complet

Les routes ci-dessous illustrent un flux d’approbation complet. La route GET retourne l’écran de chat, la route POST accepte soit un nouveau prompt texte depuis l’écran de chat, soit des décisions d’approbation. Cet exemple suppose que le modèle User de l’application utilise le 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');

Si le statut de la réponse vaut awaiting_approval, l’écran de chat doit afficher les approbations en attente et envoyer à ce même endpoint le choix de l’utilisateur, indexé par l’ID d’appel de l’outil.

{
    "decisions": {
        "call_abc": {
            "action": "approve"
        },
        "call_def": {
            "action": "reject",
            "result": "Cette facture doit être conservée."
        }
    }
}

Pour un message de chat classique, envoyez plutôt la valeur message.

{
    "message": "Supprime les anciennes factures."
}

Le flux d’approbation permet de donner à un agent d’IA de puissantes capacités d’action, tout en intercalant une vérification humaine avant l’exécution. Utilisez-le sans hésiter pour les outils impliquant des opérations irréversibles : suppression de fichier, traitement de paiement, écriture vers une API externe, etc.

Génération d’images

La classe Image permet de générer des images. Les fournisseurs OpenAI, Gemini et xAI sont pris en charge.

use Laravel\Ai\Image;

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

Vous pouvez préciser la qualité, le ratio ou un timeout.

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

Il est également possible de joindre une image de référence pour la retoucher.

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

Enregistrement des images

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

Génération d’image via une queue

use Laravel\Ai\Responses\ImageResponse;

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

Synthèse vocale (TTS)

La classe Audio permet de convertir du texte en audio. Les fournisseurs OpenAI et ElevenLabs sont pris en charge.

use Laravel\Ai\Audio;

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

Vous pouvez préciser le genre de la voix, un identifiant de voix spécifique ou des instructions de diction.

$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();

Enregistrement de l’audio

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

Génération audio via une queue

use Laravel\Ai\Responses\AudioResponse;

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

Transcription (STT)

La classe Transcription permet de convertir un fichier audio en texte. Les fournisseurs OpenAI, ElevenLabs et Mistral sont pris en charge.

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;

Séparation des intervenants (diarization)

Utilisez diarize() pour obtenir une transcription séparée par intervenant.

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

Transcription via une queue

use Laravel\Ai\Responses\TranscriptionResponse;

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

Résumé de texte (Text Summarization)

La méthode summarize de la classe Stringable de Laravel permet de résumer un texte. Par défaut, le résumé fait au maximum trois phrases et utilise le modèle texte le moins cher du fournisseur configuré.

use Illuminate\Support\Str;

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

Vous pouvez préciser le nombre maximal de phrases, le fournisseur, le modèle ou un timeout. La classe Str propose également une version statique.

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

Embeddings

Convertissez du texte en représentation vectorielle pour la recherche par similarité, entre autres.

use Illuminate\Support\Str;

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

use Laravel\Ai\Embeddings;

// Plusieurs textes en une seule requête
$response = Embeddings::for(['Napa Valley has great wine.', 'Laravel is a PHP framework.'])->generate();
$response->embeddings; // [[0.123, 0.456, ...], [0.789, 0.012, ...]]

Vous pouvez également préciser le fournisseur, le modèle et la dimension.

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

Embeddings multimodaux

La méthode Embeddings::for accepte non seulement des chaînes de caractères mais aussi des images, de l’audio, des documents ou des vidéos : vous pouvez donc générer des embeddings pour des contenus non textuels. Gemini prend en charge les embeddings d’images, d’audio, de documents et de vidéos ; VoyageAI prend en charge les embeddings d’images et de vidéos.

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

Pour les entrées multimodales, utilisez les mêmes classes de fichiers que pour les pièces jointes. Ces fichiers peuvent être créés depuis un chemin local, un disque de système de fichiers, une URL distante ou un contenu encodé en Base64. Les images, documents et vidéos peuvent aussi être créés depuis un fichier uploadé, et les documents peuvent également être créés depuis une chaîne de caractères brute.

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 n’autorise pas le mélange de médias distants (URL) et de médias encodés en Base64 dans une même requête. Les fichiers locaux, ceux du storage et les fichiers uploadés sont envoyés en Base64. Les entrées texte peuvent être combinées à l’une ou l’autre source. Consultez la documentation de chaque fournisseur pour connaître les modèles et types d’entrées multimodales disponibles.

Recherche vectorielle (pgvector)

Voici un exemple de configuration de recherche vectorielle avec PostgreSQL et l’extension pgvector.

Création de la migration

Schema::ensureVectorExtensionExists();

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

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

Configuration du modèle

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

Requête de recherche par similarité

// Recherche par vecteur d'embedding
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();

// Génère automatiquement l'embedding si vous passez une chaîne
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();

Des méthodes de bas niveau sont également disponibles.

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

Cache des embeddings

Vous pouvez éviter de régénérer les embeddings pour un même texte grâce au cache. Définissez le comportement par défaut dans config/ai.php.

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

Vous pouvez aussi contrôler le cache requête par requête.

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

// Fonctionne également avec Stringable
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings(cache: true);
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings(cache: 3600);

Reranking

Réordonnez des résultats de recherche selon leur pertinence par rapport à une requête. Les fournisseurs Cohere et Jina sont pris en charge.

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

limit() permet de restreindre le nombre de résultats renvoyés.

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

Reranking de collections

Vous pouvez réordonner directement une collection Eloquent.

// Un seul champ
$posts = Post::all()->rerank('body', 'Laravel tutorials');

// Plusieurs champs (envoyés en JSON)
$reranked = $posts->rerank(['title', 'body'], 'Laravel tutorials');

// Génération du texte via une closure
$reranked = $posts->rerank(fn ($post) => $post->title.': '.$post->body, 'Laravel tutorials');

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

Gestion des fichiers

Vous pouvez téléverser des fichiers auprès des fournisseurs d’IA pour les référencer plus tard.

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

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

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

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

return $response->id;

On peut aussi les créer depuis une chaîne ou un upload de formulaire.

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

Référencer un fichier déjà téléversé

Attachez à l’agent un fichier existant via son ID.

use Laravel\Ai\Files;

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

Récupérer et supprimer un fichier

// Récupération
$file = Document::fromId('file-id')->get();
$file->id;
$file->mimeType();

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

Choix du fournisseur

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

Options spécifiques au fournisseur

La méthode withProviderOptions permet de passer des options d’upload propres au fournisseur, comme le purpose d’un fichier chez OpenAI.

use Laravel\Ai\Files\Document;

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

Pour définir des options différentes selon le fournisseur, passez une 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 stores

Les vector stores permettent de laisser les fournisseurs gérer les documents pour vous.

use Laravel\Ai\Stores;

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

// Récupération
$store = Stores::get('store_id');
$store->id;
$store->name;
$store->fileCounts;
$store->ready;

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

Ajouter des fichiers à un store

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

// Plusieurs manières d'ajouter un fichier
$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;

Vous pouvez aussi joindre des métadonnées.

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

Retirer un fichier d’un store

$store->remove('file_id');

// Pour supprimer aussi le fichier lui-même
$store->remove('file_abc123', deleteFile: true);

Failover

En passant un tableau de fournisseurs, on bascule automatiquement sur le suivant si le premier échoue.

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

// Failover sur agent
$response = (new SalesCoach)->prompt(
    'Analyze this sales transcript...',
    provider: [Lab::OpenAI, Lab::Anthropic],
);

// Failover sur génération d'image
$image = Image::of('A donut sitting on the kitchen counter')
    ->generate(provider: [Lab::Gemini, Lab::xAI]);

Tests

Le Laravel AI SDK fournit des fakes pour tester sans appeler véritablement les API.

Tester un agent

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

// Fake avec réponses fixes
SalesCoach::fake();
SalesCoach::fake(['First response', 'Second response']);

// Réponse dynamique via une closure
SalesCoach::fake(function (AgentPrompt $prompt) {
    return 'Response for: '.$prompt->prompt;
});

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

Des assertions pour la mise en queue sont également disponibles.

use Laravel\Ai\QueuedAgentPrompt;

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

preventStrayPrompts() fait remonter une exception si un prompt non défini par le fake est déclenché.

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

Pour un agent qui renvoie une sortie structurée, vous pouvez indiquer la réponse sous forme de tableau : l’agent renverra une réponse structurée contenant les données spécifiées.

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

Si fake() est appelé sur un agent à sortie structurée sans données explicites, Laravel génère automatiquement des données factices conformes au schéma défini par l’agent.

Pour tester un agent anonyme, utilisez AnonymousAgent::fake().

use Laravel\Ai\AnonymousAgent;

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

Tester la génération d’images

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

Tester la synthèse 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();

Tester la transcription

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

Tester les embeddings

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

Tester le 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();

Tester les fichiers

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

Tester les vector stores

use Laravel\Ai\Stores;

Stores::fake(); // Fake également les opérations sur les fichiers

$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();

Vous pouvez également faire des assertions sur les opérations effectuées sur un 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');

// Validation du contenu via une 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!');

Événements

Le Laravel AI SDK émet les événements suivants. En les écoutant, vous pouvez implémenter du logging, du monitoring, etc.

Événements liés aux agents

PromptingAgent — avant l’envoi du prompt
AgentPrompted — après l’envoi du prompt
StreamingAgent — au démarrage du streaming
AgentStreamed — à la fin du streaming
InvokingTool — avant l’appel d’un outil
ToolInvoked — après l’appel d’un outil
ToolApprovalRequested — lors d’une demande d’approbation d’outil
ToolApprovalResolved — après résolution de l’approbation d’outil

Images, audio, transcription

GeneratingImage — avant la génération d’image
ImageGenerated — après la génération d’image
GeneratingAudio — avant la génération audio
AudioGenerated — après la génération audio
GeneratingTranscription — avant la transcription
TranscriptionGenerated — après la transcription

Embeddings et reranking

GeneratingEmbeddings — avant la génération d’embeddings
EmbeddingsGenerated — après la génération d’embeddings
Reranking — avant le reranking
Reranked — après le reranking

Fichiers et stores

StoringFile — avant le stockage du fichier
FileStored — après le stockage du fichier
FileDeleted — après la suppression du fichier
CreatingStore — avant la création du store
StoreCreated — après la création du store
AddingFileToStore — avant l’ajout d’un fichier à un store
FileAddedToStore — après l’ajout d’un fichier à un store
RemovingFileFromStore — avant le retrait d’un fichier d’un store
FileRemovedFromStore — après le retrait d’un fichier d’un store

Dernière modification le 2 août 2026

Sujets connexes

Les nouveautés de Laravel 13 Mises à jour Laravel — mars 2026 Intégration Laravel AI SDK Intégration Laravel AI SDK - VOICEVOX for Laravel Pilote Amazon Bedrock pour Laravel AI SDK

Laravel MCP

Laravel Sail

​Introduction

​Fournisseurs pris en charge

​Installation

​Configuration

​Variables d’environnement

​URL de base personnalisée

​Fournisseur compatible OpenAI

​Enum Lab

​Agents

​Prompt

​Contexte conversationnel

​Sortie structurée

​Objets imbriqués

​Tableau d’objets

​anyOf (choix parmi plusieurs schémas)

​Pièces jointes

​Streaming

​Protocole Vercel AI SDK

​Broadcast

​Ignorer les événements trop volumineux

​Queue

​Outils

​Outil de recherche par similarité

​Outils de stockage de fichiers

​Outils MCP

​Outils du fournisseur

​Recherche web

​Récupération de contenu web

​Recherche de fichiers

​Sous-agents

​Middleware

​Agents anonymes

​Configuration d’un agent (attributs PHP)

​Options de fournisseur

​Approbation humaine (Human Tool Approval)

​Un flux d’approbation complet

​Génération d’images

​Enregistrement des images

​Génération d’image via une queue

​Synthèse vocale (TTS)

​Enregistrement de l’audio

​Génération audio via une queue

​Transcription (STT)

​Séparation des intervenants (diarization)

​Transcription via une queue

​Résumé de texte (Text Summarization)

​Embeddings

​Embeddings multimodaux

​Recherche vectorielle (pgvector)

​Cache des embeddings

​Reranking

​Reranking de collections

​Gestion des fichiers

​Référencer un fichier déjà téléversé

​Récupérer et supprimer un fichier

​Choix du fournisseur

​Options spécifiques au fournisseur

​Vector stores

​Ajouter des fichiers à un store

​Retirer un fichier d’un store

​Failover

​Tests

​Tester un agent

​Tester la génération d’images

​Tester la synthèse vocale

​Tester la transcription

​Tester les embeddings

​Tester le reranking

​Tester les fichiers

​Tester les vector stores

​Événements

Introduction

Fournisseurs pris en charge

Installation

Configuration

Variables d’environnement

URL de base personnalisée

Fournisseur compatible OpenAI

Enum Lab

Agents

Prompt

Contexte conversationnel

Sortie structurée

Objets imbriqués

Tableau d’objets

anyOf (choix parmi plusieurs schémas)

Pièces jointes

Streaming

Protocole Vercel AI SDK

Broadcast

Ignorer les événements trop volumineux

Queue

Outils

Outil de recherche par similarité

Outils de stockage de fichiers

Outils MCP

Outils du fournisseur

Recherche web

Récupération de contenu web

Recherche de fichiers

Sous-agents

Middleware

Agents anonymes

Configuration d’un agent (attributs PHP)

Options de fournisseur

Approbation humaine (Human Tool Approval)

Un flux d’approbation complet

Génération d’images

Enregistrement des images

Génération d’image via une queue

Synthèse vocale (TTS)

Enregistrement de l’audio

Génération audio via une queue

Transcription (STT)

Séparation des intervenants (diarization)

Transcription via une queue

Résumé de texte (Text Summarization)

Embeddings

Embeddings multimodaux

Recherche vectorielle (pgvector)

Cache des embeddings

Reranking

Reranking de collections

Gestion des fichiers

Référencer un fichier déjà téléversé

Récupérer et supprimer un fichier

Choix du fournisseur

Options spécifiques au fournisseur

Vector stores

Ajouter des fichiers à un store

Retirer un fichier d’un store

Failover

Tests

Tester un agent

Tester la génération d’images

Tester la synthèse vocale

Tester la transcription

Tester les embeddings

Tester le reranking

Tester les fichiers

Tester les vector stores

Événements