Laravel AI SDK: cómo integrar IA en Laravel con Agents, Tools, Embeddings y más

El 5 de febrero de 2026, el equipo de Laravel presentó oficialmente el Laravel AI SDK, un paquete first-party que llega para unificar la forma en que interactuamos con proveedores de Inteligencia Artificial desde nuestras aplicaciones Laravel. Se trata de una de las incorporaciones más ambiciosas al ecosistema y está disponible a partir de Laravel 13 de manera estable fuera de fase beta.

Compatibilidad y requisitos

• Laravel 12 o superior.

• PHP 8.4 o superior.

• PostgreSQL con pgvector para embeddings y búsqueda vectorial (opcional, pero recomendado).

• Claves API de al menos un proveedor soportado.

¿Qué es Laravel AI SDK?

Es un paquete (laravel/ai) que proporciona una API unificada para trabajar con múltiples proveedores de IA: OpenAI, Anthropic, Google Gemini, Groq, xAI, DeepSeek, Mistral, Ollama, ElevenLabs, Cohere, Jina y VoyageAI. En lugar de lidiar con las particularidades de cada proveedor, escribes código Laravel y cambias de proveedor con una sola línea.

La instalación es directa:

composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate

La migración crea las tablas agent_conversations y agent_conversation_messages que el SDK utiliza para gestionar la persistencia de conversaciones.

Proveedores soportados por feature

No todos los proveedores soportan todas las funcionalidades. Esta es la tabla de compatibilidad actual:

• Texto: OpenAI, Anthropic, Gemini, Groq, xAI, DeepSeek, Mistral, Ollama.

• Imágenes: OpenAI, Gemini, xAI.

• Text-to-Speech: OpenAI, ElevenLabs.

• Speech-to-Text: OpenAI, ElevenLabs, Mistral.

• Embeddings: OpenAI, Gemini, Cohere, Mistral, Jina, VoyageAI.

• Reranking: Cohere, Jina.

• Files: OpenAI, Anthropic, Gemini.

Por qué este paquete cambia las reglas del juego

Antes de que existiera Laravel AI SDK, integrar IA en una aplicación Laravel significaba instalar el SDK de cada proveedor por separado, aprender su API particular, gestionar las respuestas con formatos distintos y escribir adaptadores propios si querías poder cambiar de proveedor. Funcionaba, pero no era Laravel.

Lo que consigue este paquete es llevar la integración con IA al terreno que conocemos: Artisan commands, contratos e interfaces, el contenedor de servicios, queues, broadcasting, testing con fakes... Todo encaja con lo que ya hacemos cada día. No es un wrapper genérico sobre HTTP; es una integración profunda con el framework.

Yo lo tengo implementado en mi plataforma de cursos desde que salió la beta, concretamente para generar quizzes automáticas a partir del código fuente de los proyectos de cada curso y para generar los metadatos completos de los cursos a partir de las transcripciones de los vídeos. La IA genera los borradores, yo los reviso, ajusto y publico. Y la experiencia de desarrollo ha sido sorprendentemente fluida.

Agents: clases PHP con un propósito claro

El concepto central del SDK son los Agents. Si has trabajado con Actions o Form Requests en Laravel, la idea te va a resultar familiar: una clase PHP dedicada que encapsula las instrucciones, la configuración y el comportamiento de una interacción con un LLM.

Se generan con Artisan:

php artisan make:agent TicketClassifier

Imagina que tienes una aplicación con un sistema de soporte y quieres que la IA clasifique los tickets entrantes automáticamente:

<?php

namespace App\Ai\Agents;

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

class TicketClassifier implements Agent
{
    use Promptable;

    public function instructions(): Stringable|string
    {
        return <<<INSTRUCTIONS
        Eres un clasificador de tickets de soporte técnico.
        Analiza el contenido del ticket y determina su prioridad
        y el departamento al que debe ser asignado.
        Responde siempre en español.
        INSTRUCTIONS;
    }
}

Implementas la interfaz Agent, usas el trait Promptable, defines tus instrucciones y listo:

<?php

$response = TicketClassifier::make()->prompt($ticket->body);

return (string) $response;

Lo que me gusta de este enfoque es que cada Agent queda como una pieza aislada de tu aplicación. Tienes un Agent para clasificar tickets, otro para resumir documentos, otro para generar descripciones de producto. Cada uno con sus instrucciones, su modelo, su configuración. No hay un "servicio de IA" gigante con mil métodos; hay clases pequeñas y focalizadas, que es exactamente cómo deberían ser.

Configuración declarativa con Attributes

La configuración del modelo, tokens, temperatura y timeout se hace con PHP Attributes directamente en la clase:

<?php

use Laravel\Ai\Attributes\Model;
use Laravel\Ai\Attributes\MaxTokens;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Attributes\Timeout;

#[Model('claude-sonnet-4-6-20260217')]
#[MaxTokens(4096)]
#[Temperature(0.3)]
#[Timeout(120)]
class TicketClassifier implements Agent
{
    use Promptable;

    // ...
}

Abres la clase y en las primeras líneas ya sabes qué modelo usa, cuántos tokens puede generar y cuánto tiempo tiene antes de timeout. No hay que buscar en archivos de configuración ni en variables de entorno dispersas. Todo está donde debe estar.

Y si no quieres amarrarte a un modelo concreto, existen #[UseCheapestModel] y #[UseSmartestModel] para seleccionar automáticamente el modelo más económico o más capaz del proveedor configurado.

Cambiar de proveedor o modelo en cualquier momento:

<?php

$response = new TicketClassifier()->prompt(
    $ticket->body,
    provider: 'openai',
    model: 'gpt-4o',
);

Structured Output: la IA devuelve datos, no texto

Cuando necesitas datos con una estructura concreta y no texto libre, implementas HasStructuredOutput y defines un schema. Siguiendo con el clasificador de tickets:

<?php

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\HasStructuredOutput;

class TicketClassifier implements Agent, HasStructuredOutput
{
    use Promptable;

    public function instructions(): string
    {
        return 'Clasifica tickets de soporte técnico por prioridad y departamento.';
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'priority' => $schema->string()->enum(['low', 'medium', 'high', 'critical'])->required(),
            'department' => $schema->string()->enum(['billing', 'technical', 'sales', 'general'])->required(),
            'summary' => $schema->string()->required(),
            'suggested_response' => $schema->string()->required(),
        ];
    }
}

La respuesta se comporta como un array:

<?php

$result = new TicketClassifier()->prompt($ticket->body);

$result['priority'];           // "high"
$result['department'];         // "technical"
$result['summary'];            // "El usuario no puede acceder al panel..."
$result['suggested_response']; // "Hemos detectado un problema con..."

El schema garantiza que la respuesta tenga exactamente la estructura que esperas. Sin parsear texto, sin expresiones regulares, sin rezar para que el modelo responda en el formato correcto. Defines el schema una vez y el SDK se encarga de que el modelo lo respete.

Para schemas complejos con objetos anidados, arrays de objetos y enums, funciona igual de bien. En mi caso, mis Agents devuelven arrays con preguntas, respuestas, puntuaciones y explicaciones para cada quiz. El schema es bastante denso y la respuesta llega siempre con la estructura correcta.

Tools: cuando el Agent necesita consultar tu aplicación

Los Tools son la forma de darle capacidades adicionales a tus Agents. El Agent decide cuándo necesita usarlos y los invoca automáticamente.

php artisan make:tool CustomerOrderHistory

Imagina que tu Agent de soporte necesita consultar el historial de pedidos del cliente para dar una respuesta contextualizada:

<?php

namespace App\Ai\Tools;

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

class CustomerOrderHistory implements Tool
{
    public function description(): Stringable|string
    {
        return 'Consulta los últimos pedidos de un cliente por su email.';
    }

    public function handle(Request $request): Stringable|string
    {
        $orders = Order::whereHas('customer', fn ($q) => $q->where('email', $request['email']))
            ->latest()
            ->limit(5)
            ->get(['id', 'status', 'total', 'created_at']);

        return $orders->toJson();
    }

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

Lo registras en tu Agent implementando HasTools:

<?php

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

El Agent recibe un ticket, detecta que necesita saber el historial del cliente, invoca el Tool automáticamente, recibe los datos y genera la respuesta con contexto real. Tú solo defines la pieza y el SDK orquesta todo.

En mi plataforma tengo un Tool que descomprime un ZIP con el proyecto final de un curso, filtra los archivos relevantes (app/, routes/, tests/, database/migrations/...) y le pasa el código fuente al Agent para que genere preguntas específicas sobre lo que el alumno ha construido. El Agent decide cuándo invocarlo y usa la respuesta como contexto para generar el quiz.

Provider Tools

Además de tus Tools propios, el SDK incluye Tools que se ejecutan directamente en el proveedor:

<?php

use Laravel\Ai\Providers\Tools\WebSearch;
use Laravel\Ai\Providers\Tools\WebFetch;

public function tools(): iterable
{
    return [
        (new WebSearch())->max(5)->allow(['laravel.com', 'php.net']),
        (new WebFetch())->max(3)->allow(['docs.laravel.com']),
    ];
}

WebSearch para búsquedas en tiempo real, WebFetch para leer contenido de páginas, FileSearch para buscar en Vector Stores y SimilaritySearch para búsqueda semántica directamente sobre tus modelos Eloquent.

Contexto conversacional

Si tu Agent necesita recordar mensajes anteriores, implementas Conversational. Puedes gestionar los mensajes manualmente con el método messages() o usar el trait RemembersConversations para que Laravel lo haga por ti:

<?php

use Laravel\Ai\Concerns\RemembersConversations;
use Laravel\Ai\Contracts\Conversational;

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

    public function instructions(): string
    {
        return 'Eres un asistente de soporte técnico. Mantén el contexto de la conversación.';
    }
}

<?php

// Iniciar conversación
$response = (new SupportChatAgent())->forUser($user)->prompt('No puedo acceder a mi cuenta');
$conversationId = $response->conversationId;

// Continuarla después
$response = new SupportChatAgent()
    ->continue($conversationId, as: $user)
    ->prompt('Ya probé a restablecer la contraseña pero sigue igual');

Los mensajes se persisten automáticamente. Sin configuración adicional.

Streaming, queues y broadcasting

El SDK cubre los tres escenarios de respuesta que necesitas en una aplicación real.

Streaming directo al navegador:

<?php

Route::get('/support/chat', function () {
    return new SupportChatAgent()->stream($request->input('message'));
});

Con ->then() ejecutas lógica cuando el streaming termina y con ->usingVercelDataProtocol() tienes compatibilidad directa con frontends React/Next.js.

Queues para procesar en segundo plano sin bloquear la petición HTTP:

<?php

new TicketClassifier()
    ->queue($ticket->body)
    ->then(function (AgentResponse $response) {
        // Actualizar el ticket con la clasificación...
    })
    ->catch(function (Throwable $e) {
        // Gestionar error...
    });

Y broadcasting para enviar eventos de streaming a canales de Laravel Reverb. Cada escenario tiene su caso de uso y el SDK te da las tres opciones sin dependencias extra.

Imágenes, audio y transcripciones

La generación de imágenes, text-to-speech y transcripción siguen el mismo patrón fluido:

<?php

use Laravel\Ai\Image;

$image = Image::of('Logotipo minimalista para una app de gestión de tareas, fondo blanco')
    ->quality('high')
    ->square()
    ->generate();

$path = $image->storeAs('logos/tasks-app.png', 's3');

<?php

use Laravel\Ai\Transcription;

$transcript = Transcription::fromStorage('meetings/standup-2026-02-20.mp3')
    ->diarize()
    ->generate();

Todo se puede encolar con ->queue() y tiene soporte para attachments. La API es consistente en todas las features.

Embeddings y búsqueda vectorial

La integración con embeddings es donde se nota que esto no es un wrapper superficial. Laravel ahora soporta columnas vector de forma nativa en PostgreSQL con pgvector:

<?php

// En tu migración
$table->vector('embedding', dimensions: 1536)->index();

Generar embeddings:

<?php

use Illuminate\Support\Str;

$embeddings = Str::of('Cómo configurar queues en Laravel con Redis')->toEmbeddings();

Y buscar por similitud semántica:

<?php

use App\Models\Article;

$articles = Article::query()
    ->whereVectorSimilarTo('embedding', 'configurar colas de trabajo en Laravel')
    ->limit(10)
    ->get();

Pasas un string y Laravel genera el embedding automáticamente para la comparación. También puedes cachear embeddings con ->toEmbeddings(cache: true) para evitar llamadas redundantes.

Failover entre proveedores

Algo que en producción se agradece: defines un array de proveedores y el SDK hace failover automático si uno falla por rate limit o caída:

<?php

$response = new TicketClassifier()->prompt(
    $ticket->body,
    provider: ['anthropic', 'openai'],
);

Si Anthropic no responde, la petición se redirige a OpenAI. Sin try-catch, sin lógica de retry propia.

Testing

Cada feature del SDK tiene su método fake() con assertions. Mismo patrón que Http::fake(), Queue::fake(), Mail::fake():

<?php

use App\Ai\Agents\TicketClassifier;

TicketClassifier::fake([
    json_encode([
        'priority' => 'high',
        'department' => 'technical',
        'summary' => 'Problema de acceso',
        'suggested_response' => 'Le ayudamos a restablecer...',
    ]),
]);

// Tu código que usa el Agent...

TicketClassifier::assertPrompted(fn (AgentPrompt $prompt) => str_contains($prompt->prompt, 'No puedo acceder'));

Si testeas en Laravel, ya sabes cómo testear tus Agents. Lo mismo aplica para imágenes, audio, transcripciones, embeddings y todo lo demás.

Middleware para Agents

Los Agents soportan middleware para interceptar prompts antes de enviarlos al proveedor y para actuar sobre la respuesta después. Se generan con Artisan:

php artisan make:agent-middleware TrackTokenUsage

El middleware recibe el AgentPrompt y un Closure. Puedes actuar antes, después o en ambos momentos:

<?php

namespace App\Ai\Middleware;

use Closure;
use Illuminate\Support\Facades\Log;
use Laravel\Ai\Prompts\AgentPrompt;
use Laravel\Ai\Responses\AgentResponse;

class TrackTokenUsage
{
    public function handle(AgentPrompt $prompt, Closure $next)
    {
        return $next($prompt)->then(function (AgentResponse $response) use ($prompt) {
            Log::channel('ai')->info('Agent executed', [
                'agent' => $prompt->agent::class,
                'tokens' => $response->usage,
            ]);
        });
    }
}

Para aplicarlo, tu Agent implementa HasMiddleware:

<?php

use App\Ai\Middleware\TrackTokenUsage;
use Laravel\Ai\Contracts\HasMiddleware;

class TicketClassifier implements Agent, HasStructuredOutput, HasMiddleware
{
    use Promptable;

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

    // ...
}

Útil para logging, métricas de consumo, rate limiting propio o inyectar contexto adicional al prompt antes de que salga.

Mi experiencia usándolo en producción

Llevo usando Laravel AI SDK desde la beta en mi plataforma de cursos y hay algo que quiero destacar: la curva de aprendizaje es prácticamente inexistente si ya conoces Laravel.

No tuve que aprender una forma nueva de hacer las cosas. Creé mis Agents como quien crea un Form Request, definí los schemas como quien define validation rules, registré Tools como quien registra un service provider. El SDK no inventa patrones nuevos; aplica los que ya conocemos al mundo de la IA.

Mis Agents generan borradores que yo reviso antes de publicar. Ese flujo de "la IA propone, el humano dispone" encaja perfectamente con structured output + revisión manual. La IA me ahorra horas de trabajo repetitivo, pero el control de calidad sigue siendo mío.

Si tienes que empezar con algo: crea un Agent simple con structured output. No intentes montar un sistema RAG completo el primer día. Un Agent que reciba texto y devuelva datos estructurados ya te va a demostrar todo el potencial del paquete.

Conclusión

Laravel AI SDK no es un wrapper sobre APIs de IA. Es una integración real con el framework que aprovecha queues, broadcasting, filesystem, el contenedor de servicios y el sistema de testing. Si desarrollas en Laravel y necesitas integrar IA, este es el punto de partida.

El paquete ya ha salido de fase beta, el día de 17 de marzo de 2026, justo cuando Laravel 13 ha sido liberado, así que la API ya es completamente estable. La documentación completa está disponible en laravel.com/docs/13.x/ai-sdk.