Deja que los agentes fijen la versión de la API con la que se construyeron

Deja que cada cliente fije la versión de la API con la que se construyó, por petición y por endpoint de webhook, y publica los cambios incompatibles solo en una versión nueva que el cliente decida adoptar.

Por qué

Las definiciones de herramientas, los prompts y los ejemplos de un agente están ajustados a una forma concreta de tu API. Si un campo cambia de nombre o un parámetro pasa a ser obligatorio de un día para otro, el agente no lee antes el changelog (AX-SYS-17); falla a mitad de una tarea, o malinterpreta una respuesta que todavía se puede parsear. La solución es que los cambios incompatibles sean opcionales. La API REST de GitHub recibe la versión en una cabecera X-GitHub-Api-Version, publica los cambios incompatibles solo en una versión nueva y mantiene la versión anterior al menos 24 meses después de lanzar la siguiente. Stripe le asigna a cada cuenta una versión por defecto, permite que cualquier petición la cambie con la cabecera Stripe-Version y envía los eventos de webhook en la versión por defecto de la cuenta salvo que el endpoint tenga una versión fijada, así una integración puede ver las mismas formas en las respuestas y en los eventos. Stripe también recomienda usar el versionado para probar una versión nueva antes de comprometerse a actualizar. Para un agente, eso significa que su contrato cambia cuando lo decide el equipo que lo mantiene, después de probarlo, y no cuando el proveedor despliega.

Haz

Acepta una cabecera de versión, devuelve la versión usada en cada respuesta, permite fijar una versión en los endpoints de webhook y mantén las versiones antiguas durante un periodo publicado.

No hagas

Publicar cambios incompatibles directamente en la versión por defecto, ni enviar payloads de webhook con una forma más nueva que la que usan las peticiones del cliente.

Artefacto

POST /v1/refunds HTTP/1.1
Acme-Version: 2026-06-01

HTTP/1.1 200 OK
Acme-Version: 2026-06-01
Acme-Latest-Version: 2026-09-15
Link: <https://acme.com/docs/upgrades/2026-09-15.md>; rel="help"

El agente sigue recibiendo las formas de 2026-06-01 hasta que su equipo prueba 2026-09-15 y cambia la cabecera.