Mi Agente Llamó Cinco Veces a una API Fallida—El Fallo No Estaba en el Código

Un fallo en producción. Mi agente repetía la misma llamada a una API cinco veces seguidas. Por inercia, lo primero que abrí fue el código. La lógica de reintento estaba bien. El flujo de funciones era normal. Ni un solo error en los logs.

El código no tenía respuestas. No fue hasta que abrí la traza cuando la causa se hizo visible.

El código de un agente es un recipiente vacío

Abre el código fuente de cualquier agente y encontrarás una especificación del modelo, una lista de herramientas y un system prompt. Poco más. Qué herramienta llamar y cuándo, qué secuencia de razonamiento seguir… nada de eso vive en el código.

Los equipos que trabajan con agentes basados en LangGraph repiten siempre lo mismo: “No puedes juzgar la calidad de un agente a través de una revisión de código.”

• El mismo código, la misma entrada, patrones de llamada a herramientas distintos cada vez
• A diferencia de una función como handleSubmit(), la lógica de ramificación simplemente no existe en el código
• Probar GPT-5.2 con la misma consulta diez veces da aproximadamente un 40% de consistencia en el orden de llamadas a herramientas
• Los errores ocurren sin que haya ningún bug en el código, lo que hace imposible reproducirlos

Este es el cambio fundamental. En el software tradicional, el código es el comportamiento. En los agentes, el código es solo el andamio. El comportamiento real emerge en tiempo de ejecución, moldeado por el razonamiento del modelo sobre el contexto que recibe.

Las trazas son el nuevo código fuente

Una traza registra cada paso que da el agente. Qué razonó en cada momento, qué herramienta llamó y por qué: todo queda capturado. La depuración, las pruebas y el análisis de rendimiento que antes hacíamos a través del código ahora tienen que ocurrir a través de las trazas.

Cuando un agente recibe un mensaje de error y vuelve a hacer la misma llamada de todas formas, eso no es un bug en el código. Es un fallo de razonamiento. Y solo puedes verlo en la traza.

• Comparar trazas antes y después de un cambio en el prompt revela diferencias en la calidad del razonamiento al instante
• En LangSmith, cargar una traza desde un punto concreto en el playground funciona como poner un breakpoint
• Una sola traza puede mostrarte el momento exacto en que el razonamiento del agente se torció, algo que ninguna cantidad de logging puede replicar

Piénsalo así: depurar software tradicional es leer una receta para encontrar el error. Depurar agentes es ver las grabaciones de la cocina para ver dónde se equivocó el chef. La receta puede ser perfecta. La ejecución es donde todo se rompe.

Las pruebas cambian de raíz

En el software tradicional, pruebas antes del despliegue y listo. Los agentes son no deterministas, así que hay que seguir evaluando en producción.

Sin un pipeline que recopile trazas, construya datasets de evaluación y detecte degradación de calidad o deriva, sencillamente no puedes operar agentes a escala.

Los equipos que han adoptado la evaluación basada en trazas han visto mejoras medibles en las tasas de éxito de las tareas. El patrón es consistente: las trazas revelan modos de fallo que ninguna suite de pruebas previa al despliegue podría predecir.

• Construye un pipeline de evaluación automatizado que muestree trazas de producción semanalmente
• Las pruebas previas al despliegue por sí solas no pueden garantizar calidad en sistemas no deterministas
• Monitorizar sin trazas es como comprobar únicamente si el servidor está encendido
• Un agente puede estar “funcionando con normalidad” mientras ejecuta tareas completamente equivocadas: solo las trazas lo detectan

La colaboración y el análisis de producto también ocurren en las trazas

Las revisiones de código ocurren en GitHub. ¿Dónde ocurren las revisiones del criterio de un agente?

Las plataformas de observabilidad están asumiendo ese papel. Los equipos comentan trazas, comparten puntos de decisión concretos y revisan el razonamiento del agente de la misma manera en que antes revisaban pull requests. El propio modelo de colaboración está cambiando.

El análisis de producto sigue el mismo patrón. Cuando una métrica dice “el 30% de los usuarios están insatisfechos”, no puedes encontrar la causa sin abrir las trazas. El agente puede estar completando las tareas con éxito según su propia medida mientras se aleja por completo de lo que el usuario realmente quería.

• Herramientas de analítica de producto como Mixpanel y herramientas de depuración están convergiendo en las trazas como substrato común
• Analizar los patrones de llamada a herramientas de un agente puede revelar qué funcionalidades necesitan realmente los usuarios

La conclusión

En la era de los agentes, el código es el plano de construcción y las trazas son las grabaciones de las cámaras de seguridad. Cuando algo sale mal en el edificio, no despliegas el plano primero: rebobinas las grabaciones.

Los equipos que están haciendo bien la calidad de sus agentes son los que han desplazado su centro de gravedad del código a las trazas. No porque el código no importe, sino porque los fallos interesantes —los que te cuestan usuarios y dinero— viven en el comportamiento en tiempo de ejecución que solo las trazas capturan.