Laravel AI SDK - Knowledge of Laravel

Introducción

Laravel AI SDK proporciona una API unificada y expresiva para interactuar con proveedores de IA como OpenAI, Anthropic o Gemini. Con AI SDK puedes construir agentes inteligentes con herramientas y salida estructurada, generar imágenes, sintetizar voz y transcribir audio, crear embeddings vectoriales y muchas otras funciones de IA con una interfaz coherente y muy propia de Laravel.

Laravel AI SDK es un paquete oficial añadido en Laravel 13. Se distribuye como laravel/ai y permite trabajar con múltiples proveedores de IA a través de una API unificada.

Lista de compatibilidad por proveedor

Función	Proveedores compatibles
Generación de texto	OpenAI, OpenAI Compatible, Anthropic, Gemini, Azure, Bedrock, Groq, xAI, DeepSeek, Mistral, Ollama, OpenRouter
Generación de imágenes	OpenAI, Gemini, xAI, Azure, Bedrock, OpenRouter
Síntesis de voz (TTS)	OpenAI, ElevenLabs, Gemini
Reconocimiento de voz (STT)	OpenAI, ElevenLabs, Mistral, Gemini
Embeddings	OpenAI, Gemini, Azure, Bedrock, Cohere, Mistral, Jina, VoyageAI, Ollama, OpenRouter
Reranking	Cohere, Jina, VoyageAI
Archivos	OpenAI, Anthropic, Gemini, Azure

Instalación

Instalación del paquete

Instala Laravel AI SDK con Composer.

composer require laravel/ai

Publicar el archivo de configuración y las migraciones

Publica el archivo de configuración y las migraciones con el comando Artisan vendor:publish.

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

Ejecutar las migraciones

Ejecuta las migraciones de la base de datos. Se crearán las tablas agent_conversations y agent_conversation_messages, que se usan para guardar el historial de conversaciones.

php artisan migrate

Configuración

Variables de entorno

Define las claves de API de los proveedores de IA que vayas a usar en el archivo .env.

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=

Los modelos por defecto para texto, imágenes, audio, transcripción y embeddings también pueden configurarse en config/ai.php.

URL base personalizada

Si necesitas dirigir el tráfico a través de un servicio proxy, puedes definir una URL personalizada por proveedor.

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

Las URL base personalizadas están disponibles para OpenAI, Anthropic, Gemini, Groq, Cohere, DeepSeek, xAI y OpenRouter.

Proveedor OpenAI-Compatible

Cuando uses APIs compatibles con OpenAI, como LM Studio, vLLM, Together, Fireworks o gateways locales, puedes configurar el proveedor con el driver openai-compatible. url es obligatorio y, si indicas key, se enviará como token Bearer.

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

Una vez configurado, puedes indicarlo por su nombre de la misma forma que los demás proveedores.

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

Si defines un modelo de texto por defecto, no necesitarás indicar el modelo cada vez.

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

El proveedor OpenAI-Compatible soporta generación de texto, streaming, herramientas, salida estructurada y adjuntar imágenes. Si tu endpoint necesita campos adicionales en el cuerpo de la petición, utiliza opciones de proveedor.

Enum Lab

Para referenciar los proveedores desde el código utiliza el enum Lab.

use Laravel\Ai\Enums\Lab;

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

Agentes

Los agentes son el bloque de construcción fundamental de Laravel AI SDK. Puedes generar una clase de agente con el comando make:agent.

php artisan make:agent SalesCoach

# Generar un agente con salida estructurada
php artisan make:agent SalesCoach --structured

Los agentes generados se colocan en el directorio app/Ai/Agents/. A continuación se muestra un ejemplo de un agente que implementa todas las interfaces principales.

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

Envía un mensaje al agente con el método prompt().

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

Con el método estático make() puedes crear una instancia resolviendo sus dependencias desde el contenedor.

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

El proveedor, el modelo y el timeout pueden sobreescribirse mediante los argumentos de prompt().

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

Contexto conversacional

Si implementas la interfaz Conversational y defines el método messages(), puedes pasar el historial de conversación previo a la IA. Con el trait RemembersConversations puedes guardar y recuperar automáticamente el historial de conversación en la base de datos.

use Laravel\Ai\Concerns\RemembersConversations;

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

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

Inicia una conversación con forUser() y utiliza el conversationId devuelto para continuarla 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.');

Salida estructurada

Si implementas la interfaz HasStructuredOutput y defines el esquema JSON en el método schema(), podrás recibir la respuesta de la IA como datos estructurados.

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

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

Objetos anidados

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

Arrays de objetos

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 (elegir entre varios esquemas)

Cuando el valor pueda coincidir con cualquiera de varios esquemas, usa el método 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(),
    ];
}

Adjuntos

Con el argumento attachments puedes pasar documentos e imágenes al agente.

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

Los adjuntos de imagen se manejan de la misma forma.

$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 el método stream() la respuesta se devuelve por fragmentos (chunks). Es útil para enviar respuestas largas al frontend en tiempo real.

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

Puedes describir el procesamiento tras finalizar el streaming con el callback then().

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

También puedes iterar el stream manualmente.

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

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

Protocolo Vercel AI SDK

Si usas Vercel AI SDK en el frontend, llama a usingVercelDataProtocol().

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

Broadcasting

Los eventos del stream pueden enviarse a canales de broadcast como 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() puedes emitir el broadcast pasando por la cola.

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

Omitir eventos muy grandes

Algunas plataformas de broadcast limitan los mensajes de WebSocket a aproximadamente 10 KB. Los eventos de stream con mucho contenido (como resultados de herramientas de gran tamaño) pueden superar ese límite y fallar al emitirse. Con el atributo WithoutBroadcasting puedes excluir del broadcast tipos de eventos concretos.

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

    // ...
}

Los eventos excluidos no se emiten por broadcast, pero se siguen guardando en la tabla agent_conversation_messages. De esta forma, el frontend puede obtener todos los datos de las herramientas tras finalizar el stream. Esto funciona tanto por cola (broadcastOnQueue) como de forma síncrona (broadcast / broadcastNow).

Cola

Con el método queue() puedes encolar el prompt para procesarlo de forma asíncrona.

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

Herramientas

Las herramientas permiten que la IA invoque funciones de tu código. Puedes generar una clase de herramienta con el 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 las herramientas en el método tools() del agente.

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

Herramienta de búsqueda por similitud

Puedes añadir con facilidad una herramienta de búsqueda por similitud basada en embeddings vectoriales.

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

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

También puedes indicar opciones.

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

Y definir tu propia lógica de búsqueda con un closure.

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

Con withDescription() puedes personalizar la descripción de la herramienta.

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

Herramientas de almacenamiento de archivos

Con la fábrica de herramientas FileStorage puedes darle al agente acceso a un disco del sistema de archivos de Laravel. El método all devuelve el conjunto de herramientas para listar, leer, generar URL, escribir, eliminar y copiar archivos en el disco indicado.

use Laravel\Ai\Tools\FileStorage;

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

Si solo quieres permitir acceso de lectura, utiliza el método readOnly.

return FileStorage::readOnly('local');

Estos métodos devuelven una Illuminate\Support\Collection, así que puedes filtrar aún más las herramientas que se ofrecen.

use Laravel\Ai\Tools\Filesystem\DeleteFile;

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

Herramientas MCP

Si tu aplicación utiliza Laravel MCP, puedes ofrecer al agente las herramientas expuestas por un servidor Model Context Protocol. Puedes utilizar el cliente MCP de Laravel para conectarte a un servidor MCP remoto o local y pasar sus herramientas directamente al agente.

Para usar herramientas MCP necesitas tener instalado el paquete Laravel MCP en la aplicación.

El método tools del cliente MCP devuelve una colección, así que utiliza el operador spread ... para expandirla dentro del array tools del 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,
    ];
}

El AI SDK envuelve automáticamente cada herramienta MCP para que el agente pueda invocarla como cualquier otra herramienta. También puedes usar clientes MCP con nombre.

use Laravel\Mcp\Facades\Mcp;

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

O conectarte a un servidor MCP local.

use Laravel\Mcp\Client;

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

Para más información sobre la creación de clientes MCP y la autenticación (tokens Bearer, OAuth, etc.), consulta la documentación del cliente MCP.

Herramientas de proveedor

Son herramientas especiales que el proveedor de IA implementa de forma nativa.

Búsqueda web

Añade búsqueda web al agente. Compatible con Anthropic, OpenAI, Gemini y OpenRouter.

use Laravel\Ai\Providers\Tools\WebSearch;

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

Opcionalmente puedes indicar el número de resultados, restringir dominios o especificar la ubicación.

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

Fetch web

Herramienta para obtener el contenido de la URL indicada. Compatible con Anthropic y Gemini.

use Laravel\Ai\Providers\Tools\WebFetch;

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

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

Búsqueda de archivos

Herramienta para buscar documentos en un vector store. Compatible con OpenAI y Gemini.

use Laravel\Ai\Providers\Tools\FileSearch;

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

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

// Filtrar por metadatos
new FileSearch(stores: ['store_id'], where: ['author' => 'Taylor Otwell', 'year' => 2026]);

También puedes indicar filtros complejos 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'])
);

Subagentes

Un agente también puede devolverse desde el método tools() de otro agente. Al registrar un agente como herramienta, el agente padre puede delegar tareas concretas en el subagente e incorporar el resultado a su respuesta original. Resulta útil cuando un agente genérico necesita acceder a agentes especializados con instrucciones, herramientas, configuración de modelo o de proveedor específicas. Por ejemplo, un agente de atención al cliente que delega las preguntas sobre políticas de reembolso a un agente especializado en reembolsos.

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

Para personalizar cómo se le presenta el subagente al agente padre, implementa la interfaz CanActAsTool en el subagente y define el nombre y la descripción de la herramienta.

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

Cuando el subagente no implementa CanActAsTool, Laravel usa el nombre de la clase como nombre de la herramienta y genera automáticamente una descripción genérica. Cada invocación de subagente es independiente y no hereda el historial de conversación del agente padre.

Middleware

Puedes añadir middleware al agente para interceptar prompts y respuestas.

php artisan make:agent-middleware LogPrompts

Implementa la interfaz HasMiddleware en el agente y registra el middleware en el método 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];
    }
}

Un ejemplo de implementación de la clase de 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() también puedes añadir procesamiento posterior a la respuesta.

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

Agentes anónimos

Con la función helper agent() puedes utilizar agentes anónimos sin necesidad de definir una clase.

use function Laravel\Ai\{agent};

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

También puedes crear agentes anónimos con salida estructurada.

use Illuminate\Contracts\JsonSchema\JsonSchema;

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

Configuración del agente (atributos PHP)

Con atributos PHP puedes escribir la configuración por defecto del agente de forma declarativa.

Atributo	Descripción
`#[Provider]`	Especifica el proveedor a usar
`#[Model]`	Especifica el modelo a usar
`#[MaxSteps]`	Número máximo de pasos de invocación de herramientas
`#[MaxTokens]`	Número máximo de tokens
`#[Temperature]`	Parámetro de temperatura (0.0–1.0)
`#[TopP]`	Probabilidad del núcleo de sampling (0.0–1.0)
`#[Timeout]`	Timeout (segundos)
`#[UseCheapestModel]`	Selecciona automáticamente el modelo más económico
`#[UseSmartestModel]`	Selecciona automáticamente el modelo más potente

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

También hay atributos de atajo para la selección de modelo.

// Usar el modelo más económico
#[UseCheapestModel]
class SimpleSummarizer implements Agent
{
    use Promptable;
}

// Usar el modelo más potente
#[UseSmartestModel]
class ComplexReasoner implements Agent
{
    use Promptable;
}

Opciones de proveedor

Al implementar la interfaz HasProviderOptions puedes pasar opciones específicas del proveedor.

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

Aprobación humana de herramientas (Human Tool Approval)

Para utilizar la aprobación de herramientas necesitas un agente Conversational cuyo historial de conversación se persista. Para poder reanudar una invocación en pausa, el trait RemembersConversations aporta la persistencia necesaria.

En herramientas que realizan operaciones sensibles o irreversibles, como eliminar archivos o transferir dinero, puedes exigir aprobación humana antes de la ejecución. Para marcar una herramienta como aprobable, implementa el contrato Approvable y usa el trait InteractsWithApprovals. Las herramientas aprobables requieren aprobación por defecto.

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

    /**
     * Obtiene la descripción del propósito de la herramienta
     */
    public function description(): Stringable|string
    {
        return 'Elimina un archivo del almacenamiento.';
    }

    /**
     * Ejecuta la herramienta
     */
    public function handle(Request $request): Stringable|string
    {
        Storage::delete($request['path']);

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

    /**
     * Obtiene la definición del esquema de la herramienta
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'path' => $schema->string()->required(),
        ];
    }
}

Si quieres decidir si se requiere aprobación en función de los argumentos de la invocación, define el método needsApproval en la herramienta. Este método puede devolver un booleano o una instancia de Approval que incluya el motivo de la aprobación.

use Laravel\Ai\Approvals\Approval;

/**
 * Determina si la herramienta necesita aprobación para la petición dada
 */
protected function needsApproval(Request $request): Approval|bool
{
    return str_starts_with($request['path'], 'temporary/')
        ? false
        : Approval::required('Este archivo se eliminará de forma permanente.');
}

Al devolver las herramientas desde el método tools del agente también puedes sobreescribir el requisito de aprobación.

public function tools(): iterable
{
    return [
        (new SendNotification)->withoutApproval(),
        (new DeleteFile)->requireApproval('La eliminación requiere confirmación.'),
    ];
}

Cuando se invoca una herramienta aprobable, el agente se detiene antes de ejecutarla. Puedes examinar pendingApprovals en la respuesta para consultar el ID, el nombre de la herramienta, los argumentos y el motivo de aprobación de cada invocación.

$response = (new FileAssistant)
    ->forUser($user)
    ->prompt('Elimina las facturas antiguas.');

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

Para reanudar el agente, continúa la conversación y pasa una instancia de Decisions con la decisión de cada invocación de herramienta pendiente. En una decisión puedes aprobar, rechazar o editar los argumentos de la invocación antes de ejecutarla.

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('Esta factura debe conservarse.'),
    ]));

Los valores booleanos true y false pueden usarse como forma abreviada de aprobar y rechazar, respectivamente. Todas las invocaciones de herramienta pendientes necesitan una decisión. Si indicas un ID de invocación desconocido, ausente o ya resuelto, se lanzará ApprovalMismatchException. Para las invocaciones sin decisión explícita, puedes indicar una decisión por defecto con los métodos approveRemaining o rejectRemaining.

$decisions = Decisions::from([
    'call_abc' => true,
])->rejectRemaining('No fue aprobado.');

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

Al rechazar con un resultado, como Decision::reject('No fue aprobado.'), el resultado se devuelve al modelo y la respuesta continúa. Si se rechaza sin resultado, el bucle de generación se detiene en el momento en que se registra el rechazo. La aprobación de herramientas se soporta en los métodos prompt, stream, queue, broadcast, broadcastNow y broadcastOnQueue. Durante el streaming y el broadcasting, la pausa se representa como un evento tool_approval_request. Cuando utilizas el protocolo de stream de Vercel AI SDK, las solicitudes y los resultados de aprobación se emiten como las partes nativas de aprobación de herramientas del protocolo. En el caso de agentes encolados, la respuesta resultante se pasa al callback then y Laravel también despacha el evento ToolApprovalRequested. Laravel guarda el resultado de la ejecución de las herramientas aprobadas antes de pedirle al modelo que continúe. Si la generación posterior falla, las aprobaciones ya están resueltas. En lugar de reenviar la misma decisión de aprobación, continúa la conversación con un prompt de texto normal.

Flujo completo de aprobación

Las siguientes rutas muestran un flujo completo de aprobación. La ruta GET devuelve la pantalla de chat y la ruta POST recibe un nuevo prompt de texto desde la pantalla o una decisión de aprobación. En este ejemplo se asume que el modelo User de la aplicación usa el 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');

Cuando el estado de la respuesta sea awaiting_approval, la pantalla de chat mostrará las aprobaciones pendientes y deberá enviar al mismo endpoint la elección del usuario usando como clave el ID de la invocación de la herramienta.

{
    "decisions": {
        "call_abc": {
            "action": "approve"
        },
        "call_def": {
            "action": "reject",
            "result": "Esta factura debe conservarse."
        }
    }
}

Para un mensaje de chat normal, en su lugar envía el valor de message.

{
    "message": "Elimina las facturas antiguas."
}

El flujo de aprobación es un mecanismo que otorga a los agentes de IA capacidades operativas potentes al tiempo que introduce una revisión humana antes de la ejecución. Aprovéchalo especialmente en herramientas cuyas operaciones no puedan deshacerse: eliminación de archivos, procesamiento de pagos, escritura en APIs externas, etc.

Generación de imágenes

Con la clase Image puedes generar imágenes. Compatible con los proveedores OpenAI, Gemini y xAI.

use Laravel\Ai\Image;

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

Puedes indicar la calidad, la relación de aspecto y el timeout.

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

También puedes adjuntar una imagen de referencia para editarla.

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

Guardar la imagen

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

Generar imágenes por cola

use Laravel\Ai\Responses\ImageResponse;

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

Síntesis de voz (TTS)

Con la clase Audio puedes convertir texto a voz. Compatible con los proveedores OpenAI y ElevenLabs.

use Laravel\Ai\Audio;

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

Puedes indicar el género de la voz, un ID de voz concreto o instrucciones de estilo.

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

Guardar el audio

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

Generar audio por cola

use Laravel\Ai\Responses\AudioResponse;

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

Transcripción (STT)

Con la clase Transcription puedes convertir archivos de audio a texto. Compatible con los proveedores OpenAI, ElevenLabs y 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;

Diarización de hablantes

Con diarize() obtienes una transcripción segmentada por hablante.

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

Transcripción por cola

use Laravel\Ai\Responses\TranscriptionResponse;

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

Resumen de texto (Text Summarization)

Con el método summarize que proporciona la clase Stringable de Laravel puedes resumir un texto. Por defecto se resume en 3 frases como máximo, utilizando el modelo de texto más económico del proveedor configurado.

use Illuminate\Support\Str;

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

También puedes indicar el número máximo de frases del resumen, el proveedor, el modelo y el timeout. La clase Str ofrece la versión estática.

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

Convierte texto en representaciones vectoriales para aprovecharlo en búsquedas por similitud, entre otras cosas.

use Illuminate\Support\Str;

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

use Laravel\Ai\Embeddings;

// Procesar varios textos a la vez
$response = Embeddings::for(['Napa Valley has great wine.', 'Laravel is a PHP framework.'])->generate();
$response->embeddings; // [[0.123, 0.456, ...], [0.789, 0.012, ...]]

También puedes indicar el proveedor, el modelo y las dimensiones.

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

Embeddings multimodales

El método Embeddings::for no solo acepta cadenas: también admite imágenes, audio, documentos y vídeo, de forma que puedes generar embeddings para contenido distinto del texto. Gemini soporta embeddings de imágenes, audio, documentos y vídeo; VoyageAI soporta embeddings de imágenes y vídeo.

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

Para las entradas multimodales se usan las mismas clases de archivo que en los adjuntos. Puedes crear estos archivos a partir de una ruta local, de un disco del sistema de archivos, de una URL remota o de contenido codificado en Base64. Las imágenes, documentos y vídeos también pueden crearse desde archivos subidos, y los documentos pueden crearse desde contenido de cadena en bruto.

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 no permite mezclar en la misma petición contenido multimedia de URL remotas con contenido codificado en Base64. Los archivos locales, de storage y subidos se envían como contenido codificado en Base64, y las entradas de texto se pueden combinar con cualquiera de las dos fuentes de contenido. Consulta la documentación de cada proveedor para conocer los modelos multimodales y las entradas disponibles.

Búsqueda vectorial (pgvector)

Ejemplo de configuración de búsqueda vectorial con PostgreSQL y la extensión pgvector.

Crear la migración

Schema::ensureVectorExtensionExists();

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

// Añadir un índice HNSW
$table->vector('embedding', dimensions: 1536)->index();

Configurar el modelo

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

Consulta por similitud

// Buscar por vector de embedding
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();

// Pasando una cadena, el embedding se genera automáticamente
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();

También hay métodos de más bajo nivel.

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

Caché de embeddings

Puedes cachear los embeddings para no volver a generarlos con el mismo texto. Configura los valores por defecto de la caché en config/ai.php.

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

También puedes controlar la caché por petición.

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

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

Reranking

Puedes reordenar (rerank) los resultados de búsqueda según su relevancia para la consulta. Compatible con los proveedores Cohere y 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() puedes limitar el número de resultados devueltos.

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

Reranking de colecciones

Puedes rerankar directamente una colección de Eloquent.

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

// Varios campos (se envían como JSON)
$reranked = $posts->rerank(['title', 'body'], 'Laravel tutorials');

// Generación de texto personalizada mediante closure
$reranked = $posts->rerank(fn ($post) => $post->title.': '.$post->body, 'Laravel tutorials');

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

Gestión de archivos

Puedes subir archivos al proveedor de IA para referenciarlos posteriormente.

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

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

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

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

return $response->id;

También puedes trabajar con cadenas o con subidas desde formulario.

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

Referenciar un archivo ya guardado

Puedes adjuntar al agente un archivo ya subido a partir de su ID.

use Laravel\Ai\Files;

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

Obtener y eliminar archivos

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

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

Especificar el proveedor

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

Especificar opciones específicas del proveedor

Con el método withProviderOptions puedes pasar opciones de subida específicas del proveedor. Por ejemplo, puedes configurar el purpose del archivo en OpenAI.

use Laravel\Ai\Files\Document;

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

Si quieres indicar opciones distintas por proveedor, pasa un 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

Con los vector stores puedes gestionar los documentos en el lado del proveedor.

use Laravel\Ai\Stores;

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

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

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

Añadir archivos al store

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

// Añadir archivos de distintas maneras
$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;

También puedes asociar metadatos.

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

Eliminar archivos del store

$store->remove('file_id');

// Para eliminar también el archivo en sí
$store->remove('file_abc123', deleteFile: true);

Failover

Si indicas varios proveedores en un array, cuando el primero falle se hará automáticamente fallback al siguiente.

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

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

// Failover en generación de imágenes
$image = Image::of('A donut sitting on the kitchen counter')
    ->generate(provider: [Lab::Gemini, Lab::xAI]);

Pruebas

Laravel AI SDK ofrece funcionalidad de fakes para pruebas, de forma que puedas testear sin llamar a la API real.

Pruebas de agentes

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

// Fake con respuestas fijas
SalesCoach::fake();
SalesCoach::fake(['First response', 'Second response']);

// Respuestas dinámicas con closure
SalesCoach::fake(function (AgentPrompt $prompt) {
    return 'Response for: '.$prompt->prompt;
});

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

También hay aserciones para encolado.

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() se lanza una excepción si se invoca un prompt que no ha sido definido en el fake.

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

Al hacer fake de un agente con salida estructurada, puedes indicar la respuesta como array. El agente devolverá una respuesta estructurada con los datos indicados.

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

Si se llama a fake() en un agente con salida estructurada sin pasar datos falsos explícitos, Laravel genera automáticamente datos falsos acordes con el esquema definido por el agente.

Para probar agentes anónimos, usa AnonymousAgent::fake().

use Laravel\Ai\AnonymousAgent;

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

Pruebas de generación de imágenes

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

Pruebas de síntesis de voz

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

Pruebas de transcripción

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

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

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

Pruebas de archivos

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

Pruebas de vector stores

use Laravel\Ai\Stores;

Stores::fake(); // Las operaciones sobre archivos también quedan fakeadas

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

También puedes hacer aserciones sobre las operaciones de archivo del 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');

// Verificar el contenido con un 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!');

Eventos

Laravel AI SDK despacha los siguientes eventos. Puedes escucharlos para registrar logs, monitorizar, etc.

Relacionados con agentes

PromptingAgent — antes de enviar el prompt
AgentPrompted — después de enviar el prompt
StreamingAgent — al iniciar el streaming
AgentStreamed — al finalizar el streaming
InvokingTool — antes de invocar la herramienta
ToolInvoked — después de invocar la herramienta
ToolApprovalRequested — cuando se solicita aprobación de la herramienta
ToolApprovalResolved — después de resolverse la aprobación de la herramienta

Relacionados con imágenes, audio y transcripción

GeneratingImage — antes de generar la imagen
ImageGenerated — después de generar la imagen
GeneratingAudio — antes de generar el audio
AudioGenerated — después de generar el audio
GeneratingTranscription — antes de generar la transcripción
TranscriptionGenerated — después de generar la transcripción

Relacionados con embeddings y reranking

GeneratingEmbeddings — antes de generar los embeddings
EmbeddingsGenerated — después de generar los embeddings
Reranking — antes del reranking
Reranked — después del reranking

Relacionados con archivos y stores

StoringFile — antes de guardar el archivo
FileStored — después de guardar el archivo
FileDeleted — después de eliminar el archivo
CreatingStore — antes de crear el store
StoreCreated — después de crear el store
AddingFileToStore — antes de añadir el archivo al store
FileAddedToStore — después de añadir el archivo al store
RemovingFileFromStore — antes de eliminar el archivo del store
FileRemovedFromStore — después de eliminar el archivo del store

Última modificación el 2 de agosto de 2026

Temas relacionados

Resumen de las novedades de Laravel 13 Actualización de Laravel — Marzo de 2026 Integración con Laravel AI SDK Integración con Laravel AI SDK - VOICEVOX for Laravel Driver de Amazon Bedrock para Laravel AI SDK

Laravel MCP

Laravel Sail

​Introducción

​Lista de compatibilidad por proveedor

​Instalación

​Configuración

​Variables de entorno

​URL base personalizada

​Proveedor OpenAI-Compatible

​Enum Lab

​Agentes

​Prompt

​Contexto conversacional

​Salida estructurada

​Objetos anidados

​Arrays de objetos

​anyOf (elegir entre varios esquemas)

​Adjuntos

​Streaming

​Protocolo Vercel AI SDK

​Broadcasting

​Omitir eventos muy grandes

​Cola

​Herramientas

​Herramienta de búsqueda por similitud

​Herramientas de almacenamiento de archivos

​Herramientas MCP

​Herramientas de proveedor

​Búsqueda web

​Fetch web

​Búsqueda de archivos

​Subagentes

​Middleware

​Agentes anónimos

​Configuración del agente (atributos PHP)

​Opciones de proveedor

​Aprobación humana de herramientas (Human Tool Approval)

​Flujo completo de aprobación

​Generación de imágenes

​Guardar la imagen

​Generar imágenes por cola

​Síntesis de voz (TTS)

​Guardar el audio

​Generar audio por cola

​Transcripción (STT)

​Diarización de hablantes

​Transcripción por cola

​Resumen de texto (Text Summarization)

​Embeddings

​Embeddings multimodales

​Búsqueda vectorial (pgvector)

​Caché de embeddings

​Reranking

​Reranking de colecciones

​Gestión de archivos

​Referenciar un archivo ya guardado

​Obtener y eliminar archivos

​Especificar el proveedor

​Especificar opciones específicas del proveedor

​Vector Stores

​Añadir archivos al store

​Eliminar archivos del store

​Failover

​Pruebas

​Pruebas de agentes

​Pruebas de generación de imágenes

​Pruebas de síntesis de voz

​Pruebas de transcripción

​Pruebas de embeddings

​Pruebas de reranking

​Pruebas de archivos

​Pruebas de vector stores

​Eventos

Introducción

Lista de compatibilidad por proveedor

Instalación

Configuración

Variables de entorno

URL base personalizada

Proveedor OpenAI-Compatible

Enum Lab

Agentes

Prompt

Contexto conversacional

Salida estructurada

Objetos anidados

Arrays de objetos

anyOf (elegir entre varios esquemas)

Adjuntos

Streaming

Protocolo Vercel AI SDK

Broadcasting

Omitir eventos muy grandes

Cola

Herramientas

Herramienta de búsqueda por similitud

Herramientas de almacenamiento de archivos

Herramientas MCP

Herramientas de proveedor

Búsqueda web

Fetch web

Búsqueda de archivos

Subagentes

Middleware

Agentes anónimos

Configuración del agente (atributos PHP)

Opciones de proveedor

Aprobación humana de herramientas (Human Tool Approval)

Flujo completo de aprobación

Generación de imágenes

Guardar la imagen

Generar imágenes por cola

Síntesis de voz (TTS)

Guardar el audio

Generar audio por cola

Transcripción (STT)

Diarización de hablantes

Transcripción por cola

Resumen de texto (Text Summarization)

Embeddings

Embeddings multimodales

Búsqueda vectorial (pgvector)

Caché de embeddings

Reranking

Reranking de colecciones

Gestión de archivos

Referenciar un archivo ya guardado

Obtener y eliminar archivos

Especificar el proveedor

Especificar opciones específicas del proveedor

Vector Stores

Añadir archivos al store

Eliminar archivos del store

Failover

Pruebas

Pruebas de agentes

Pruebas de generación de imágenes

Pruebas de síntesis de voz

Pruebas de transcripción

Pruebas de embeddings

Pruebas de reranking

Pruebas de archivos

Pruebas de vector stores

Eventos