Con Laravel 13 llegó el Laravel AI SDK, el paquete oficial para integrar inteligencia artificial en tus aplicaciones: generación de texto, agentes que usan herramientas, embeddings, imágenes, audio y búsqueda semántica. Todo con una API unificada que funciona con distintos proveedores (OpenAI, Anthropic, Gemini, Mistral, DeepSeek, Ollama…).

En este tutorial vamos a construir algo práctico: un agente que lee los mensajes del formulario de contacto de una web y los clasifica, indicando la categoría, la prioridad y un resumen breve.

1. Instalación

Instala el paquete, publica su configuración y ejecuta las migraciones:

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

Las migraciones crean las tablas agent_conversations y agent_conversation_messages, que el SDK usa para guardar el historial de las conversaciones.

2. Configurar el proveedor

Añade la clave de API del proveedor que vayas a usar en el archivo .env. Por ejemplo:

OPENAI_API_KEY=tu-clave
# o
ANTHROPIC_API_KEY=tu-clave

Los modelos que se usan por defecto para texto, imágenes, audio y embeddings se configuran en config/ai.php.

Nunca subas las claves al repositorio: déjalas solo en el .env, que debe estar en el .gitignore.

3. Crear el agente

Cada agente es una clase con sus instrucciones, herramientas y formato de respuesta. Como queremos una respuesta con campos concretos, lo creamos con la opción --structured:

php artisan make:agent ContactClassifier --structured

La clase se crea en app/Ai/Agents. La completamos así:

<?php

namespace App\Ai\Agents;

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

class ContactClassifier implements Agent, HasStructuredOutput
{
    use Promptable;

    /**
     * Instrucciones que el agente debe seguir.
     */
    public function instructions(): string
    {
        return 'Eres el asistente de un desarrollador web freelance. '
            .'Clasifica los mensajes que llegan desde el formulario de contacto. '
            .'Responde siempre en español y no inventes información que no esté en el mensaje.';
    }

    /**
     * Estructura de la respuesta.
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'category' => $schema->string()->required(),
            'priority' => $schema->integer()->min(1)->max(3)->required(),
            'summary' => $schema->string()->required(),
        ];
    }
}

4. Usar el agente

Para lanzarle una petición basta con llamar a prompt(). Como el agente tiene una respuesta estructurada, puedes leer cada campo como si fuera un array:

use App\Ai\Agents\ContactClassifier;

$response = (new ContactClassifier)->prompt(
    "Clasifica este mensaje:\n\n".$contactRequest->message
);

$contactRequest->update([
    'ai_category' => $response['category'],
    'ai_priority' => $response['priority'],
    'ai_summary' => $response['summary'],
]);

Si el agente no tuviera respuesta estructurada, obtendrías el texto con (string) $response o con $response->text.

También puedes elegir el proveedor, el modelo o el tiempo máximo en cada llamada:

use Laravel\Ai\Enums\Lab;

$response = (new ContactClassifier)->prompt(
    'Clasifica este mensaje...',
    provider: Lab::Anthropic,
    timeout: 120,
);

Y si un proveedor falla o te limita las peticiones, puedes indicar varios para que el SDK pase al siguiente automáticamente:

$response = (new ContactClassifier)->prompt(
    'Clasifica este mensaje...',
    provider: [Lab::OpenAI, Lab::Anthropic],
);

5. Darle herramientas al agente

Las herramientas (tools) permiten que el agente consulte datos de tu aplicación cuando los necesite. Por ejemplo, una herramienta que busca si quien escribe ya es cliente:

php artisan make:tool FindCustomer

La herramienta se crea en app/Ai/Tools:

<?php

namespace App\Ai\Tools;

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

class FindCustomer implements Tool
{
    public function description(): Stringable|string
    {
        return 'Busca si un email pertenece a un cliente existente y devuelve su nombre y sus proyectos.';
    }

    public function handle(Request $request): Stringable|string
    {
        $customer = Customer::query()
            ->where('email', $request['email'])
            ->with('projects:id,customer_id,name')
            ->first();

        return $customer
            ? json_encode(['name' => $customer->name, 'projects' => $customer->projects->pluck('name')])
            : 'No es cliente.';
    }

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

Y se registra en el agente, que debe implementar también HasTools:

use App\Ai\Tools\FindCustomer;
use Laravel\Ai\Contracts\HasTools;

class ContactClassifier implements Agent, HasStructuredOutput, HasTools
{
    // ...

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

La herramienta solo lee datos. Si alguna vez das al agente herramientas que modifican o borran información, usa la aprobación humana del SDK (human-in-the-loop), que obliga a confirmar esas acciones antes de ejecutarlas.

6. Respuestas en streaming

Para mostrar la respuesta mientras se genera, por ejemplo en un chat, usa stream() en lugar de prompt():

Route::get('/asistente', function () {
    return (new SupportAssistant)->stream('¿Cómo puedo cambiar mi contraseña?');
});

7. Probar el agente sin gastar tokens

El SDK permite simular las respuestas en los tests, así no llamas a la API ni pagas por cada ejecución:

use App\Ai\Agents\ContactClassifier;

public function test_contact_requests_are_classified(): void
{
    ContactClassifier::fake([
        ['category' => 'presupuesto', 'priority' => 1, 'summary' => 'Quiere una tienda online.'],
    ]);

    // ... código que clasifica la solicitud ...

    ContactClassifier::assertPrompted(fn ($prompt) => $prompt->contains('tienda'));
}

8. Controlar el gasto

Cada respuesta incluye el consumo de tokens que informa el proveedor:

$response->usage->inputTokens;
$response->usage->outputTokens;
$response->usage->totalTokens();

Guárdalo o regístralo para vigilar el coste, sobre todo si el agente se ejecuta automáticamente con cada mensaje que llega.

Buenas prácticas

  • Las claves de API, solo en el .env.
  • Ejecuta las llamadas en una cola si no necesitas la respuesta al momento: la petición del usuario no espera a la IA.
  • No envíes más datos personales de los necesarios al proveedor, y menciónalo en tu política de privacidad.
  • Revisa las respuestas antes de usarlas para algo importante: un modelo de lenguaje puede equivocarse.

Conclusión

El Laravel AI SDK hace que integrar IA en una aplicación Laravel sea tan natural como enviar un correo o lanzar un job: una clase con instrucciones, una llamada a prompt() y tests sin coste.

¿Te gustaría añadir IA a tu aplicación o automatizar alguna tarea de tu negocio? Cuéntame qué necesitas.

Fuentes