Integrar IA en Laravel con una capa unificada y complejidad gradual

Cuando metes IA en una aplicación real, el primer riesgo no es el prompt. Es el acoplamiento. Si tu código importa el SDK de un proveedor y además parsea su formato de respuesta, cambiar de modelo deja de ser una decisión de configuración y se vuelve una refactorización. Ahí empiezan los costos evitables: pagas más, tardas más en probar opciones y te cuesta reaccionar cuando un proveedor cambia, falla o deja de convenirte.

Laravel ya tiene una forma práctica de evitarlo. El SDK de IA de Laravel expone una API unificada para hablar con proveedores como OpenAI, Anthropic o Gemini, y además cubre agentes con herramientas, salida estructurada y embeddings con la misma interfaz. La consecuencia útil para tu arquitectura es simple: el proveedor deja de estar escrito en el código de la aplicación. [132]

Empieza por la abstracción, no por las funciones avanzadas

La regla transferible es separar tu lógica de aplicación del proveedor desde el primer día. La razón no es teórica. En este ecosistema cambian cuatro cosas con frecuencia suficiente como para diseñar contra ellas: un proveedor se cae, cambian los precios, aparece un modelo con mejor relación calidad-precio y las APIs evolucionan. La respuesta a las cuatro es la misma: una capa de abstracción entre tu aplicación y el proveedor, igual que un ORM —una capa que traduce una interfaz común a un backend concreto— te separa de una base de datos específica. [92]

En Laravel, esa capa ya existe en el SDK. Por eso conviene usarla incluso si hoy sólo piensas en un proveedor. El beneficio no aparece cuando todo sale bien. Aparece cuando quieres cambiar un modelo de texto, mover embeddings a otro proveedor o combinar varios servicios sin reescribir clientes HTTP. El corpus lo plantea de forma directa: el texto puede venir de un proveedor, los embeddings de otro y el reordenado de un tercero, todo configurado en el mismo sitio y con la misma forma. Cambiar de modelo de texto puede quedarse en una línea de configuración. [122]

Si además te preocupa la operación, el mismo enfoque permite definir una cadena de respaldo en configuración. El corpus muestra este ejemplo:

// El primero es el titular; los siguientes entran si el titular no responde.
'default' => ['anthropic', 'openai'],

Ese respaldo tiene una regla clara: conmutar sólo por fallos de infraestructura, como límite de tasa, caída de conexión, saturación o crédito agotado. No conviene usarlo para “arreglar” errores de contenido, como un esquema incumplido o una cita inventada, porque otro proveedor puede repetir el problema con otro estilo. [93]

Integra donde ya operas, pero aísla los dominios

Otra decisión práctica es dónde vive el módulo de IA. Si ya tienes una aplicación Laravel con autenticación, despliegue y operación resueltos, integrar ahí mismo puede ser la opción más barata de mantener. El criterio transferible es este: si separar el módulo te obliga a duplicar autenticación, despliegue o administración sin ganar una frontera de negocio real, conviene integrar y aislar. [67]

El aislamiento sigue siendo necesario. El corpus da un ejemplo concreto: un módulo bajo /studio, detrás de una puerta de acceso, con separación entre el material público y el corpus interno, incluso con tablas de etiquetas distintas. [67] Eso enseña el principio, no el patrón universal. La ruta /studio, las tablas exactas y la forma de autenticación son detalles locales. Lo reusable es otra cosa: compartir infraestructura cuando ya la tienes, y separar los dominios de datos para no mezclar el contenido publicado con el conocimiento recuperable.

Esa separación importa porque el sistema trabaja con capas distintas. El material fuente, el conocimiento derivado y el artefacto publicado tienen ciclos de vida distintos. Si los mezclas en el mismo modelo mental, luego cuesta saber qué se regenera, qué se versiona y qué debe permanecer inmutable. [100]

La progresión correcta: clase mínima, luego esquema, luego herramientas

No hace falta empezar con un agente lleno de capacidades. De hecho, el corpus recomienda lo contrario. Para un proyecto nuevo, la secuencia de arranque es: instalar el paquete y migraciones, configurar las claves y el proveedor por defecto, escribir el primer agente como una clase con instrucciones, añadir esquema cuando la salida tenga que consumirse por código y dejar las herramientas para cuando el agente realmente necesite decidir qué hacer. [135]

Esa progresión evita meter complejidad antes de tener una necesidad concreta.

Un agente mínimo en Laravel puede ser sólo esto:

<?php

namespace App\Ai\Agents;

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

class SalesCoach implements Agent
{
    use Promptable;

    /**
     * Get the instructions that the agent should follow.
     */
    public function instructions(): string
    {
        return 'You are a sales coach, analyzing transcripts and providing feedback.';
    }
}

Ese diseño tiene una ventaja operativa que vale la pena conservar. Las instrucciones viven en un método, no incrustadas en el punto de llamada. Eso permite cargarlas desde un archivo versionado y saber después con qué versión exacta se produjo un resultado. [133]

¿Cuándo añadir esquema? Cuando otro pedazo de código va a consumir la salida y necesita una forma estable. El corpus también deja ver por qué eso importa en un sistema de producción: una salida que debe revisarse completa a mano no ahorra trabajo. El objetivo es que la revisión humana sea una parte menor del flujo, y para eso la salida tiene que llegar estructurada, citada y con huecos declarados. [100]

¿Cuándo añadir herramientas? Cuando el modelo debe decidir el procedimiento mismo. Si tu flujo ya tiene un orden fijo, no ganas nada dándole esa decisión al modelo. En el corpus, la regla es nítida: cadena fija cuando el procedimiento se conoce; agente cuando lo que hay que decidir es el procedimiento. [49] Llevado a Laravel, eso significa que no conviene meter tools —funciones que el agente puede invocar— para pasos que tu código ya sabe ejecutar en secuencia.

También hay un motivo de costo. En un bucle agéntico, el gasto crece por más llamadas, más contexto reenviado y más iteraciones. En casos complejos, un factor de cinco frente a un pipeline equivalente es realista. [96] Si tu problema se resuelve con una cadena fija, empieza por ahí.

Material runnable que sí puedes reproducir hoy

Aquí sí hay material ejecutable en el corpus. Lo primero es la instalación básica del SDK:

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

Según el corpus, la migración crea, entre otras cosas, las tablas donde se persisten las conversaciones de agente. Eso permite reanudar una conversación pausada, base de cualquier flujo con aprobación humana. [133]

También puedes generar embeddings —vectores numéricos que representan texto para búsqueda o similitud— con el SDK directamente:

use Laravel\Ai\Embeddings;

$response = Embeddings::for([
    'Napa Valley has great wine.',
    'Laravel is a PHP framework.',
])->generate();

$response->embeddings; // [[0.123, 0.456, ...], [0.789, 0.012, ...]]

Y desde una cadena:

use Illuminate\Support\Str;

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

Con eso ya puedes probar la parte más concreta de una integración RAG: generar embeddings desde Laravel sin escribir un cliente propio para un proveedor. [135]

Eso no significa que ya tengas un RAG completo. El propio corpus marca la frontera. Antes de montar recuperación, pregúntate si el conocimiento necesario cabe completo en la ventana de contexto. Si cabe y es acotado, pasar todo el contexto puede ser más barato, más rápido y más fácil de depurar. La recuperación se paga cuando el corpus deja de caber o cuando elegir bien qué entra mejora calidad y costo. [9] [11]

Si tu proyecto apenas empieza, esa pregunta te puede ahorrar una capa entera de complejidad.

1. Instala el SDK y publica su configuración.
2. Corre las migraciones.
3. Configura tus claves y el proveedor por defecto.
4. Crea un agente mínimo como clase con instrucciones.
5. Prueba generación de embeddings con uno de los ejemplos reproducidos arriba.
6. Añade esquema sólo si otro código necesita consumir la salida.
7. Añade herramientas sólo si el modelo debe decidir acciones y no sólo producir texto.