El backend en la era de los agentes de IA

Durante años hemos diseñado backends pensando en dos tipos de cliente: un frontend que controlamos y, a veces, un desarrollador externo que lee la documentación con calma, escribe una integración y la deja funcionando durante meses.

Está apareciendo un tercer cliente que no se parece a ninguno de los dos: un agente de IA que descubre tu API sobre la marcha, decide qué llamar en función de un objetivo y lo hace en nombre de una persona que no está mirando.

Tesis

Mi tesis es sencilla: si una parte creciente de tus usuarios llega a través de agentes, tu API deja de ser un detalle de implementación y pasa a ser tu producto. La interfaz que importa ya no es la pantalla, sino el contrato.

Eso no significa reescribir nada. Significa que muchas cosas que siempre fueron “buenas prácticas” pasan a ser requisitos. Y que algunas suposiciones, como que al otro lado hay un humano que lee los errores, dejan de ser ciertas.

APIs pensadas para máquinas que razonan

Un agente no es un script. Un script hace siempre lo mismo; un agente interpreta. Lee la descripción de un endpoint, decide si le sirve y construye la llamada. Eso cambia qué hace buena a una API.

La documentación es parte de la interfaz

Para un agente, la descripción de un endpoint y de sus parámetros es literalmente el material con el que decide qué hacer. Un nombre ambiguo o un parámetro sin explicar no es una molestia: es una llamada equivocada.

Lo que antes era documentación para humanos pasa a ser contrato ejecutable: esquemas precisos, descripciones que dicen para qué sirve cada operación y cuándo no usarla, y ejemplos reales.

Los errores tienen que enseñar

Un 400 Bad Request sin más es inútil para un agente. Un error que dice qué campo falla, por qué y qué valores son válidos le permite corregirse en el siguiente intento sin ayuda.

  Mal:   400 { "error": "invalid request" }

  Bien:  400 { "error": "invalid_date_range",
               "message": "'to' debe ser posterior a 'from'",
               "field": "to",
               "hint": "Rango máximo: 90 días" }

Esto siempre fue una buena práctica. Con agentes, marca la diferencia entre una tarea que se completa y una que se abandona tras gastar diez llamadas.

Operaciones con intención, no solo CRUD

Un agente que tiene que encadenar cinco llamadas genéricas para “reservar una cita” tiene cinco oportunidades de equivocarse. Una operación que expresa la intención completa, con sus validaciones dentro, reduce los errores y facilita entender qué ha pasado.

No defiendo abandonar las APIs de recursos, sino añadir una capa de operaciones de negocio para lo que un agente va a querer hacer de verdad.

Idempotencia y confirmación

Los agentes reintentan, a veces sin que nadie lo decida explícitamente. Cualquier operación que cambie algo debería aceptar una clave de idempotencia, para que repetirla no duplique un pedido o un pago.

Y para lo que es irreversible, tiene sentido un patrón en dos pasos: el agente propone la acción, el sistema devuelve qué va a pasar, y la ejecución requiere una confirmación explícita, idealmente de la persona.

Límites, coste y abuso

Un humano hace clic unas pocas veces por minuto. Un agente puede hacer cientos de llamadas para resolver una sola tarea, sobre todo si se equivoca y lo vuelve a intentar.

Eso cambia cómo pienso los límites:

Antes	Con agentes
Límite por IP o por usuario	Límite por agente y por la persona en cuyo nombre actúa
Peticiones por minuto	Peticiones y coste por tarea (no todas las llamadas pesan igual)
Bloquear el abuso	Distinguir el abuso del agente torpe que reintenta en bucle
Errores 429 genéricos	429 con Retry-After y el motivo, para que el agente espere en lugar de insistir

La autenticación también cambia. Un agente no debería usar las credenciales completas de una persona, sino permisos delegados, acotados y revocables: puede leer el calendario pero no borrar eventos; puede preparar un pedido pero no pagarlo. Los modelos de OAuth con permisos finos, que muchas APIs ya tienen, se vuelven la norma en lugar de la excepción.

Y hay un riesgo nuevo que no tenían los clientes clásicos: el agente puede ser manipulado por el contenido que lee. Si tu API devuelve texto que viene de otros usuarios, ese texto puede contener instrucciones dirigidas al agente. El backend no puede resolver eso solo, pero sí puede reducir el daño: permisos mínimos, confirmación para lo irreversible y nada de acciones peligrosas por defecto.

Observabilidad cuando el cliente no es humano

Hoy, cuando algo falla, sueles poder reconstruir lo que hizo el usuario: una sesión, unos clics, una secuencia razonable. Con un agente, la secuencia puede ser larga, extraña y perfectamente válida a la vez.

Lo que me parece imprescindible:

• Identificar al agente y a la persona en cada petición, por separado. Saber que fue “el asistente X actuando para el usuario Y” es la base de todo lo demás.
• Agrupar las llamadas por tarea. Un identificador que el agente propague en todas las llamadas de un mismo objetivo convierte cien peticiones sueltas en una historia que se puede leer.
• Medir la tasa de éxito por tarea, no por petición. Que el 99 % de las peticiones respondan 200 no dice nada si la mitad de las tareas se abandonan a medias.
• Vigilar los errores que se repiten. Si muchos agentes fallan igual en el mismo endpoint, el problema probablemente no está en los agentes, sino en tu contrato.

  tarea "reservar cita" (task_id=abc)
   ├─ GET  /availability        200
   ├─ POST /bookings            400 invalid_date_range   ◀─ ¿error de contrato?
   ├─ POST /bookings            200  (idempotency-key=k1)
   └─ POST /bookings/confirm    200

Qué haría ya hoy

No creo que haga falta esperar a que esto se generalice para prepararse. Casi todo lo que propongo mejora la API también para los humanos:

1. Revisar los errores de los endpoints más usados para que digan qué falla y cómo arreglarlo.
2. Completar los esquemas y descripciones de la API como si fueran código, porque lo son.
3. Añadir claves de idempotencia a todas las operaciones que crean o cambian algo.
4. Separar permisos en ámbitos pequeños, pensando en credenciales delegadas desde el principio.
5. Añadir un identificador de cliente y de tarea a los logs, aunque al principio solo los use el frontend propio.
6. Diseñar un par de operaciones de negocio para los flujos más habituales, en lugar de obligar a encadenar CRUD.

Nada de esto es nuevo. Lo nuevo es que deja de ser opcional. Durante años, una API mal documentada o con errores confusos se compensaba con un humano paciente al otro lado. Ese humano va a estar cada vez menos presente, y la calidad del contrato pasará a ser la calidad del producto.