Integración primero: los agentes valen lo que sus APIs

Buena parte de la conversación sobre agentes de IA gira alrededor del modelo: cuál razona mejor, cuál comete menos errores, cuál cuesta menos. Es una pregunta legítima, pero en operaciones de TI rara vez es la que decide el resultado. Un agente de triaje que no puede leer el historial de cambios, o uno de rightsizing que no puede consultar el uso real de un recurso, no mejora con un modelo más capaz. Solo razona mejor sobre datos incompletos.

El valor de un agente está acotado por las herramientas que puede usar, y esas herramientas son, en casi todos los casos, APIs de sistemas que ya existen: la plataforma de gestión de servicios, la CMDB, la consola de nube, la herramienta de observabilidad, el orquestador de automatización. Si esas APIs son incompletas, ambiguas o frágiles, el agente lo será también. Por eso proponemos invertir el orden habitual: primero la integración, después el agente.

Del contrato a la herramienta

Un agente no lee el código de una API ni su documentación de portal. Lee una descripción estructurada de cada herramienta: nombre, propósito, parámetros de entrada y forma de la respuesta. En el Model Context Protocol (MCP), por ejemplo, cada herramienta se publica con una descripción y un esquema JSON de entrada, y puede declarar también un esquema de salida para validar los resultados estructurados. Esa descripción es todo lo que el modelo sabe sobre la herramienta.

La forma más sólida de producir buenas descripciones es partir de contratos que ya existen o que conviene tener de todos modos:

• OpenAPI describe APIs HTTP: rutas, operaciones, parámetros, esquemas de petición y respuesta, seguridad. La versión 3.1 basa sus esquemas en JSON Schema 2020-12, el mismo dialecto que MCP asume por defecto para los esquemas de herramientas en su revisión 2025-11-25.
• AsyncAPI describe APIs orientadas a mensajes y eventos: canales, operaciones de envío y recepción, y mensajes. Es la referencia para documentar lo que un agente puede escuchar (eventos de monitoreo, cambios de estado) y no solo lo que puede pedir.

Con un contrato bien escrito, exponer una operación como herramienta es en buena medida un trabajo de traducción. Sin contrato, cada herramienta se vuelve una integración a medida, con descripciones escritas a mano que se desactualizan en cuanto cambia la API.

Un matiz importante: no toda operación de una API debe convertirse en herramienta. Exponer cientos de operaciones genéricas obliga al modelo a elegir entre muchas opciones parecidas y amplía la superficie de riesgo. Conviene diseñar pocas herramientas, con nombres y descripciones orientados a la tarea ("consultar cambios recientes de un servicio") en lugar de reflejar la estructura interna de la API.

Qué hace que una API esté lista para agentes

Una API pensada para integraciones entre sistemas o para una interfaz web no siempre sirve a un agente. Un programa tradicional sigue un camino fijo escrito por un desarrollador; un agente decide en cada paso qué llamar, con qué parámetros y qué hacer con la respuesta. Eso exige propiedades que conviene revisar de forma explícita.

Criterio	Qué revisar	Por qué importa a un agente
Contrato publicado	OpenAPI o AsyncAPI vigente, versionado y validado contra la API real	Es la fuente de la descripción de la herramienta
Descripciones útiles	Cada operación y parámetro explica qué hace, valores válidos y unidades	El modelo elige la herramienta y arma parámetros a partir del texto
Lectura separada de escritura	Operaciones de consulta sin efectos; escrituras explícitas y acotadas	Permite habilitar primero la lectura y gobernar la escritura aparte
Idempotencia	Reintentar una escritura con la misma clave no duplica el efecto	Los agentes reintentan ante fallos o respuestas ambiguas
Errores claros	Códigos HTTP correctos y cuerpo estructurado con causa y corrección posible	El agente puede corregir parámetros en lugar de insistir o inventar
Paginación	Cursores estables, tamaño de página acotado, indicador de fin	Evita respuestas enormes que no caben en el contexto del modelo
Límites de uso	Límites documentados, respuesta 429 con tiempo de espera	Un agente en bucle no debe degradar el sistema para todos
Filtros y campos	Consultas por criterio y selección de campos	Menos datos irrelevantes, menos costo y menos exposición
Autorización granular	Permisos por operación y por recurso, tokens con audiencia	Base del mínimo privilegio por herramienta
Trazabilidad	Identificador de correlación aceptado y devuelto	Une la llamada del agente con el registro de auditoría

No hace falta cumplir todos los criterios para empezar. Sí hace falta saber cuáles faltan, porque cada brecha se traduce en una limitación del agente o en un control adicional que habrá que poner por fuera.

Lectura antes que escritura, e idempotencia siempre

La separación entre lectura y escritura es el criterio que más pesa en la práctica. Un agente que solo lee (resume incidentes, correlaciona señales, propone acciones) aporta valor con un riesgo acotado. Un agente que escribe necesita además aprobación, límites y registro, como explicamos en barreras de seguridad para agentes de IA.

Por eso recomendamos que cada herramienta declare su efecto. MCP ofrece anotaciones para esto, como readOnlyHint, destructiveHint e idempotentHint. Son útiles para la interfaz y para el modelo, pero la especificación las trata como indicaciones no confiables salvo que el servidor sea de confianza. El control real está en los permisos de la API, y en que la herramienta de lectura use credenciales que no permitan escribir.

La idempotencia merece una mención aparte. Un agente puede reintentar una operación porque no recibió respuesta, porque el resultado le pareció ambiguo o porque reinició la tarea. Si crear un ticket o escalar un recurso no es idempotente, cada reintento duplica el efecto. El patrón habitual es que el cliente envíe una clave única por operación y que la API devuelva el mismo resultado si recibe de nuevo esa clave. Para las operaciones que por naturaleza no pueden ser idempotentes, conviene exigir aprobación humana.

Errores, paginación y límites que un modelo pueda entender

Un desarrollador que recibe un error lee la documentación y corrige su código. Un agente solo tiene el mensaje de error. Si la API responde "Error 500" para un parámetro mal formado, el agente no tiene cómo saber qué cambiar.

Dos referencias ayudan. El RFC 9457 (Problem Details for HTTP APIs) define un formato estándar de error con tipo, título, estado y detalle, que un modelo puede interpretar. Y la especificación de MCP distingue entre errores de protocolo (herramienta desconocida, petición mal formada) y errores de ejecución de la herramienta, que se devuelven en el resultado marcados con isError. Estos últimos deben contener información accionable para que el modelo se corrija y reintente con otros parámetros, y la especificación recomienda que el cliente se los entregue al modelo.

Con la paginación ocurre algo parecido. Una consulta que devuelve diez mil registros no cabe en el contexto del modelo y, aunque cupiera, sería costosa. La API debería ofrecer paginación con cursores estables y filtros que permitan pedir solo lo necesario. MCP usa el mismo enfoque en sus propias listas: cursores opacos y tamaño de página definido por el servidor.

Por último, los límites de uso. Un agente mal configurado puede entrar en un bucle de llamadas. La API debe responder con el código 429 (Too Many Requests, RFC 6585) y, cuando sea posible, indicar cuánto esperar con la cabecera Retry-After. La herramienta, a su vez, debe respetar esa indicación en lugar de reintentar de inmediato.

Inventario de APIs y prioridades con Valor × Complejidad

Antes de decidir qué agente construir, conviene saber qué APIs existen. Recomendamos un inventario que registre, para cada sistema relevante: si tiene API, si tiene contrato publicado, qué operaciones de lectura y escritura ofrece, cómo se autoriza, quién es el dueño y cuántos criterios de la tabla anterior cumple. Ese inventario suele mostrar que el cuello de botella no es el agente, sino dos o tres sistemas sin API usable. También revela problemas de datos que conviene atender antes, como planteamos en datos listos para IA.

Para decidir qué integraciones construir o mejorar primero, usamos el mismo marco que para el backlog de automatización, descrito en priorizar la automatización por valor y complejidad. Cada candidato se documenta en una ficha y se puntúa de 1 a 5 en dos ejes:

• Valor: promedio de ahorro de esfuerzo, reducción de riesgo y errores, impacto en el cliente o en el SLA, y aporte al cumplimiento o la auditoría. Aquí el valor es el de los casos de uso de agentes que la integración habilita.
• Complejidad: promedio de cantidad de sistemas e integraciones, variabilidad del proceso, calidad de los datos y accesos disponibles, riesgo del cambio en producción y dependencia de terceros.

Con un corte en 3, cada integración cae en un cuadrante:

1. Victorias rápidas (valor alto, complejidad baja): por ejemplo, exponer como herramientas de solo lectura las consultas de una API que ya tiene contrato. Se ejecutan primero.
2. Apuestas estratégicas (valor alto, complejidad alta): por ejemplo, una API de escritura sobre un sistema sin contrato ni idempotencia. Se dividen en entregas menores, empezando por la lectura.
3. Mejoras oportunistas (valor bajo, complejidad baja): se hacen cuando hay capacidad libre.
4. Descartar o rediseñar (valor bajo, complejidad alta): no se integran así; primero se simplifica el proceso o el sistema.

Como el valor y la complejidad cambian (un proveedor publica una API, un sistema se reemplaza), el inventario y la priorización se revisan periódicamente, por ejemplo cada trimestre.

Por dónde empezar

Recomendamos tres pasos concretos. Primero, elegir un caso de uso de agente con valor claro y listar las operaciones que necesita. Segundo, evaluar las APIs involucradas con la tabla de criterios y cerrar las brechas críticas (contrato, errores claros, separación de lectura y escritura) antes de escribir la primera instrucción del agente. Tercero, exponer las herramientas a través de un punto de control con identidad, política y registro, como describimos en gobernar agentes con MCP.

Las integraciones que habilitan escritura sobre sistemas críticos, o que exponen datos personales, deben revisarse con Arquitectura y Seguridad antes de llegar a producción.