Versionado de API para Agentes de IA: Cuando los Cambios Disruptivos Afectan

El equipo de la API cambió el nombre de un campo de customer_name a customer_full_name. Lo anunciaron, actualizaron la documentación y cada cliente mantenido por humanos recibió una solicitud de extracción. Tu agente no recibió nada, porque nadie lo consideró un cliente. Siguió enviando el campo antiguo, la API siguió aceptando la solicitud e ignorando la clave desconocida, y durante dos semanas cada registro que creaba tenía un nombre vacío.

Los agentes son los consumidores de API menos capaces de notar un cambio y los más propensos a encubrirlo. Un cliente humano lanza una excepción. Un agente lee un 200, decide que la llamada funcionó y sigue adelante. A veces improvisa una solución al problema de una manera que parece un éxito.

Esta guía cubre por qué los agentes son inusualmente frágiles a la deriva de la API, qué cambios los rompen que no romperían a los clientes ordinarios, cómo fijar y detectar versiones, y cómo detectar la deriva en CI antes de que se ejecute. Nuestra publicación sobre por qué los agentes de IA fallan en producción cubre los modos de falla; esta es la que llega desde fuera de tu código base.

Apidog es importante aquí porque la detección es un problema de especificación. Si tienes la versión anterior de una definición de API y la actual, la diferencia es mecánica.

Por qué los agentes notan menos que los clientes

Cuatro propiedades se combinan mal.

Tolerancia silenciosa. La mayoría de las API ignoran los campos desconocidos en el cuerpo de una solicitud. Un campo renombrado significa que el nuevo está ausente y el antiguo se descarta, con un 200 al salir. Nada se levanta.

Improvisación. Cuando a una respuesta le falta un valor, un modelo a menudo continuará con un sustituto plausible en lugar de detenerse. Este es un comportamiento útil en una conversación y peligroso contra una API.

Descripciones en el prompt. Las descripciones de las herramientas del agente codifican suposiciones sobre la API en texto. Cuando la API cambia, las descripciones se vuelven sutilmente incorrectas, y las descripciones incorrectas producen llamadas incorrectas sin que intervenga ningún código. Nuestra publicación sobre el diseño de esquemas de herramientas de API cubre cuánto comportamiento depende de ese texto.

Sin compilador. Un cliente tipado se rompe en tiempo de compilación cuando un campo desaparece. El contrato de un agente reside en esquemas JSON y prosa, y nada lo verifica hasta que una llamada falla, o peor aún, hasta que una silenciosamente no falla.

El resultado: los cambios que son seguros para los clientes típicos no siempre son seguros para los agentes, y debes clasificarlos por separado.

Qué cambios realmente rompen a los agentes

La división habitual entre aditivos y disruptivos sigue aplicándose, y los agentes añaden una categoría intermedia.

Realmente disruptivos, para todos. Eliminar un endpoint, eliminar un campo, renombrar un campo, cambiar un tipo, hacer que un parámetro opcional sea requerido, cambiar la URL. Los agentes también se rompen aquí, solo que de forma más silenciosa.

Seguro para clientes tipados, arriesgado para agentes:

• Un nuevo campo requerido. Cada llamador existente se rompe, pero un agente se rompe con un error de validación que puede intentar corregir inventando un valor. Esto es peor que un fallo duro.
• Un nuevo valor de enumeración. Los clientes ordinarios ignoran lo que no manejan. Un agente puede razonar sobre el valor desconocido y sacar una conclusión que tu producto nunca pretendió.
• Una regla de validación más estricta. Un campo que solía aceptar cualquier cadena ahora requiere un patrón. El agente no tiene forma de aprender el patrón excepto fallando, por eso la regla pertenece al mensaje de error, como se cubre en nuestra publicación sobre el diseño de mensajes de error de API para agentes de IA.
• Un valor predeterminado cambiado. El valor predeterminado de paginación baja de 100 a 20 y el agente, que nunca envió un límite, ahora ve una quinta parte de los datos e informa sobre ellos como si estuvieran completos.
• Documentación reescrita. Ningún cambio de comportamiento en absoluto, pero si tus herramientas se generan a partir de la especificación, como en nuestra guía para convertir una especificación OpenAPI en herramientas de agente, el texto de la descripción cambió y la selección de herramientas puede cambiar con él.

Seguro también para agentes. Añadir un campo opcional, añadir un endpoint, añadir un parámetro opcional con un valor predeterminado conservado, relajar la validación.

Esa lista intermedia es la que hay que vigilar, porque nada en una revisión de cambio estándar la señala.

Fija la versión, siempre

La primera defensa es negarse a moverse implícitamente.

Envía una versión explícita en cada solicitud, cualquier mecanismo que la API ofrezca: un segmento de ruta, una cabecera o un pin a nivel de cuenta. La documentación de versionado de API de GitHub utiliza una cabecera de fecha, y Stripe fija una versión por cuenta con un paso de actualización explícito. Ambos te dan la misma propiedad: nada cambia debajo de ti hasta que tú lo decides.

DEFAULT_HEADERS = {
    "X-API-Version": "2026-06-01",
    "User-Agent": "billing-agent/1.4 (+https://example.com/agents)",
}

El User-Agent vale tanto como la fijación de la versión. Cuando un proveedor de API necesita advertir a los que llaman sobre una deprecación, observa el tráfico. Un agente que se identifica recibe el correo electrónico; uno que envía una cadena de biblioteca predeterminada no lo hace.

Si eres el propietario de la API, publica una versión y mantenla. Nuestra guía sobre la mejor estrategia de versionado de API cubre las opciones, y gestionar el versionado de API en Apidog cubre cómo mantener varias activas a la vez.

Para APIs de terceros sin ningún versionado, fija lo que puedas: registra la forma de respuesta contra la que construiste y verifícala, que es la siguiente sección.

Detectar la deriva antes de que lo haga una ejecución

Fijar la versión da tiempo. No detiene la actualización eventual, y no hace nada por las API que cambian sin versionado. Así que, detecta.

Compara la especificación según un cronograma. Si el proveedor publica un documento OpenAPI, obtenlo diariamente y compáralo con la copia con la que generaste las herramientas. Campos eliminados, tipos cambiados, requisitos añadidos, enumeraciones extendidas, descripciones editadas. En Apidog puedes mantener la definición importada en el proyecto y ver qué cambió entre versiones, lo que convierte "¿algo cambió?" en un informe en lugar de una investigación.

Prueba por contrato los endpoints que llamas. Para cada herramienta que tiene el agente, envía una solicitud conocida como buena y afirma la forma de la respuesta: campos requeridos presentes, tipos correctos, valores de enumeración dentro del conjunto que esperas. Esto detecta la deriva en APIs que no publican ninguna especificación, que son la mayoría. Nuestra guía de pruebas de contrato de API cubre el patrón, y las pruebas de contrato bidireccionales cubren cómo ejecutarlas desde ambos lados.

Afirma la forma en tiempo de ejecución. Valida las respuestas en el envoltorio de la herramienta contra el esquema que esperas, y registra una advertencia cuando aparece algo inesperado. Esta es la última línea, y es la que detecta el cambio que nadie anunció.

def check_shape(tool_name, payload, expected):
    missing = [f for f in expected["required"] if f not in payload]
    extra = [f for f in payload if f not in expected["properties"]]
    if missing:
        log.error("api_drift", tool=tool_name, missing=missing)
        raise ApiDriftError(f"{tool_name}: missing fields {missing}")
    if extra:
        log.warning("api_new_fields", tool=tool_name, fields=extra)
    return payload

Falla si falta algo, advierte si hay algo extra. Un campo requerido que falta significa que el agente está a punto de trabajar con datos incompletos, lo cual es la falla por la que vale la pena detenerse. Los nuevos campos suelen ser aditivos y vale la pena conocerlos sin interrumpir una ejecución. Dirige ambos al registro de seguimiento descrito en nuestra publicación sobre el seguimiento de llamadas de herramientas de agente de IA.

Observa el comportamiento, no solo los esquemas. Alguna deriva es invisible para una verificación de forma: un valor predeterminado que cambió, un límite de tasa que se endureció, una respuesta que se volvió más lenta. Rastrea las llamadas por tarea completada, la tasa de reintentos por endpoint y el tamaño promedio de respuesta por herramienta. Un cambio brusco en cualquiera de ellos generalmente significa que algo se movió upstream.

Actualizar sin romper el agente

Cuando te muevas a una nueva versión, trátala como un cambio para el agente, porque lo es.

Regenera las herramientas en lugar de editarlas a mano, para que las descripciones y los esquemas se muevan juntos. Luego, lee la diferencia de las definiciones de herramientas generadas. Esa diferencia es el verdadero radio de acción, y a menudo es más pequeño o más grande de lo que implica el registro de cambios de la API.

Ejecuta el agente contra un mock de la nueva versión antes de apuntarlo a cualquier cosa en vivo. Este es el paso de mayor valor y el que más a menudo se omite: un mock construido a partir de la nueva especificación te permite ejecutar tu conjunto completo de tareas contra las nuevas formas sin riesgo, siguiendo nuestra publicación sobre ejecutar agentes contra mocks en lugar de producción.

Vuelve a ejecutar la suite de selección. Los cambios en la descripción desplazan qué herramienta elige el modelo, y esa regresión es invisible para una diferencia de esquema. Afirma la elección de la herramienta para un conjunto fijo de prompts, como en nuestra guía para probar agentes no deterministas.

Implementa detrás de una bandera, en una porción del tráfico, con la versión antigua aún anclada y lista. Observa los mismos cuatro números durante un día. Las regresiones del agente se muestran como más llamadas por tarea y más reintentos mucho antes de que alguien presente una queja.

Tres derivas que llegaron a producción

El campo renombrado. La historia inicial. Un 200 en cada llamada, nombres vacíos en cada registro, descubierto dos semanas después por un humano leyendo un informe. Una verificación de forma en tiempo de ejecución en la respuesta lo habría detectado en la primera llamada, porque el campo que el agente esperaba leer de vuelta había desaparecido.

El valor predeterminado de paginación ajustado. Un proveedor redujo el tamaño de página predeterminado de 100 a 20. El agente nunca envió un limit, por lo que comenzó a ver 20 registros y a resumirlos como el conjunto completo. Nada dio error. Los resúmenes eran simplemente incorrectos, de una manera que sonaba confiada. La solución fue una línea, enviando un limit explícito, y la lección es más amplia: confía en los valores predeterminados y tendrás una dependencia no declarada de la decisión de otra persona.

El nuevo valor de enumeración. Una API de pagos agregó status: "disputed". Los clientes tipados lo ignoraron. El agente razonó al respecto, decidió que un cargo disputado contaba como un reembolso, y reportó libros conciliados que no lo estaban. Una validación explícita de enumeración habría elevado un error sobre el valor desconocido en lugar de dejar que el modelo lo interpretara.

El patrón: cada cambio fue anunciado, cada uno fue aditivo o menor según la clasificación del propio proveedor, y cada uno fue disruptivo para un agente. Esa brecha es lo que hay que diseñar para evitar.

Trata las deprecaciones como un elemento de trabajo

Los proveedores suelen advertirte. La advertencia llega en un registro de cambios, un correo electrónico o una cabecera Deprecation en la respuesta, y es fácil que ninguna de ellas llegue a la persona que mantiene el agente.

Conéctalas a tu cola normal. La cabecera Deprecation y la cabecera Sunset están estandarizadas, por lo que una verificación genérica funciona en todos los proveedores. Regístralas cuando aparezcan, y alerta en el primer avistamiento en lugar del milésimo. Una cabecera que aparece en el 3 por ciento de las llamadas hoy es una interrupción total en la fecha de caducidad.

Mantén también un inventario: qué agente, qué proveedor, qué versión, qué endpoints y quién es el propietario. Diez líneas en un archivo son suficientes. Cuando llega un aviso de deprecación, la pregunta "¿esto nos afecta?" debería llevar un minuto, no una tarde de búsqueda.

La deriva es trabajo, así que dale un propietario

La detección produce una cola: una diferencia de especificación, una prueba de contrato fallida, una cabecera de deprecación vista por primera vez. Cada una es una pequeña pieza de trabajo con una fecha límite adjunta, y el modo de falla es que permanece en un canal sin propietario hasta que llega la fecha de caducidad.

Ponlos donde tu equipo ya rastrea el trabajo. Si tus agentes se ejecutan como tiempos de ejecución de codificación en lugar de como un servicio que implementaste, la plataforma que los gestiona puede cerrar el ciclo: Sharkly asigna una Tarea a un Agente o un Equipo y mantiene el objetivo, el rastro de ejecución y la revisión en un solo lugar, de modo que "la API de pagos deprecó este endpoint" se convierte en una tarea asignada con un resultado en lugar de un mensaje en un hilo. Sea lo que sea que uses, la regla es la misma. Una alerta de deriva sin propietario es una deprecación que volverás a encontrar el día en que se rompa.

Una lista de verificación

• Cada solicitud envía una versión de API explícita y un User-Agent identificativo.
• Los documentos de especificación de terceros se obtienen y comparan según un cronograma.
• Cada herramienta que el agente puede llamar tiene una prueba de contrato que afirma la forma de la respuesta.
• Los envoltorios de herramientas validan las respuestas en tiempo de ejecución: fallan si falta algo, advierten si hay algo nuevo.
• Se rastrean métricas de comportamiento por endpoint para que la deriva silenciosa salga a la superficie.
• Las actualizaciones de versión regeneran las herramientas en lugar de editarlas a mano.
• El conjunto de tareas y el conjunto de selección se ejecutan primero contra un mock de la nueva versión.
• El despliegue está marcado con una bandera y es reversible, con la versión anterior aún fijada.

El equipo de la API seguirá enviando cambios, y eso está bien. Lo que necesitas es que tu agente sea un cliente que se dé cuenta, lo que requiere un pin de versión, una prueba de contrato y una verificación de forma en tiempo de ejecución. Descarga Apidog para comparar la especificación y simular la próxima versión antes de que llegue a una ejecución en vivo.

Preguntas frecuentes

¿Con qué frecuencia debo verificar los cambios en una especificación de terceros? Diariamente es suficiente para la mayoría, y económico de automatizar. Para las API sin especificación publicada, apóyate en las pruebas de contrato que se ejecutan en CI, ya que detectan la misma deriva desde el exterior.

¿Debo siempre fijarme a la versión operativa más antigua? No. Fíjate para que las actualizaciones sean deliberadas, luego actualiza según un cronograma. Mantenerse en una versión antigua hasta que se elimine convierte un cambio planificado en una emergencia.

¿Qué pasa si el agente funciona bien después de un cambio? Verifica en lugar de asumir. Los resultados peligrosos son los que aún devuelven 200, como un campo renombrado que se descarta silenciosamente. Una aserción de forma te dice lo que una ejecución correcta no puede.

¿Necesito versionar mi propia API de manera diferente para los agentes? No de manera diferente, pero sí de manera más estricta. Trata los nuevos campos requeridos, los nuevos valores de enumeración y los valores predeterminados cambiados como disruptivos para los consumidores de agentes, incluso cuando sean aditivos para los clientes tipados, y anúncialos de la misma manera.

¿Cómo sé qué agentes llaman a qué endpoints? A partir de tus rastros. El nombre de la herramienta más el endpoint por ejecución te da el mapa de dependencias, y te dice exactamente quién se ve afectado por una deprecación. Nuestra publicación sobre el seguimiento de llamadas de herramientas de agente de IA cubre la forma del registro.

¿Puede el agente adaptarse por sí mismo a una API cambiada? A veces, y no debes confiar en ello. Un modelo que improvisa ante un campo faltante produce una salida plausible sin ninguna señal de que algo salió mal. Falla ruidosamente y corrige las herramientas en su lugar.