La frontera

Lo más valioso de este capítulo es lo poco llamativo que es.

Vamos a construir un endpoint que envía un prompt a un proveedor y devuelve lo que vuelve. No tiene nada de ingenioso. Lo que tiene, en cambio, es una frontera: un solo lugar donde se describe al proveedor, una clase por cada cosa que la aplicación quiere de un modelo y un único conjunto de decisiones sobre credenciales, timeouts y reintentos que toda futura funcionalidad de IA hereda gratis.

Si te equivocas aquí, lo pagarás en cada capítulo que sigue. Si aciertas, la mayoría de los capítulos restantes se vuelven pequeños.

Empieza por el lugar equivocado, brevemente

Esto es lo que casi todo el mundo escribe primero, y vale la pena mirarlo con honestidad, porque no es una tontería. Simplemente está sin terminar.

public function generate(Request $request): JsonResponse
{
    $response = Http::withToken(
        config('services.openai.token')
    )->post('https://api.provider.example/v1/responses', [
        'model' => 'some-model',
        'input' => $request->input('prompt'),
    ]);

    return response()->json([
        'content' => $response->json(
            'output.0.content.0.text',
        ),
    ]);
}

Funciona. En un buen día funciona siempre.

Lo que le falta son todas las decisiones que todavía no has tomado. No hay timeout, así que un proveedor lento retiene este worker hasta que PHP se rinde. No se comprueba que la credencial exista, así que una vacía se envía como un bearer vacío y vuelve como un error de autenticación que te culpa de algo que no hiciste. Nada limita lo que puede costar la respuesta. La URL del proveedor y la forma de su payload están soldadas a un controlador, así que el día que añadas un segundo proveedor, o el día que este cambie el nombre de un campo, estarás editando controladores.

Y, lo que es más grave, no hay dónde poner la siguiente decisión. Cuando aprendas algo sobre cómo llamar a este proveedor, esta forma no te da ningún lugar donde dejarlo escrito.

Instala el SDK y luego decide todo lo que él decidió

Laravel trae ahora un paquete oficial exactamente para esta capa.

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

El AI SDK te da una abstracción de proveedor para una docena de empresas, clases de agente, salida estructurada, herramientas, streaming, colas, conmutación por error y simulaciones para tus tests. Hasta hace poco, un capítulo como este construía a mano un Manager y un driver para conseguir lo primero de esa lista. Ya no hace falta, y no deberías hacerlo. Una frontera de proveedor que mantienes tú es una frontera que tienes que poner al día con los cambios de cada empresa, y ahora eso lo hace por ti el equipo del framework.

Lo que el SDK no puede hacer es tomar tus decisiones. Tiene que venir con valores por defecto, y cada valor por defecto es una decisión que alguien tomó sin conocer tu producto. Léelos como una lista de preguntas:

Ninguno de esos valores está mal. Cada uno es una respuesta razonable para nadie en particular. Este capítulo sustituye los que importan por respuestas pensadas para ti, y el resto del libro sigue haciéndolo.