Ahora asegúrate de que nada rodea la frontera.
Quienes llaman obtienen un agente del contenedor o construyen uno con el espacio de trabajo, y esa es la única forma de llegar a un modelo:
$copy = SiteCopywriter::make(workspace: $workspace)
->prompt($brief);
Quien llama no puede ver qué proveedor respondió, no puede construir un proveedor con otra clave y no puede olvidarse del timeout, porque el timeout está en la clase.
Lo que sí puede hacer todavía, un viernes ajetreado, es llamar a Http::post() contra la URL de un proveedor desde un controlador. Así que déjalo escrito como una regla que un test pueda hacer cumplir:
arch('only the AI layer builds providers')
->expect('Laravel\Ai\Ai')
->toOnlyBeUsedIn('App\Ai');
arch('nobody calls a provider by hand')
->expect('App')
->not->toUse(['OpenAI', 'Anthropic']);
Dos tests de arquitectura, unos milisegundos cada uno. El primero mantiene la construcción de proveedores, y con ella todas las credenciales, dentro de app/Ai. El segundo impide que se instale y se use el SDK de una empresa al lado de la frontera. Ninguno comprueba tu criterio. Los dos comprueban que sigue habiendo un solo lugar donde mirar.
Cuándo sigues escribiendo el tuyo
Hay una parte del sistema conductor que no pasa por el SDK, y deberías saber por qué antes de encontrártela.
El agente del prefacio habla directamente con la Messages API de Anthropic, a través de un cliente escrito a mano. Usa una función del proveedor, un conector que permite que el propio proveedor llame a nuestro servidor MCP, que queda fuera de lo que modela un SDK neutral respecto al proveedor. También depende de motivos de parada que una abstracción neutral tiene que fusionar. El capítulo 8 muestra ese bucle y lo que cuesta ser su dueño.
La regla es sencilla. Usa el SDK salvo que necesites algo que no sabe expresar. Cuando sea así, pon el cliente escrito a mano detrás del mismo tipo de frontera: una clase, un solo lugar para la credencial, el timeout y la política de reintentos, y un test de arquitectura que lo mantenga ahí. La frontera siempre fue lo importante. El SDK solo significa que normalmente no tienes que construirla.
Lo que esto nos dio
Haz balance, porque es fácil mirar unas pocas clases pequeñas y concluir que has escrito ceremonia.
Ahora tienes un solo lugar donde se describe cada uso de un modelo, con su costo y su límite de tiempo en el archivo. Un solo lugar donde las credenciales se resuelven por inquilino, con un error que dice dónde mirar. Una política de reintentos que no puede cobrarte dos veces una tarde lenta. Un test que falla el día que alguien lo rodee todo.
Y tienes dónde poner la siguiente lección. Esa es la parte que se acumula. Todo lo que enseña el resto de este libro (validación de la salida estructurada, techos de costo, cancelación, observabilidad) encaja limpiamente porque hay una frontera donde encajar. Sin ella, cada una de esas cosas se convierte en un cambio en cada punto de llamada.
Lo que todavía no resuelve
A estas alturas el endpoint es honesto pero ingenuo. Confía en que la respuesta tiene la estructura que necesita la funcionalidad, lo cual todavía no es cierto. No tiene techo para el número de llamadas que puede hacer un inquilino. Corre dentro de la petición HTTP, que no sobrevivirá a un turno largo. Y su prompt es una constante que nadie ha mirado, que es el tema del capítulo 3.
Cada una de esas cosas es un capítulo, y cada una es un cambio dentro de esta frontera y no a lo largo de toda tu aplicación.
Decisiones de este capítulo
- Usa el SDK y lee sus valores por defecto como preguntas. Cada valor por defecto es una decisión tomada para nadie en particular.
- Una clase de agente por cada cosa que quiere la aplicación. Ponle el nombre del uso, nunca el del modelo.
- Construye el proveedor por inquilino, a partir de una credencial guardada, sin valor de reserva compartido.
- Falla en la frontera con tu propio mensaje, y con un código de estado que diga que falta la dependencia.
- No reintentes nunca un timeout. El proveedor sigue generando, y te cobrará las dos respuestas.
- Mantén un solo camino de entrada, y deja que un test de arquitectura lo vigile.