Construye una puerta de CI que detecte fallos de herramientas del agente antes que los usuarios

Una fusión puede aprobarse mientras el agente sigue a una sola herramienta rota de un estado deficiente. Un pipeline de publicación de siete agentes entregó más de 261 publicaciones. Los fallos que importan suelen ser fallos de herramientas: timeouts, límites de tasa, escrituras parciales y bucles de reintento que parecen vivos pero no hacen nada.

En 2026, un agente multi-herramienta suele realizar de 3 a 20 llamadas a herramientas en una sola tarea. Si cada llamada a herramienta tiene éxito el 98% de las veces, una ejecución de agente de 10 pasos tiene como máximo 81,7% de éxito. Esa matemática explica por qué una demo del camino feliz no es una prueba de fiabilidad.

Las herramientas rotas son los fixtures

Un arnés de regresión de fallos de herramientas trata las herramientas rotas como fixtures de prueba de primera clase. No solo pruebas que el agente llame a la herramienta correcta. Pruebas lo que hace cuando la herramienta se niega, se detiene, devuelve datos parciales o repite el mismo fallo. A los usuarios no les importa tu número de reintentos. Les importa si la tarea se completa, si el estado se mantiene consistente o si la parada es clara.

No escribas a mano cada traza. Captura un pequeño conjunto de tareas similares a producción y luego elimina el ruido. Una traza dorada debe ser legible por un diseñador, no solo por un ingeniero. Si un compañero no puede decir qué intentaba hacer el agente, la traza es demasiado opaca.

Los timeouts necesitan un fixture que haga que la herramienta se cuelgue lo suficiente para que el agente lo note. Un fixture de límite de tasa debe devolver una negativa que el agente debe respetar. Las escrituras parciales dejan un registro en un estado que requiere reconciliación. Las tormentas de reintento hacen que la misma llamada falle repetidamente. Los bucles atascados dejan que el agente repita un patrón sin progreso.

AWS describe la inyección de fallos como una forma deliberada de someter a estrés las cargas de trabajo, permitiendo a los equipos observar el comportamiento y fortalecer la resiliencia mediante plantillas y salvaguardas como condiciones de parada. La misma idea se aplica a las llamadas a herramientas del agente. Una herramienta es una dependencia con modos de fallo, y esos modos de fallo pertenecen a la suite de pruebas.

La puerta es un bucle de reproducción

• Registra trazas doradas de tareas reales. Una traza guardada para cada tarea representativa incluye la solicitud del usuario, las llamadas a herramientas, los argumentos, las respuestas, los reintentos, la respuesta final y cualquier efecto secundario.
• Escribe fixtures de fallo para las herramientas que realmente llamas. Incluye timeouts, límites de tasa, escrituras parciales, tormentas de reintento y bucles atascados. Para herramientas HTTP, usa RFC 9110 como referencia para las semánticas HTTP fundamentales; Julian Reschke, Roy T. Fielding, Mark Nottingham y el RFC están asociados. Termina cuando el conjunto de fixtures cubra los modos de fallo que realmente puedes provocar.
• Reproduce las trazas contra los fixtures. Ejecuta la misma tarea con una herramienta que falla de una forma conocida. Una reproducción pasa cuando termina en un estado recuperado, un estado degradado con una razón visible para el usuario o una parada segura.
• Puntúa la recuperación con una rúbrica. Una rúbrica terminada nombra el fallo y el comportamiento de recuperación. Verifica si el agente notó el fallo, evitó repetir la misma llamada, preservó el estado parcial y le dijo al usuario lo que no pudo hacer.
• Controla las fusiones con la rúbrica. El trabajo de CI falla con una puntuación de recuperación caída, un bucle atascado o una escritura parcial no reconciliada.

El error común es probar solo la respuesta final. Una respuesta fluida puede ocultar un estado de herramienta roto. Controla los efectos secundarios, no solo la prosa.

Mantén la rúbrica lo suficientemente pequeña para discutir en una revisión. Una puntuación de recuperación no debe ocultar un mal fallo. Si el agente se recupera destruyendo el estado del usuario, la puntuación debe fallar. La rúbrica es una decisión de diseño, no una métrica para pulir después.

Una puerta útil comienza con herramientas dañinas

Comienza con las herramientas que pueden causar un daño real. Cualquier herramienta que escriba, elimine o publique merece un fixture antes de salir. Una búsqueda de solo lectura puede comenzar con un fixture de timeout y un fixture de reintento. El arnés debe ser lo suficientemente estable para ejecutarse en cada fusión y lo suficientemente preciso para capturar el fallo que de otro modo llegaría a un usuario.

Si quieres una reproducción local económica, un modelo local pequeño puede mantener el bucle rápido. Los datos de benchmark del autor midieron Llama 3.1 8B Q4_K_M a una tasa de 12 tokens por segundo en un M1 de 16GB; el M4 Max de 36GB alcanzó 58 tokens por segundo. Ese tipo de velocidad importa cuando el arnés se ejecuta en cada fusión.

Mantén la rúbrica visible en la pull request. Un diff corto de traza, un nombre de fallo y un veredicto de recuperación son más útiles que un dashboard lleno de checks verdes. Cuando la puerta está en su lugar, una fusión se aprueba porque el agente sobrevivió al fallo de herramienta que encontrará en producción.