Laravel AI SDK 1.0 consolida los agentes en LaravelLaravel AI SDK 1.0 consolida los agentes en Laravel

El problema no era hacer una llamada al modelo

Integrar un modelo de lenguaje en Laravel nunca ha sido especialmente difícil. Lo complicado empieza cuando esa llamada debe consultar datos internos, ejecutar acciones, mantener una conversación, pedir confirmación antes de cambiar algo y responder en tiempo real. Ahí es donde una integración basada en un cliente HTTP y varios servicios sueltos termina acumulando decisiones difíciles de mantener.

Laravel AI SDK 1.0 pone una API propia sobre esos problemas habituales. El paquete no se limita a generar texto: define una estructura para agentes, herramientas, contexto conversacional, salida estructurada y ejecución en segundo plano. Para una aplicación Laravel que necesita IA como parte de un flujo de negocio, esa diferencia importa más que poder cambiar una línea de Http::post(). (laravel.com)

Agentes que viven dentro de la aplicación

El SDK plantea un agente como una clase PHP con instrucciones, herramientas, contexto y, si hace falta, un esquema de salida. Se puede crear con php artisan make:agent y ejecutar mediante prompt(), usando inyección de dependencias al resolverlo con make(). Es un enfoque coherente con Laravel: la lógica del agente puede convivir con modelos Eloquent, políticas, colas y servicios de dominio sin convertir el proyecto en una colección de prompts dispersos. (laravel.com)

Las herramientas son la parte que transforma una conversación en una función útil. Un agente puede exponer clases que implementan Tool, con una descripción, un esquema de parámetros y un método handle() para ejecutar la acción. Eso permite consultar pedidos, buscar documentos, generar informes o preparar cambios en la aplicación sin que el modelo tenga acceso directo e indiscriminado a toda la infraestructura. (laravel.com)

Delegar no sustituye al diseño

También hay soporte para subagentes. Un agente puede devolver otro agente desde su método tools(), delegando una tarea concreta a una clase especializada con sus propias instrucciones, herramientas o proveedor. Puede ser útil, por ejemplo, para separar un asistente general de un agente que evalúa condiciones de reembolso o analiza documentación técnica. (laravel.com)

No lo interpretaría como una invitación a construir organigramas de agentes para cualquier formulario. Cada delegado añade llamadas, contexto y puntos de fallo, además de hacer más difícil seguir el recorrido de una respuesta. La división tiene sentido cuando hay una responsabilidad real y límites claros; para el resto, una herramienta pequeña y bien autorizada suele ser una solución mejor.

Las acciones sensibles deben parar

La aprobación humana es una de las partes más prácticas del SDK. Una herramienta puede implementar Approvable y usar el trait InteractsWithApprovals para pausar una ejecución antes de realizar una acción sensible o irreversible. El agente puede proponer borrar un archivo, cancelar un recurso o modificar un dato, pero la aplicación conserva la decisión final. (laravel.com)

Ese flujo no elimina la necesidad de autorización convencional. Antes de permitir que alguien apruebe una acción, sigue siendo responsabilidad de la aplicación comprobar que esa persona puede acceder a la conversación y a los datos afectados. La documentación además avisa de que las aprobaciones requieren conservar el historial de la ejecución pausada, ya sea con un agente conversacional o aportando los mensajes desde el frontend. (laravel.com)

Conversaciones persistentes sin montar otra capa

El trait RemembersConversations permite almacenar y recuperar automáticamente el historial de un agente. Tras publicar las migraciones y ejecutarlas, el paquete crea sus tablas de conversaciones y mensajes; el agente puede iniciar una conversación con forUser() y retomarla después con continue() o continueOrStart(). Esto reduce bastante el código repetido que suele aparecer al construir un chat persistente. (laravel.com)

Persistir conversaciones no significa que debamos guardarlo todo sin pensar. El historial puede contener datos personales, información comercial o resultados de herramientas, así que hacen falta políticas de retención, controles de acceso y una revisión de qué contexto llega realmente al modelo. Tampoco conviene confiar en que continue() valide por sí solo la propiedad de una conversación: la documentación indica expresamente que esa autorización corresponde a la aplicación. (laravel.com)

Streaming y colas para no bloquear la interfaz

Para respuestas largas, el método stream() devuelve una respuesta que puede enviarse al cliente mientras el modelo genera contenido. También admite then() para trabajar con el resultado completo cuando termina la transmisión. Si la tarea no debe depender de la petición web, queue() permite ejecutar el agente en segundo plano y registrar callbacks para la respuesta o el error. (laravel.com)

Esto no convierte automáticamente un chat en una experiencia robusta. Hay que gestionar reconexiones, estados intermedios, límites de tiempo, errores del proveedor y el comportamiento de las herramientas durante el stream. La ventaja es que el SDK ya contempla esos recorridos, en lugar de obligar a inventarlos sobre una respuesta HTTP convencional.

Un proveedor local sin cambiar la aplicación

Para un homelab, la parte más interesante es el proveedor openai-compatible. La configuración admite un url obligatorio, una clave opcional y un modelo de texto por defecto; después se usa como cualquier otro proveedor nombrado. La documentación menciona explícitamente vLLM y gateways locales entre los endpoints compatibles, mientras que Ollama aparece como proveedor soportado para texto y embeddings. (laravel.com)

// config/ai.php
 
'providers' => [
    'local' => [
        'driver' => 'openai-compatible',
        'url' => env('LOCAL_AI_URL'),
        'key' => env('LOCAL_AI_API_KEY'),
        'models' => [
            'text' => [
                'default' => env('LOCAL_AI_MODEL'),
            ],
        ],
    ],
],

Con esa configuración, una aplicación puede enviar una petición al proveedor local sin quedar atada a una API externa en el código de negocio. La URL puede apuntar a una instancia de vLLM o a un gateway compatible dentro de la red privada, y el proveedor se selecciona al invocar el agente. La clave es opcional en esta configuración, aunque se enviará como token Bearer si se define. (laravel.com)

La letra pequeña

OpenAI-compatible no significa que todos los servidores locales implementen cada capacidad de la misma forma. El SDK declara soporte para generación de texto, streaming, herramientas, salida estructurada, adjuntos de imagen, embeddings y transcripción en este tipo de proveedor, pero el endpoint elegido tiene que ofrecer realmente las rutas y comportamientos necesarios. Antes de diseñar un flujo de producción conviene probar específicamente herramientas, streaming y formatos estructurados con el modelo y servidor concretos. (laravel.com)

Tampoco conviene presentar un proveedor local como una solución gratuita o sin operaciones. Cambia una factura externa por consumo de CPU o GPU, almacenamiento de modelos, observabilidad, actualizaciones y seguridad de red. Si el caso necesita disponibilidad alta, respuestas consistentes o modelos grandes, el homelab puede ser una buena pieza de desarrollo y privacidad, pero no evita tomar decisiones de infraestructura.

Laravel AI SDK 1.0 no resuelve por sí solo la calidad de las respuestas ni protege una herramienta mal diseñada. Lo que sí aporta es una base Laravel reconocible para construir esas piezas con agentes, conversaciones, aprobaciones y proveedores intercambiables. Para mí, ese es el salto relevante: deja de ser una integración experimental aislada y pasa a ser una dependencia razonable para proyectos que necesiten IA dentro de sus procesos.

Fuente del lanzamiento · Documentación oficial