APIs listas para agentes de IA: qué necesita su sistema para que un agente lo use con control

Un cliente le pide a un asistente de IA de su banco que pague el recibo de luz desde su cuenta. El asistente —un agente: un programa que, ante una instrucción, decide por sí mismo qué sistemas llamar y en qué orden— llama a la API de pagos. La respuesta tarda, la conexión se corta. El agente no sabe si el pago salió, así que hace lo que haría cualquier programa: lo intenta de nuevo. Si la API no tiene forma de reconocer que es el mismo pago, el cliente acaba con un cargo doble, una aclaración abierta y una mala opinión de su banco.

Ese escenario no requiere un agente malicioso ni un modelo malo. Basta una API pensada, como casi todas, para un programador que lee la documentación, conoce el negocio y sabe qué hacer cuando algo falla. Un agente puede no tener ese contexto, y entonces convierte cada ambigüedad del contrato en una acción equivocada.

Cambie el pago por la emisión de una póliza, un pedido que descuenta inventario, una transferencia a una billetera digital o una factura que se timbra ante el SAT, y el problema es de la misma familia. Este artículo es para quien responde por esos sistemas en un banco, una fintech, una aseguradora, una cadena de retail o cualquier empresa regulada.

Cada vez más APIs van a tener ese nuevo consumidor. En la encuesta de Postman de 2025 —un proveedor de herramientas de API, con más de 5,700 participantes—, el 24 % de los desarrolladores dijo diseñar sus APIs pensando en agentes; el 60 % las diseña principalmente para humanos [1]. Este artículo explica qué le falta a una API para que un agente la use con control, cuáles de esas piezas ya son estándar y cuáles no, y cómo llegar ahí sin reescribir sus sistemas.

Conectarla no es lo mismo que prepararla

Hoy es fácil «conectar» una API a un agente. El protocolo MCP, que ya explicamos en este blog, y los gateways de varios proveedores —Microsoft, AWS, Google, Kong y Cloudflare, entre otros— pueden convertir un contrato OpenAPI en herramientas que un agente llama [2]. Un contrato, en este contexto, es la descripción formal, legible por una máquina, de lo que hace cada operación de una API y qué acepta.

Convertir el contrato resuelve la conexión, no el control. Un preprint académico revisó 116 servidores MCP oficiales y 80 contratos OpenAPI. En esa muestra, el 92 % de los servidores solo envolvía la API tal como estaba, y exponía una mediana del 19 % de sus operaciones. Lo interesante vino después: cuando los autores corrigieron automáticamente los contratos —descripciones, parámetros, agrupación—, la proporción de herramientas que funcionaban bien subió del 76 % al 94.2 % [3].

La lección: el primer cuello de botella no es el conector, es la calidad del contrato. Convertir 200 operaciones en 200 herramientas no le da a un agente 200 capacidades; le da 200 oportunidades de equivocarse.

Las siete propiedades de una API que un agente puede usar

1. Se explica sola

Un programador puede preguntar qué significa el parámetro type. Un agente, en el mejor caso, lo deduce; en el peor, adivina. Por eso cada operación necesita decir qué hace para el negocio, no solo qué tipos de datos recibe: «Cancela el pago programado si todavía no se ejecuta; los pagos ya ejecutados se revierten por otra operación». OpenAPI 3.2, la especificación vigente para describir APIs, da los lugares para escribirlo: un identificador estable por operación, descripciones, ejemplos y la forma de declarar los avisos que la API manda cuando termina un proceso largo [4]. El preprint citado arriba es justamente evidencia de que reparar esas descripciones mejora el desempeño del agente [3].

Un matiz que casi nadie menciona: la propia especificación de MCP advierte que las descripciones y anotaciones de una herramienta no son confiables salvo que vengan de un servidor de confianza [6]. Una herramienta que dice de sí misma «soy de solo lectura» no se vuelve segura por decirlo. La seguridad se pone en la API, no en la descripción.

2. Es consistente

Si una operación devuelve fechas en un formato y otra en otro, el agente tiene que aprender cada excepción. Y la diferencia entre «no sé quién es usted» y «sí sé quién es, pero no tiene permiso» importa más de lo que parece: ante la primera, el agente intenta renovar su credencial; ante la segunda, debería detenerse o pedir autorización. Una API que las confunde manda al agente a renovar credenciales en círculo, gastando cuotas y llenando bitácoras. Esa diferencia está definida en el estándar HTTP (los códigos 401 y 403, en el RFC 9110) [7], y la guía del IETF para construir sobre HTTP pide no reinventar esos significados [8].

3. Sus errores enseñan a corregir

Cuando una llamada falla, el mensaje de error es la guía más directa que tiene el agente. «Entrada inválida» lo manda a probar al azar; «el monto debe ser mayor a cero y menor que el límite diario de la cuenta» le permite corregirse en un intento.

Esto ya tiene estándar: el RFC 9457 (2023) define un formato de error que una máquina puede leer —tipo de problema, título, estado y detalle, más los campos que cada API necesite— y reemplazó al RFC 7807 [9]. No hace falta inventar un esquema propio; hace falta usar el que ya existe, en todas las operaciones, y decir en cada error si conviene reintentar. Con equilibrio: el error debe ser específico sin exponer el interior del sistema.

4. Reintentar no duplica

Los agentes reintentan; es parte de cómo funcionan. Si una llamada se corta, no saben si la operación se aplicó. En una consulta no pasa nada. En un pago, una póliza o un movimiento de inventario, un reintento puede ejecutar la operación dos veces.

La solución conocida es la llave de idempotencia: el cliente manda un identificador único con cada operación, y si la repite con la misma llave, la API devuelve el resultado original en lugar de ejecutarla otra vez. Antes de implementarla conviene saber dos cosas:

• No es estándar. El borrador del IETF para el encabezado Idempotency-Key llegó a su versión 07 en octubre de 2025 y hoy figura como expirado y archivado, sin haberse convertido en RFC [10]. Por eso cada API tiene que publicar sus propias reglas: cuánto tiempo guarda la llave, cómo compara la petición repetida y qué responde si la misma llave llega con otro contenido o mientras la primera sigue en proceso. El borrador distinguía esos casos con respuestas diferentes [10].
• Lo importante es qué pasa cuando algo falla. Stripe, el referente del tema, guarda el resultado de la primera ejecución aunque haya sido un error del servidor [11]. En palabras simples: si el primer intento quedó en duda, el reintento no vuelve a cobrar; le contesta al cliente «esto quedó así, verifique antes de intentar otra cosa».

Y no todo se debe reintentar. Google, en su guía de diseño de APIs, reintenta automáticamente los errores transitorios —indisponibilidad, plazos vencidos— y considera la cuota agotada como generalmente no reintentable, salvo casos documentados [12]. Si su API no dice qué es reintentable, el agente lo va a adivinar.

5. Responde siempre con la misma forma

Un agente lee texto libre sin problema; lo que le cuesta es una estructura que cambia: un campo que a veces es texto, a veces objeto y a veces no viene. Una lista vacía debe ser una lista vacía, no la ausencia de la lista. Las operaciones que tardan necesitan su propio patrón: responder de inmediato que la petición fue aceptada, con un lugar donde consultar su estado, en vez de dejar al agente esperando.

Y para una empresa regulada, el estado de una operación debería distinguir al menos cinco desenlaces: rechazada, no iniciada, en proceso, completada y resultado desconocido. Ese último es el que más se olvida y el que más problemas causa, porque es justo el que provoca el reintento del ejemplo inicial.

Cuando un trámite toca varias operaciones —un alta de cliente que pasa por tres sistemas, por ejemplo—, la especificación Arazzo permite describir el flujo completo, paso por paso, para que el agente no tenga que deducir el orden [18].

6. Avisa cuánto le queda

Un agente con un error en su lógica puede hacer miles de llamadas en una noche, y cada una consume capacidad de la API y, muchas veces, también tokens del modelo, que alguien paga. Si la API le dice en cada respuesta cuánto le queda de su cuota y cuándo se renueva, el agente puede frenar antes de chocar. Cuando choca, la API puede responder con el código 429 («demasiadas peticiones», RFC 6585) e incluir el encabezado Retry-After para indicar cuándo volver [5][7]. GitHub, por ejemplo, pide esperar ese tiempo y, si no viene, alargar la espera de forma creciente; insistir puede bloquear la integración [14].

El estándar de encabezados para comunicar la cuota sigue en borrador en el IETF, en su versión 11 de mayo de 2026, y su forma ha cambiado entre versiones [15]. Lo sensato es elegir una convención, documentarla y aplicarla igual en todas las operaciones.

7. Avisa antes de retirarse

Las APIs cambian. Un programador lee el correo que anuncia el retiro de una versión; un agente no. Hoy eso ya tiene estándar: el encabezado Deprecation se publicó como RFC 9745 en 2025, y el encabezado Sunset, que indica cuándo dejará de responder, como RFC 8594 [16][17]. Con ellos, un agente puede detectar a tiempo que debe moverse a la nueva versión.

Qué ya es estándar y qué no

Esta tabla es lo que más conviene tener a la mano antes de diseñar. Mezclar un borrador con un estándar es la forma más rápida de construir algo que habrá que cambiar.

Estándar: RFC publicado por el IETF en su ruta de estándares. Borrador: trabajo en curso que puede cambiar o abandonarse. RFC informativo: guía que no obliga. Ninguno es, por sí solo, una obligación legal.

Las filas marcadas como estándar no admiten mucho debate: son la referencia que conviene seguir. Las filas en borrador son decisiones de diseño que cada empresa tiene que tomar y documentar, y son las que más varían de una organización a otra.

Cómo se ve en su industria

Las siete propiedades son las mismas en todas partes; lo que cambia es qué se rompe cuando faltan. Cinco escenarios, uno por industria, ilustrativos y sin cliente:

En todos los casos se repite el patrón: una API con estados explícitos reduce el riesgo de que un reintento haga daño, y trabaja junto con los controles de identidad, autorización y conciliación que veremos enseguida.

La seguridad no se le puede dejar al modelo

Aquí está el punto que más pesa para un banco, una fintech, una aseguradora, una cadena de retail con datos de millones de clientes o cualquier empresa regulada: un agente puede ser engañado por los datos que lee. Un correo, un documento o la respuesta de otra herramienta pueden traer instrucciones escondidas, y el agente puede seguirlas. Se le llama inyección indirecta de instrucciones, y OWASP la coloca como el primer riesgo de las aplicaciones con modelos de lenguaje [22].

Lo incómodo es que no hay detector infalible, y la propia OWASP lo reconoce [22]. Un grupo de investigadores atacó doce defensas publicadas, varias con éxito reportado cercano a cero, y superó el 90 % de éxito contra la mayoría cuando adaptó sus ataques [23]. El instituto de seguridad de IA del NIST encontró algo parecido en un entorno simulado de oficina: frente al mismo modelo, el mejor ataque conocido tuvo éxito en el 11 % de los casos y un ataque nuevo, en el 81 % [24]. La lección no es una tasa general de vulnerabilidad: es que una defensa probada contra ataques conocidos no está probada. Y el caso EchoLeak, en un asistente corporativo de uso masivo, mostró que un solo correo, sin que nadie hiciera clic, podía sacar datos internos [25][34].

La conclusión práctica no es «no use agentes». Es contener el daño en la API, que sí controla, en lugar de prometer que el modelo nunca se va a equivocar. Empieza por separar lo que un agente puede hacer en tres niveles:

Y sobre esa separación, cuatro controles que viven en la API, no en el modelo:

• Identidad propia para cada agente. Una credencial de máquina, no la de una persona. Cuando el agente actúa a nombre de un cliente o un empleado, el intercambio de tokens permite representar quién delegó en quién [21]; conservar esa constancia es una decisión de configuración y de bitácora que hay que exigir. Y las credenciales se pueden atar a quien las usa, para que una credencial robada no le sirva a otro [19][20]. El incidente de la integración Salesloft Drift, en 2025, fue justo eso: credenciales de una integración robadas y usadas con consultas que parecían válidas [26]. Es la misma disciplina de accesos que conviene aplicar a las personas, y la explicamos en Controlar quién entra.
• Permisos mínimos por operación. Un agente que consulta inventario no necesita poder borrar clientes.
• Montos, límites y reglas de autorización en la API, fuera del modelo.
• Bitácora de cada acción: qué agente, a nombre de quién, con qué permiso, qué pidió, quién aprobó y qué pasó.

La especificación de MCP va en la misma dirección: cuando se usa su autorización, exige validar que la credencial fue emitida para ese servidor y prohíbe reenviar la credencial del usuario a otros servicios [6].

En México, además, hay ley

Dos normas cambian la conversación. La primera aplica a todas las industrias; la segunda, al sector financiero. No sustituyen la revisión de su área jurídica, pero conviene tenerlas en el radar desde el diseño:

• Para banca y fintech, la Ley Fintech obliga, en su artículo 76, a compartir datos por medio de APIs estandarizadas, en tres capas: datos abiertos, agregados y transaccionales. El desarrollo regulatorio no es uniforme: depende del tipo de entidad, del dato y de la autoridad. Banxico, por ejemplo, emitió en 2020 disposiciones que contemplan las tres capas para las sociedades de información crediticia y las cámaras de compensación [13]. Y el texto de la ley ya trae un control que es exactamente lo que un agente exige: el acceso de un tercero se interrumpe tan pronto el cliente retira su consentimiento, se detectan vulnerabilidades o el tercero incumple, y la interrupción se notifica a la autoridad en no más de dos horas [27]. Para las interfaces sujetas a ese artículo, poder revocar un acceso sin maniobras manuales complicadas no es un lujo; para las demás, es un control que vale la pena tener.
• Para todas las industrias —seguros y retail incluidos—, la nueva Ley Federal de Protección de Datos Personales en Posesión de los Particulares, publicada en marzo de 2025, da al titular el derecho de oponerse a un tratamiento automatizado que, sin intervención humana, evalúe aspectos como su situación económica o su comportamiento y le cause efectos jurídicos no deseados [28]. Si un flujo con agentes hace ese tipo de evaluación, hay que revisarlo frente a esa regla. Y en cualquier caso, la ley pide medidas de seguridad proporcionales al riesgo: el uso de datos por un agente es parte del tratamiento, y entra al mismo análisis de riesgos y controles [28].

En la mayoría de los casos, sus sistemas no se reescriben: se les pone una fachada

Ningún banco va a reescribir su core, ninguna aseguradora su sistema de pólizas y ninguna cadena su ERP o su punto de venta para que los use un modelo de lenguaje, y en la mayoría de los casos no hace falta. El camino que recomienda la literatura de modernización —y el que siguen los propios fabricantes— es una fachada: una capa que expone al agente operaciones de negocio claras —consultar un saldo, cotizar una póliza, registrar una devolución, iniciar un pago, consultar el estado de una factura— y que por dentro traduce al lenguaje del sistema existente [29].

Tres decisiones definen si esa fachada ayuda o estorba:

• Qué se expone. Operaciones de negocio estrechas, no tablas ni transacciones internas genéricas. Un agente con acceso a «ejecutar cualquier transacción» no es un agente con capacidades: es un riesgo.
• Qué responsabilidades quedan en la fachada y cuáles en el sistema de origen. La guía de Microsoft sobre este patrón advierte que la capa de traducción agrega latencia y otro servicio que operar, y recomienda no convertirla en el lugar de las reglas de negocio [29]; si termina decidiendo lo que antes decidía el core, se vuelve otro sistema heredado.
• Con qué evidencia. Cada operación expuesta necesita poder demostrar lo que promete su contrato: que no duplica, que se puede revocar, que deja rastro.

Los fabricantes van en esa dirección: SAP ofrece su capa de administración de APIs para poner autenticación, cuotas y monitoreo sobre servicios existentes [30], e IBM expone sistemas de mainframe como APIs descritas con OpenAPI [31]. La tecnología de la fachada existe; lo difícil —y lo que más se equivoca— es decidir qué se expone, con qué reglas y con qué evidencia.

Qué pasa si no se hace nada

Las áreas de negocio no van a esperar. Si la API no está lista, alguien va a conectar un agente de todos modos: con una credencial personal, sin bitácora y con más permisos de los que necesita. El resultado típico no es un ataque sofisticado; es un cargo duplicado que termina en una aclaración, una cuota agotada a media noche o una credencial de integración que se filtra, como en los incidentes citados arriba. Prepararla antes suele costar menos que explicarlo después.

Cómo saber si está funcionando

Un acierto aislado no dice nada; lo que mide la confianza es la consistencia. El benchmark τ-bench, de 2024, propuso medir cuántas veces resuelve un agente la misma tarea si se la repiten. En sus pruebas, un modelo de punta de ese momento resolvía menos de la mitad de las tareas, y en el dominio de comercio, menos de una cuarta parte cuando se le pedía acertar ocho veces seguidas [32]. Las cifras de ese año ya cambiaron; el método sigue siendo el correcto: medir tareas completas, varias veces, con su estado final, y medir aparte los intentos de ataque [33].

Desconfíe de las metas redondas que circulan en materiales de proveedores, como «85 % de éxito al primer intento» o «menos de 1.5 reintentos». No encontramos ninguna fuente independiente que las respalde. Las metas se fijan con sus propios datos.

Por dónde empezar

1. Para el diagnóstico, priorice por riesgo. Las operaciones que escriben —pagos, pólizas, pedidos, inventario, facturas— son las que más pueden dañar si un agente las usa mal; por eso se revisan primero.
2. Para el primer caso de uso, elija algo acotado. Una consulta, o una operación reversible y con aprobación explícita. El agente que mueve dinero llega después, con evidencia.
3. Corrija en su lugar lo que se pueda. Agregar descripciones, errores estándar y encabezados de cuota suele ser compatible con los clientes actuales, porque la mayoría ignora los campos nuevos; aun así, se prueba primero contra sus integraciones existentes. Si su equipo programa en TypeScript, la lección «El servidor» de nuestro curso abierto practica justo esto: códigos de estado y contratos que no exponen datos internos.
4. Ponga una fachada donde no se pueda tocar, con operaciones de negocio estrechas, idempotencia y bitácora.
5. Pruebe con agentes reales y mida la consistencia antes de abrirle la puerta a producción.

Saber qué estándar usar es la parte fácil. Lo difícil es saber cuáles de sus operaciones están listas, cuáles se pueden corregir en su lugar, cuáles necesitan una fachada y qué controles no se le pueden delegar a un agente. Eso es lo que revisamos en un diagnóstico: le entregamos el mapa de sus operaciones críticas, los riesgos de control que encontramos y el orden en que conviene atenderlos, para que TI, seguridad, riesgo y negocio decidan con la misma información, buscando siempre no reescribir sus sistemas.