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

Un equipo de API renombró customer_name a customer_full_name. Anunció el cambio y actualizó la documentación, pero tu agente siguió enviando el campo antiguo. La API devolvía 200, ignoraba la clave desconocida y, durante dos semanas, creó registros con nombres vacíos.

Prueba Apidog hoy

Los agentes son clientes de API especialmente frágiles: interpretan un 200 como éxito, pueden improvisar ante datos incompletos y no tienen un compilador que detecte contratos rotos. Esta guía explica cómo prevenir y detectar la deriva de API antes de que afecte a producción.

Apidog ayuda porque la detección de deriva es, sobre todo, un problema de especificación: si conservas la definición anterior y la actual de una API, la comparación es mecánica.

Por qué los agentes detectan menos cambios

Cuatro propiedades se combinan mal:

• Tolerancia silenciosa. Muchas API ignoran campos desconocidos. Si un campo se renombra, el agente envía el antiguo, el nuevo falta y la respuesta puede seguir siendo 200.
• Improvisación. Cuando falta un valor, un modelo puede usar un sustituto plausible en vez de detenerse.
• Descripciones en prompts. Las definiciones de herramientas contienen supuestos sobre la API en prosa. Si la especificación cambia, esas descripciones pueden quedar incorrectas. Consulta cómo diseñar esquemas de herramientas de API para agentes.
• Sin compilador. Un cliente tipado falla al compilar cuando desaparece un campo. El contrato de un agente suele vivir en JSON Schema y texto, y no se valida hasta la ejecución.

Por eso, un cambio compatible para clientes convencionales puede ser disruptivo para un agente.

Cambios que rompen agentes

Los cambios claramente disruptivos son los habituales: eliminar endpoints o campos, renombrar campos, modificar tipos, volver obligatorio un parámetro opcional o cambiar una URL.

Pero también hay cambios aparentemente seguros que son peligrosos para agentes:

• Nuevo campo obligatorio. El agente puede intentar inventar un valor para superar la validación.
• Nuevo valor de enumeración. Puede interpretarlo de una forma que el producto nunca contempló.
• Validación más estricta. Si un texto ahora debe cumplir un patrón, el agente solo lo aprenderá al fallar. Diseña errores claros; consulta mensajes de error de API para agentes de IA.
• Cambio de valor predeterminado. Si la paginación baja de 100 a 20 elementos, un agente puede resumir una quinta parte de los datos como si fueran el conjunto completo.
• Documentación reescrita. Si las herramientas se generan desde OpenAPI, cambiar una descripción puede afectar qué herramienta selecciona el modelo. Consulta cómo convertir una especificación OpenAPI en herramientas de agente.

En general, añadir campos, endpoints o parámetros opcionales con valores predeterminados conservados sigue siendo seguro. La categoría intermedia es la que debes vigilar.

Fija la versión de la API

No permitas actualizaciones implícitas. Envía una versión explícita en cada solicitud mediante ruta, cabecera o configuración de cuenta.

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

El User-Agent también importa: permite al proveedor localizarte y avisarte de una deprecación. GitHub usa una cabecera de fecha para versionar su API; revisa su documentación de versionado.

Si eres propietario de la API, publica versiones y mantenlas activas durante una transición. Consulta la mejor estrategia de versionado de API y cómo gestionar versiones de API en Apidog.

Si una API de terceros no ofrece versionado, fija al menos la forma de respuesta esperada y verifícala.

Detecta la deriva antes de producción

1. Compara especificaciones periódicamente

Obtén diariamente el documento OpenAPI del proveedor y compáralo con la versión usada para generar tus herramientas. Busca:

• Campos eliminados o renombrados.
• Tipos modificados.
• Nuevos requisitos.
• Enumeraciones ampliadas.
• Descripciones editadas.

En Apidog, puedes conservar la definición importada y comparar versiones para convertir “¿cambió algo?” en un informe.

2. Ejecuta pruebas de contrato

Para cada herramienta disponible para el agente, envía una solicitud conocida como válida y verifica:

• Campos requeridos presentes.
• Tipos correctos.
• Valores de enumeración esperados.

Esto detecta cambios incluso en APIs que no publican especificaciones. Consulta pruebas de contrato de API y pruebas de contrato bidireccionales.

3. Valida respuestas en tiempo de ejecución

Añade una comprobación de forma al envoltorio de cada herramienta:

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 un campo esperado. Advierte si aparece uno nuevo. Un campo requerido ausente significa que el agente está a punto de trabajar con datos incompletos; un campo adicional suele ser aditivo, pero merece seguimiento. Registra ambos eventos con un sistema de trazabilidad de llamadas de herramientas de agentes.

4. Observa comportamiento, no solo esquemas

Algunos cambios no alteran la forma de una respuesta: valores predeterminados, límites de tasa o latencia. Mide por endpoint:

• Llamadas por tarea completada.
• Tasa de reintentos.
• Tamaño medio de respuesta.
• Latencia.

Un cambio brusco suele indicar que algo cambió upstream.

Actualiza una versión sin romper el agente

Cuando migres a una versión nueva:

1. Regenera las herramientas desde la especificación; no las edites manualmente.
2. Revisa la diferencia entre definiciones de herramientas generadas.
3. Ejecuta el agente contra un mock de la nueva versión antes de usar producción. Consulta cómo ejecutar agentes contra mocks en vez de producción.
4. Repite la suite de selección de herramientas. Los cambios de descripción pueden modificar la elección del modelo. Consulta cómo probar agentes no deterministas.
5. Despliega con una bandera, en una fracción del tráfico y manteniendo la versión anterior fijada como reversión.

Observa llamadas por tarea, reintentos, errores de validación y tamaño de respuestas durante al menos un día.

Tres derivas reales

Campo renombrado

customer_name pasó a ser customer_full_name. La API ignoró el campo viejo y devolvió 200. Los nombres vacíos se detectaron dos semanas después. Una validación de respuesta habría fallado en la primera llamada.

Valor predeterminado de paginación cambiado

Un proveedor redujo el tamaño de página de 100 a 20. El agente nunca enviaba limit, por lo que empezó a resumir 20 registros como si fueran todos. La corrección fue simple: enviar un límite explícito.

Nuevo valor de enumeración

Una API de pagos añadió status: "disputed". Los clientes tipados lo ignoraron. El agente lo interpretó como un reembolso y reportó conciliaciones incorrectas. Una validación estricta de enumeraciones habría detenido el flujo ante el valor desconocido.

El patrón es consistente: cada cambio fue anunciado y parecía menor para el proveedor, pero era disruptivo para el agente.

Convierte deprecaciones en trabajo asignable

Las advertencias pueden llegar en un registro de cambios, un correo electrónico o las cabeceras estándar Deprecation y Sunset.

Registra estas cabeceras y alerta en la primera aparición, no en la milésima. Una cabecera presente hoy en el 3 % de las llamadas puede convertirse en una interrupción total en la fecha de retirada.

Mantén un inventario mínimo:

agente | proveedor | versión | endpoints | responsable

Cuando llegue un aviso, “¿nos afecta?” debería responderse en minutos.

Si gestionas agentes como tiempos de ejecución de código, una plataforma como Sharkly puede convertir una deprecación en una tarea asignada con trazabilidad, ejecución y revisión. La herramienta importa menos que la regla: una alerta de deriva sin responsable terminará siendo una incidencia.

Lista de verificación

• Cada solicitud envía una versión de API explícita y un User-Agent identificable.
• Las especificaciones de terceros se obtienen y comparan periódicamente.
• Cada herramienta tiene una prueba de contrato para validar la respuesta.
• Los envoltorios validan respuestas en tiempo de ejecución.
• La falta de campos esperados falla; los campos nuevos generan advertencias.
• Se miden llamadas, reintentos, latencia y tamaño de respuesta por endpoint.
• Las actualizaciones regeneran herramientas desde la especificación.
• Las suites de tareas y selección se ejecutan primero contra un mock.
• Los despliegues usan banderas y permiten volver a la versión anterior.

La API seguirá cambiando. Tu objetivo es que el agente lo detecte antes de que un 200 silencioso se convierta en datos incorrectos. Descarga Apidog para comparar especificaciones y simular la siguiente versión antes de llegar a producción.

Preguntas frecuentes

¿Con qué frecuencia debo comparar una especificación de terceros?

Diariamente suele ser suficiente y es barato de automatizar. Para APIs sin especificación publicada, usa pruebas de contrato en CI.

¿Debo fijar siempre la versión más antigua?

No. Fija una versión para que las actualizaciones sean deliberadas y actualiza según un calendario. Esperar hasta la retirada convierte una migración planificada en una emergencia.

¿Qué ocurre si el agente sigue funcionando tras un cambio?

Verifica, no asumas. Los fallos más peligrosos siguen devolviendo 200, como un campo renombrado que la API descarta silenciosamente.

¿Debo versionar mi propia API de forma distinta para agentes?

No distinta, pero sí más estrictamente. Trata nuevos campos obligatorios, nuevos valores de enumeración y cambios de valores predeterminados como disruptivos para consumidores basados en agentes.

¿Cómo sé qué agentes llaman a qué endpoints?

Usa tus trazas. El nombre de herramienta y el endpoint por ejecución construyen un mapa de dependencias y muestran quién se verá afectado por una deprecación. Lee más sobre trazabilidad de llamadas de herramientas de agentes de IA.

¿Puede un agente adaptarse solo a una API que cambió?

A veces, pero no debes confiar en ello. Un modelo puede improvisar una salida plausible ante un campo faltante sin indicar que algo salió mal. Haz que falle de forma visible y corrige la herramienta.