Laravel 13 AI SDK: crea agentes y sub-agentes con PHP, sin servicios externos

Laravel 13 "Atlas" dejó el AI SDK en producción estable el 17 de marzo de 2026: agentes con tools, salida estructurada y búsqueda semántica nativa, y desde mayo también sub-agentes. Así construyes una app AI-native sin salir de PHP.

Del beta de Laravel 12 al SDK estable de Laravel 13

El Laravel AI SDK nació en beta durante el ciclo de Laravel 12 como un paquete first-party para integrar modelos de lenguaje con una API consistente al estilo del framework. Con el lanzamiento de Laravel 13 "Atlas" el 17 de marzo de 2026, el SDK pasó a producción estable desde el primer día, lo que cambia las reglas del juego: ya no hace falta montar orquestación propia ni depender de paquetes de terceros para conectar tu aplicación con modelos de IA.

Qué cambió con "Atlas": upgrade en 10 minutos y cero breaking changes

El equipo de Laravel diseñó la transición de 12.x a 13.x para que fuera prácticamente indolora. El camino de actualización oficial se resuelve en unos diez minutos en la mayoría de proyectos, y el AI SDK no introduce breaking changes respecto a la beta: si ya usabas el paquete en Laravel 12, al actualizar te encuentras con las mismas clases y métodos, pero con garantías de estabilidad y soporte de larga duración. Eso convierte a Laravel 13 en la primera versión donde construir funcionalidad AI-native se considera una decisión de producción razonable, no una apuesta.

Qué puedes generar: texto, imágenes, audio y embeddings

El SDK no se limita a chat. Con una única interfaz puedes generar texto, crear imágenes, sintetizar voz, transcribir audio y calcular embeddings para búsquedas vectoriales. La documentación oficial de 13.x presenta estas capacidades como un conjunto homogéneo: el mismo estilo de configuración y las mismas abstracciones para cualquier modalidad, de forma que cambiar de proveedor o de tarea no obliga a reescribir tu lógica de negocio.

Lee también

Laravel 13: novedades y guía de actualización desde Laravel 12

IA local con Ollama: ejecuta LLMs en tu propio equipo sin pagar por API

Agentes: la pieza fundamental del SDK

El concepto central del AI SDK es el agente: una clase PHP dedicada que encapsula todo lo necesario para que un modelo de lenguaje haga un trabajo concreto. En lugar de esparcir llamadas al LLM por controladores y servicios, defines un agente con sus instrucciones, su contexto y sus herramientas, y el SDK se encarga del bucle de ejecución.

Un agente como clase PHP: instrucciones, contexto y tools

Un agente típico declara las instrucciones de sistema, el contexto de conversación y las tools que puede invocar. Las tools son métodos o clases PHP normales que el modelo decide llamar cuando necesita datos o acciones que no puede deducir por sí mismo, como consultar una base de datos o enviar un correo.

composer require laravel/ai

<?php

namespace App\Agents;

use Laravel\Ai\Agent;

class SupportAgent extends Agent
{
    protected string $instructions = '
        Eres el agente de soporte de la tienda.
        Responde siempre en el idioma del usuario.
    ';

    protected array $tools = [
        SearchTickets::class,
        LookupOrder::class,
    ];
}

Cuando el usuario pregunta "¿dónde está mi pedido?", el agente decide usar la tool LookupOrder, obtiene el resultado y construye la respuesta final. Tú solo defines qué puede hacer el agente; la decisión de cuándo hacerlo la toma el modelo.

Salida estructurada y prompts con plantillas Blade

Dos detalles marcan la diferencia frente a integrar un SDK de OpenAI a mano. Primero, la salida estructurada: puedes declarar el esquema de respuesta esperado y el SDK valida y tipa el resultado, eliminando la fase de parsear JSON a mano y los errores silenciosos por campos renombrados. Segundo, los prompts se escriben con plantillas Blade, lo que permite reutilizar parciales, pasar datos del modelo de Laravel y mantener los prompts versionados en tu repositorio como cualquier otra vista.

Providers intercambiables: OpenAI, Anthropic, Ollama y Mistral

El SDK abstrae el proveedor detrás de una capa de configuración. OpenAI, Anthropic, Ollama y Mistral son ciudadanos de primera clase, y la lista sigue creciendo con el ecosistema.

Cambiar de proveedor cambiando una línea de config

La arquitectura de drivers funciona igual que en el resto de Laravel: defines los providers en el archivo de configuración y eliges el activo con una variable de entorno. Cambiar de proveedor no toca ni una línea de tu código de negocio, solo la configuración.

// config/ai.php
'default' => env('AI_PROVIDER', 'openai'),

'providers' => [
    'openai' => [
        'api_key' => env('OPENAI_API_KEY'),
        'model' => env('OPENAI_MODEL', 'gpt-5'),
    ],
    'anthropic' => [
        'api_key' => env('ANTHROPIC_API_KEY'),
        'model' => env('ANTHROPIC_MODEL', 'claude-sonnet-4'),
    ],
    'ollama' => [
        'url' => env('OLLAMA_URL', 'http://localhost:11434'),
        'model' => env('OLLAMA_MODEL', 'llama-3.3'),
    ],
    'mistral' => [
        'api_key' => env('MISTRAL_API_KEY'),
        'model' => env('MISTRAL_MODEL', 'mistral-large'),
    ],
],

Esta flexibilidad tiene una consecuencia práctica muy útil: puedes desarrollar y hacer tests con Ollama en local sin pagar por API y desplegar en producción contra OpenAI o Anthropic cambiando una variable de entorno.

Sub-agentes: orquestación desde mayo de 2026

El 12 de mayo de 2026 el SDK dio el salto de herramienta de chat a capa de orquestación: ahora puedes pasar un agente como tool de otro agente. Nacen así los sub-agentes, que permiten descomponer problemas grandes en agentes especializados.

Pasar un agente como tool de otro agente

La mecánica es directa: instancias un agente especializado y lo incluyes en la lista de tools del agente principal. Cuando el agente principal detecta que la consulta pertenece al dominio del sub-agente, le delega el trabajo con el contexto adecuado y recibe su respuesta.

$refundAgent = new RefundAgent();
$billingAgent = new BillingAgent();

$supportAgent = new SupportAgent([
    'tools' => [
        SearchTickets::class,
        $refundAgent,   // sub-agente
        $billingAgent,  // sub-agente
    ],
]);

$response = $supportAgent->ask(
    'Quiero devolver el pedido 4521 porque llegó roto.'
);

Cada sub-agente puede tener sus propias instrucciones, sus propias tools e incluso un modelo distinto: un sub-agente de facturación puede usar un modelo más barato y rápido, mientras el agente principal emplea el más capaz. El resultado es una arquitectura de agentes modular, testeable y barata de operar.

Cuándo usar sub-agentes (y cuándo no)

Los sub-agentes brillan cuando hay dominios claramente separados: soporte con reembolsos y facturación, un asistente de contenido con sub-agentes de redacción y de corrección, o un sistema de atención al cliente que delega en agentes por producto. En cambio, para tareas lineales con una sola herramienta, un agente único con varias tools es más simple y consume menos tokens. La regla práctica: añade un sub-agente cuando el agente principal empiece a arrastrar instrucciones contradictorias o tools que rara vez usa.

Búsqueda semántica nativa con Eloquent

La otra gran apuesta de Laravel 13 es la búsqueda semántica integrada con Eloquent. En lugar de depender de servicios externos de vector search, el SDK expone flujos de embeddings y vector queries que se apoyan en tu base de datos.

Embeddings, vector queries y flujos de indexado

El patrón típico tiene tres fases: generas embeddings para tus documentos al guardarlos, los almacenas en una columna vectorial del modelo, y consultas por similitud con el embedding de la pregunta del usuario. El SDK también ofrece gestión de vector stores y rerank de resultados para afinar el orden de las respuestas.

$question = '¿Cómo solicito un reembolso?';

$embedding = Ai::embed($question);

$articles = HelpArticle::query()
    ->orderByVector('embedding', $embedding)
    ->limit(5)
    ->get();

Combinado con agentes, este patrón habilita el flujo de retrieval-augmented generation (RAG) sin salir del framework: el agente busca los fragmentos relevantes con una vector query y los usa como contexto para responder con fundamento, en lugar de inventar.

Ejemplo práctico: agente de soporte con sub-agentes

Pongamos todo junto. Una tienda online quiere un chat de soporte que sepa de reembolsos, facturación y estado de pedidos. Con el SDK defines tres agentes: un agente principal con las instrucciones generales de tono y política, un sub-agente de reembolsos con la tool que ejecuta la devolución en el ERP, y un sub-agente de facturación con la tool que consulta y reenvía facturas. El agente principal recibe la consulta, decide qué sub-agente necesita y delega. Si la consulta es ambigua, pide aclaración o escala al equipo humano con un resumen del hilo. Todo el flujo corre en PHP, con streaming de respuesta para que el usuario vea el texto llegar poco a poco, y sin depender de un servicio de orquestación externo.

Para probarlo sin gastar un euro, basta con apuntar el provider a Ollama en local, como muestra la configuración anterior. El mismo código que en desarrollo corre contra un modelo local funciona en producción contra un proveedor comercial.

Conclusión

El AI SDK de Laravel 13 convierte la IA en una capacidad más del framework: agentes como clases PHP, providers intercambiables con una línea de configuración, sub-agentes para orquestar tareas complejas y búsqueda semántica integrada con Eloquent. Si aún no lo has probado, la mejor forma de empezar es montar un agente pequeño con Ollama y dejar que el SDK haga el trabajo pesado. Y si quieres repasar el resto de novedades de la versión, en este blog tienes la guía de actualización de Laravel 13 y una introducción a la IA local con Ollama.