Siete lecciones de llevar agentes de IA a producción

Llevo tiempo trabajando en una plataforma multiagente en producción: decenas de agentes especializados con más de 270 herramientas conectadas. La demo funcionó el primer mes. Todo lo demás lo aprendimos después, casi siempre por las malas. Estas son las siete lecciones que más me han costado.

1. Los tests verdes no significan cubierto

Tuvimos un bug latente diez días con la suite entera en verde. Un cambio de significado en un identificador rompió un proceso de fondo que nadie testeaba, porque los tests cubrían la capa obvia y el fallo vivía en otra. Desde entonces la pregunta no es «¿pasan los tests?» sino «¿toca este test el camino que de verdad puede fallar?».

2. Un invariante que rompe el build vale más que la disciplina

«Acordarse de actualizar el otro sitio» no escala. Lo que escala es un test estructural que falla la build cuando alguien viola la regla: que todo componente registrado cumpla el contrato, que el esquema y el handler no diverjan. Es la diferencia entre vigilar un error y hacerlo imposible por construcción.

3. A los agentes se les evalúa por resultado, no por camino

Un agente puede resolver la misma tarea con secuencias de herramientas distintas, y las dos valer. Si tu eval comprueba la secuencia exacta, tendrás falsos rojos cada semana. Evaluamos el resultado final contra un conjunto dorado que sale de fallos reales de producción: cada bug reportado se convierte en un caso de eval. El bug te lo comes una vez; la regresión, nunca más.

4. El contexto es un recurso finito y se gestiona como tal

Con conversaciones largas y herramientas que devuelven kilobytes, la ventana de contexto se agota antes de lo que crees. Hay que decidir qué se compacta, qué se pagina y qué se descarta, y hacerlo con criterio auditable. La gestión de contexto no es fontanería: es diseño de producto.

5. Los errores del proveedor se cuentan tal cual

Si la API de turno devuelve «Calendar API not enabled in project 12345» y tú lo tapas con un «error de autenticación, reconecta», el usuario reconectará cuatro veces y el error seguirá. Nos pasó. El mensaje literal del proveedor va al usuario o al modelo, y la sugerencia de acción se añade aparte. Sustituir información por prosa amable es un bug.

6. Las herramientas también tienen presupuesto

Con 270 herramientas, cada descripción entra en el prompt en cada turno. Descripciones infladas significan tokens quemados y modelos confundidos. Las tratamos como se trata una API pública: compactas, consistentes y con revisión. Y las combinaciones raras del proveedor las resuelve el servidor, no el agente: pedirle al modelo que recuerde que cierto campo es obligatorio solo cuando hay recurrencia es apostar a perder.

7. La observabilidad va antes que la elegancia

Cuando algo falla en un sistema agéntico, la pregunta es siempre la misma: ¿qué vio exactamente el modelo y qué respondió? Sin trazas de cada llamada, con su prompt y su respuesta, estás depurando a ciegas. Primero se instrumenta, luego se refactoriza.

El resumen honesto

Nada de esto es exótico: es ingeniería de toda la vida aplicada a un componente no determinista. La parte de IA es la que menos guerra da; la guerra está en los contratos, los límites y la memoria de los errores. De eso último, de darle memoria a los agentes, hablo en otro post.