Cómo crear contract tests para que un agente no rompa cuando cambia el esquema de una herramienta

Un agente puede fallar aunque la herramienta siga “arriba”. El problema aparece cuando una API continúa respondiendo, pero cambia algo que el agente daba por estable: un campo se renombra, un valor enum desaparece, una propiedad pasa a ser obligatoria o una respuesta anida datos en otra estructura. Desde infraestructura todo puede verse saludable y, aun así, la integración deja de significar lo mismo. Un contract test convierte ese supuesto invisible en una prueba explícita. Su tarea es demostrar que el contrato que consume el agente coincide con el contrato que realmente ofrece la herramienta antes de dejar que una nueva versión entre al flujo.

Empieza enumerando qué partes del contrato son realmente necesarias para tomar decisiones. No hace falta fijar cada detalle de una respuesta si el agente utiliza solo cinco campos. Documenta endpoint o acción, parámetros obligatorios, tipos, enums permitidos, restricciones, estructura mínima de salida y errores que el sistema sabe interpretar. También registra qué campos son opcionales y qué comportamiento se espera cuando faltan. Esa lista funciona como una interfaz de negocio, no como una copia completa de documentación técnica. El objetivo es proteger lo que el agente necesita para actuar correctamente y permitir que la herramienta evolucione en áreas que no afectan el flujo.

Convierte esa interfaz en ejemplos ejecutables que deban pasar antes de cada despliegue. Un test puede enviar una solicitud mínima válida y comprobar que la respuesta contiene los campos esperados con tipos compatibles. Otro puede probar un valor inválido y exigir el error que el agente sabe manejar. También conviene incluir casos límite: colecciones vacías, valores nulos, paginación, identificadores inexistentes y respuestas parciales. Si una herramienta ofrece un schema formal, úsalo como base; si no, construye un contrato reducido. Lo importante es que el test falle cuando una modificación rompe una expectativa que antes era silenciosa.

Prueba también el contrato de error porque ahí suelen aparecer fallos difíciles de diagnosticar. Un agente puede manejar correctamente un 404 y reintentar un 429, pero comportarse mal si la herramienta cambia el código, el formato del mensaje o la ubicación del identificador de error. Diseña pruebas para las condiciones que activan reintentos, escalamiento humano, cancelación o fallback. Así verificas no solo el camino feliz, sino las señales que controlan decisiones posteriores. Un cambio de error puede ser tan peligroso como un cambio de campo porque altera la lógica con la que el agente decide qué hacer a continuación.

Separa compatibilidad de sintaxis y compatibilidad de significado. Que un campo siga siendo string no garantiza que conserve la misma semántica. Por ejemplo, status="complete" podría pasar de significar “acción ejecutada” a “solicitud aceptada”. El contract test técnico puede pasar mientras el proceso de negocio queda incorrecto. Para campos críticos, añade asserts sobre significado mediante fixtures conocidos: una entrada que antes producía cierto estado debe seguir produciendo una interpretación equivalente. Cuando una herramienta cambia semántica, el test debe obligar al equipo a revisar conscientemente la lógica del agente en vez de absorber el cambio de forma accidental.

Ejecuta las pruebas en dos direcciones cuando controlas tanto agente como herramienta. El consumidor declara qué necesita y el proveedor confirma que sigue cumpliéndolo. Si existen varios agentes, cada uno puede mantener su contrato mínimo para evitar que una modificación destinada a un flujo rompa otro. Antes de retirar un campo o cambiar un enum, el proveedor puede ver qué consumidores aún dependen de él. Esta disciplina convierte una integración en una relación versionada y observable. También reduce la tentación de probar únicamente en producción, donde descubrir una incompatibilidad significa que el cliente ya participó en el experimento.

Un contract test es una alarma temprana para cambios que todavía parecen pequeños. No sustituye pruebas end-to-end ni monitoreo real, pero detecta una clase específica de fallo antes de que se mezcle con razonamiento, memoria o decisiones del agente. La regla práctica es sencilla: si una herramienta tiene campos o respuestas que controlan una acción, esos supuestos deben existir como pruebas automáticas. Cuando el contrato cambia, el sistema debería detener el despliegue y pedir una decisión explícita. La integración madura no confía en que dos equipos recuerden mantenerse compatibles; conserva esa compatibilidad como evidencia ejecutable.