Hay un momento concreto en el que un sistema de IA deja de ser un experimento y se convierte en un problema de ingeniería real: cuando el agente llama a tu API y no entiende lo que le devuelves. No porque el modelo sea torpe. Sino porque tu API nunca fue diseñada para él.
Durante años, los equipos de backend han diseñado contratos —endpoints, esquemas de error, códigos de estado, mensajes de respuesta— pensando en un único tipo de cliente: el humano que abre el terminal, lee el 429, y decide qué hacer. Ese humano tiene juicio. Interpreta. Infiere. Un agente de IA no hace ninguna de esas tres cosas de la misma manera. Sigue instrucciones. Reintenta. Y si el contrato es ambiguo, improvisa de formas que destruyen datos o colapsan colas.
El resultado es predecible: agentes en producción que funcionan en demo y se degradan silenciosamente en real. No es un problema de prompts. Es un problema de arquitectura. Y los equipos que lo están resolviendo no están reescribiendo los modelos: están reescribiendo el backend.
Las APIs actuales hablan a humanos; los agentes necesitan contratos legibles a máquina, con semántica explícita y sin ambigüedad.
Los errores más peligrosos no son los que rompen el agente: son los que el agente interpreta mal y sigue ejecutando.
Diseñar para agentes no es añadir una capa encima; es replantear qué información necesita un cliente no humano para tomar decisiones correctas.
El problema: Contratos diseñados para ojos, no para máquinas
Cuando un desarrollador diseña un endpoint, piensa en quién lo va a consumir: otro desarrollador, una interfaz web, una app móvil. Todos tienen algo en común: hay un humano en el bucle que puede interpretar una respuesta inesperada. Si el servidor devuelve un HTTP 422 con un mensaje de validación críptico, el desarrollador lo lee, lo entiende y lo corrige. Si devuelve un 200 con un cuerpo vacío porque la operación fue parcialmente exitosa, el desarrollador lo detecta en los logs y lo reporta.
Un agente de IA no hace nada de eso. Recibe la respuesta, la interpreta según el esquema que tiene en contexto, y decide su siguiente acción. Si el contrato es ambiguo —si el mismo código 200 puede significar éxito completo, éxito parcial o "ya lo procesaremos después"— el agente elige una interpretación. Y esa interpretación puede ser catastrófica.
El artículo que circuló esta semana sobre el diseño de límites de tasa para clientes máquina lo formula bien: un 429 tiene dos lectores, el humano que debuggea y el bucle de reintento que parsea. La mayoría de las APIs solo están escritas para el primero. Esto no es un problema menor cuando el segundo es un agente autónomo que decide cuántas veces reintentar, con qué backoff, y si la operación fracasada fue suficientemente importante como para notificarlo hacia arriba en la cadena de decisión.
El paralelismo con el fallo de software del Gran Premio de Bahréin es revelador: los pilotos —usuarios expertos— quedaron "sin poder hacer nada" porque el sistema que controlaba funciones críticas actuó de forma inesperada. No hubo fallo catastrófico visible. Hubo degradación silenciosa. Eso es exactamente lo que pasa cuando un agente consume una API que no fue diseñada para él: no explota, simplemente deja de hacer lo que se esperaba, y nadie lo ve hasta que el daño está hecho.
Semántica: Lo que el código de estado no puede decir solo
El problema de fondo es semántico. Los códigos HTTP fueron diseñados para describir el estado de la transacción de red, no la intención del negocio. Un 200 dice "la petición llegó y el servidor respondió". No dice si la operación tuvo el efecto que el llamante esperaba. Un 400 dice "algo en tu petición está mal". No dice si ese "algo" es recuperable, si el agente debe reintentar con datos diferentes, o si debe detener la cadena entera y escalar.
Para un humano, esa ambigüedad es tolerable: lee el mensaje, infiere el contexto, actúa. Para un agente, la ambigüedad es un vector de error. Y cuanto más autónomo sea el agente —cuanto más largo sea su horizonte de planificación, cuanto más acciones encadene antes de esperar confirmación humana— más se amplifica ese error.
Un agente no lee entre líneas. Si el contrato no es explícito, el agente inventa la línea que falta. Y esa línea inventada puede desencadenar diez acciones más antes de que alguien lo note.
La solución no es añadir más texto al campo message de la respuesta de error. Es estructurar la semántica de las respuestas para que sean interpretables a máquina sin ambigüedad. Esto implica varias decisiones de diseño concretas:
Códigos de error específicos del dominio, no solo HTTP genéricos. En lugar de un 400 que engloba todo, un esquema de error que distinga entre "parámetro inválido", "operación no permitida en este estado", "límite de cuota alcanzado transitoriamente" y "límite de cuota alcanzado permanentemente".
Instrucciones de acción explícitas en la respuesta: ¿debe el agente reintentar? ¿cuándo? ¿con los mismos datos o con datos modificados? ¿debe escalar a un humano?
Estado de la operación separado del estado de la petición: saber que la petición fue recibida no es lo mismo que saber que la operación tuvo el efecto esperado.
Esto no es ciencia ficción. Es lo que hacen bien las APIs mejor diseñadas del mercado: Stripe distingue entre errores de tarjeta, errores de red, errores de fraude y errores de configuración, cada uno con un código, una descripción y una acción recomendada. Ese nivel de granularidad fue pensado para desarrolladores humanos, pero resulta que también funciona perfectamente para agentes. La lección es que diseñar con precisión para humanos es un buen proxy para diseñar para máquinas. El problema es cuando la API fue diseñada con pereza para humanos: el agente lo sufre de forma amplificada.
Idempotencia: El seguro de vida que tu API probablemente no tiene
Si hay un concepto que separa las APIs diseñadas para agentes de las que no lo están, es la idempotencia. Un agente que reintenta no es un bug: es el comportamiento esperado ante incertidumbre. La pregunta es qué pasa cuando ese reintento llega a tu backend.
Si tu endpoint de "crear pedido" no es idempotente, un agente que reintenta ante un timeout puede crear el mismo pedido tres veces. Si tu endpoint de "enviar notificación" no es idempotente, el usuario recibe tres emails. Si tu endpoint de "procesar pago" no es idempotente... el escenario es obvio.
El patrón de la clave de idempotencia
La solución estándar es el patrón de clave de idempotencia: el llamante envía un identificador único con cada operación, y el servidor garantiza que esa operación —con ese identificador— se ejecuta exactamente una vez, independientemente de cuántas veces llegue la petición. Stripe lo lleva usando más de una década. No es una idea nueva. Pero sí es una idea que la mayoría de los backends de pymes no han implementado porque, cuando el cliente era siempre una interfaz web con un humano detrás, la probabilidad de doble envío era baja y el coste de implementar idempotencia parecía mayor que el coste de los casos raros.
Con agentes autónomos, esa ecuación cambia completamente. Un agente que opera en condiciones de red inciertas, con latencias variables y sin confirmación visual de éxito, va a reintentar. Siempre. La pregunta no es si tu backend va a recibir peticiones duplicadas. Es cuándo.
Más allá de la idempotencia: el estado como contrato
Hay una extensión del problema que va más allá de la idempotencia simple: las operaciones de larga duración. Cuando un agente desencadena un proceso que no se completa de forma síncrona —una generación de documento, un cálculo intensivo, una integración con un tercero— necesita saber en qué estado está esa operación en cada momento. No le basta un "202 Accepted". Necesita un mecanismo para consultar el estado, recibir una actualización cuando cambie, o recuperar el resultado cuando esté disponible.
Diseñar ese mecanismo para agentes —con estados explícitos, transiciones claras y señales que el agente pueda interpretar sin ambigüedad— es una decisión de arquitectura que tiene que tomarse antes de escribir el primer endpoint, no cuando el agente ya está en producción y el equipo está investigando por qué la mitad de las operaciones se quedan en estado "procesando" indefinidamente.
Vale la pena leer en paralelo lo que ya publicamos sobre por qué los agentes en producción fallan de formas que los tests no capturan: muchos de esos fallos silenciosos tienen su raíz exactamente aquí, en contratos de API que no fueron diseñados para clientes no humanos.
Arquitectura: Diseñar el backend para el cliente que viene
La conclusión práctica no es "reescribe todas tus APIs". Eso es el tipo de consejo que suena bien en una conferencia y paraliza equipos en la realidad. La conclusión práctica es más quirúrgica: identifica qué operaciones van a ser consumidas por agentes y diseña esas operaciones con un contrato explícito para clientes no humanos. El resto puede seguir siendo como es.
Esa identificación no es trivial. Requiere entender qué parte del flujo de trabajo va a ser automatizada, qué nivel de autonomía va a tener el agente, y qué operaciones son críticas —irreversibles, con efectos externos, con coste económico. Exactamente las mismas preguntas que deberías hacerte antes de decidir qué herramientas orquestar y por qué.
En la práctica, el trabajo suele organizarse en tres capas:
Capa de contrato: esquemas de respuesta versionados, códigos de error con semántica de dominio, instrucciones de acción explícitas. Lo que el agente necesita para interpretar cada respuesta sin ambigüedad.
Capa de garantías: idempotencia en operaciones con efectos externos, gestión de estado explícita para operaciones asíncronas, límites de tasa con información accionable sobre cuándo y cómo reintentar.
Capa de observabilidad: trazabilidad de qué agente ejecutó qué operación, en qué momento, con qué resultado. Sin esta capa, depurar un comportamiento anómalo de un agente es como buscar la causa de un fallo en logs que no registran lo que necesitas ver.
Lo que Room 714 ve en proyectos donde el agente llega tarde a la conversación de arquitectura es siempre la misma secuencia: el prototipo funciona, la demo convence, el equipo lo lleva a producción, y a las dos semanas hay un comportamiento que nadie entiende. Se llama a los de IA, que dicen que el modelo funciona bien. Se llama a los de backend, que dicen que las APIs devuelven lo correcto. Y ambos tienen razón. El problema está en el espacio entre los dos: el contrato que nadie definió con precisión porque nadie pensó que el cliente iba a ser no humano.
La deuda técnica más cara no es la del código que se escribe mal. Es la del contrato que se asume implícito y nadie escribe.
Cambiar eso no requiere meses ni grandes migraciones. Requiere hacer las preguntas correctas antes de que el agente esté en producción: ¿qué necesita saber este cliente para actuar bien? ¿qué pasa si esta operación llega dos veces? ¿cómo sabe el agente que la operación de larga duración ha terminado, y con qué resultado? ¿qué hace si no lo sabe?
Son preguntas de ingeniería, no de IA. Y su respuesta determina si el agente en producción es una ventaja operativa o una fuente sistemática de incidentes.
Si estás en ese punto de inflexión —el agente ya existe, el backend no estaba preparado, y el equipo está parcheando en lugar de diseñando— en Room 714 podemos ayudarte a diagnosticar exactamente dónde está la ruptura y qué cambiar primero. Nuestro trabajo en desarrollo de producto para equipos internos incluye exactamente este tipo de revisión de arquitectura: sin reescrituras innecesarias, con decisiones quirúrgicas sobre qué contratos necesitan evolucionar y cuáles pueden quedarse como están. Si quieres empezar por ahí, la primera conversación no tiene coste.
