Depuración de Agentes de IA: Tu panel conoce el costo, no la causa

La depuración de agentes de IA comienza donde termina tu panel de observabilidad. Cuando un agente de codificación de IA rompe algo y la ejecución ya ha terminado, el panel puede decirte cuánto costó esa ejecución (tokens, dólares, latencia), pero guarda silencio sobre la única pregunta que de verdad importa: ¿por qué cambió el agente ese archivo? El artefacto que responde esa pregunta es un trace grabado que puedes abrir, leer y reproducir, porque te devuelve la ejecución en lugar de describirla desde fuera.

Esto dejó de ser un evento raro en el momento en que los agentes empezaron a hacer trabajo real. Un agente recorrerá un repositorio, editará varios archivos, ejecutará las verificaciones y reportará éxito, todo entre dos mensajes que escribiste con minutos de diferencia. Si una de esas ediciones es incorrecta, te enteras después: cuando la terminal ya está cerrada, cuando el historial ya no está, cuando el proceso que podría haberse explicado ya ha salido. Lo que ocurre a continuación depende por completo de lo que conservaste. Si la respuesta es un panel de costos, te espera un trabajo de arqueología. Si la respuesta es una grabación, te espera una lectura.

El fallo que no puedes reproducir

Esta es la forma que tiene. Vuelves al repositorio y un archivo que nunca pediste a nadie que tocara ha sido reescrito, o eliminado, o vaciado de la función de la que depende todo lo demás. Le preguntas al agente qué pasó; la sesión está cerrada, e incluso cuando sobrevive una transcripción, el relato del agente sobre su propia ejecución es una reconstrucción, no una grabación. Así que haces lo natural y lo ejecutas de nuevo, y obtienes una ejecución diferente. Diferentes llamadas a herramientas, diferentes ediciones, posiblemente ningún fallo en absoluto, porque la trayectoria original dependía del muestreo, del estado del repositorio, del momento. La ejecución que necesitas inspeccionar ya no existe.

Es peor que irreproducible. Es irreproducible y marcado como éxito. Una ejecución termina con código 0 cuando el agente termina con código 0, incluso si una verificación dentro de la ejecución terminó con código 1: la canalización puede estar en verde mientras un paso de verificación dentro de la ejecución falló, y el código de salida en el que naturalmente confiarías no te está diciendo nada.

No importa qué modelo haya elegido el router para la ejecución (GLM 5.3 Flash o cualquier otro): una vez que el proceso termina, el razonamiento se va con él. La evidencia existía solo mientras la ejecución estaba activa: los prompts, las llamadas a herramientas, las salidas, los diffs. Si nada los registró, «¿por qué cambió ese archivo?» no tiene respuesta. Tiene teorías.

Este es el modo de fallo que separa a los agentes de codificación de IA de todas las herramientas anteriores: el daño y la explicación ocurren en el mismo lugar, y el lugar se cierra.

¿Qué mide un panel de control y qué pasa por alto?

El instinto después de una mala ejecución es abrir el panel de observabilidad, y el panel será de verdad muy bueno en su labor. Su labor es el tráfico: tokens por día, costo por modelo, latencia, tasas de error. Para la planificación de capacidad y la facturación, ese es exactamente el instrumento adecuado, y si ejecutas agentes en producción, deberías tenerlo abierto.

Pero tu pregunta no es agregada. Es singular y causal: ¿por qué esta ejecución cambió este archivo? La agregación pasa por alto precisamente la granularidad que la responde. Al promediar entre ejecuciones, la ejecución que te importa es ruido; dentro de esa ejecución, la llamada a la herramienta que te importa es ruido otra vez.

Un panel describe una ejecución desde el exterior: que ocurrió, lo que pesó, lo que costó. No puede entregarte la ejecución, y el "porqué" no es una propiedad de la descripción. Es una propiedad de la secuencia.

• ¿Cuánto costó la ejecución? — El panel de costos lo responde vs la traza registrada lo responde

• ¿Por qué el agente cambió ese archivo? — Panel de costos Sin respuesta vs Traza registrada La edición, en secuencia, con su diff

• ¿Qué comprobación falló dentro de una ejecución verde? — Cost dashboard: Sin respuesta vs. Traza registrada. La comprobación, con su código de salida.

• ¿Puedo reproducir exactamente el mismo fallo de nuevo? — Panel de costos: No vs Traza registrada: Sí, sin conexión, sin costo.

La capa que responde a eso se encuentra justo debajo: registros de solicitudes grabados, capturados mientras ocurría la ejecución, con cada prompt enviado, cada llamada a herramienta emitida, cada respuesta recibida, en orden. No un resumen de la ejecución. La ejecución misma.

Leer una ejecución como una línea temporal.

Con una grabación, la depuración deja de ser arqueología y se convierte en lectura. La arqueología es lo que haces sin una: git reflog, entradas de stash, historial del shell, tu propio recuerdo de lo que pediste ese mismo día. La lectura es lo que haces con una: abrir la línea de tiempo y desplazarte.

La línea de tiempo presenta la ejecución en el orden en que ocurrió: el prompt que la inició, cada llamada a herramienta, cada edición de archivo con su diff, cada verificación, cada código de salida. Se toma una instantánea del sistema de archivos una vez por turno en lugar de una vez por llamada a herramienta, lo cual es suficiente para ver el estado del repositorio en cada paso de la conversación sin ahogarse en el ruido de cada llamada. Lo que convierte esto en depuración y no en una simple exploración es la adyacencia: la edición y la verificación que la detectó están una al lado de la otra, en orden, sin nada en medio sobre lo que especular. El "por qué" es, en su mayor parte, una propiedad de la adyacencia.

Un ejemplo concreto, tomado de una corrección registrada: 14 eventos, entre ellos el cambio de archivo impreso como +1 -3 y una comprobación fallida con código de salida 1. En el registro, el cambio y la comprobación que falló por él son adyacentes. Esa es toda la diferencia entre reconstruir una ejecución a partir de fragmentos y leerla entera. Importa sobre todo para los agentes de codificación en terminal, cuyo espacio de trabajo es una terminal que se cierra en cuanto el trabajo termina: la cronología es el scrollback que sobrevive.

Registrado o inferido: lo que el rastreo sabe frente a lo que dedujo

Una línea de tiempo te dice qué sucedió en orden. El gráfico causal te dice qué condujo a qué, y la brecha entre ambos es donde hay que ganarse la confianza.

El grafo conecta eventos: esta edición, luego esta verificación fallida. Algunas de esas aristas son hechos registrados: la llamada a la herramienta que produjo el diff está justo ahí en la traza. Otras son inferidas: la conclusión del grafo de que la verificación falló debido a ese diff. orca graph etiqueta cada arista como registrada o inferida y nombra la regla que usó en cualquier caso, de modo que siempre sabes si estás viendo algo que la ejecución hizo o algo que la herramienta dedujo sobre la ejecución.

Esa distinción se aplica, no es aspiracional: las aristas inferidas nunca se escriben en la traza. La traza sigue siendo un registro fiel de lo sucedido; la inferencia es una vista superpuesta a ella, que puedes inspeccionar, cuestionar y rebatir. Esto importa sobre todo cuando hay más de un agente involucrado. Cuando un agente de refactorización y un agente que escribe pruebas tocan los mismos archivos, «qué agente causó esto» es precisamente la pregunta que la atribución multiagente existe para responder. Una arista que se promueve silenciosamente de inferencia a hecho es cómo terminas depurando una historia en lugar de una ejecución.

Reproducirlo tantas veces como quieras gratis.

La lectura explica. La repetición demuestra. Una vez que tienes una hipótesis (la comprobación falló porque la edición eliminó la llamada de reinicio), quieres volver a ejecutarla y verlo suceder. Volver a ejecutar el agente en vivo te da una nueva trayectoria y una nueva factura.

Reproducir la grabación te da la misma ejecución: la reproducción se ejecuta con la red bloqueada, por lo que no cuesta tokens y no tiene variación. Los mismos eventos, cada vez, sin conexión. Esa es la propiedad que convierte la depuración de agentes de un juego de azar en ingeniería: el fallo se ha vuelto determinista, y los fallos deterministas se corrigen.

La herramienta tampoco es una caja negra. OrcaReplay es de código abierto con licencia Apache-2.0 y el formato de trazas tiene licencia CC BY 4.0, por lo que cualquiera puede reimplementarlo: tus grabaciones no son rehenes de un formato propietario, y las nuestras tampoco. Y se ha puesto a prueba de verdad, no es una demo: 1393 pruebas en Node 20 y Node 22. Puedes leer el código fuente, comprobar el formato y ejecutar la suite de pruebas tú mismo antes de confiarle las ejecuciones de tu equipo a cualquiera de estos elementos.

La conclusión

Un panel es una factura. Una traza registrada es la ejecución. Si tu plan para depurar agentes de IA termina en un panel de costos, no tienes un plan de depuración: tienes un sistema de facturación. El panel siempre podrá decirte cuánto costó una ejecución, y nunca podrá decirte por qué el agente borró tu archivo, porque el "porqué" vive en la secuencia, y la secuencia solo existe si la conservaste.

El método completo consta de cuatro pasos:

• Registre las ejecuciones.

• Lee la cronología.

• Comprueba las aristas del grafo.

Repite los que te asustan, gratis, tantas veces como quieras.

Nota sobre las fuentes: todas las cifras de este artículo han sido declaradas por el proveedor, tanto las de nuestro propio producto como las del repositorio OrcaReplay y su documentación: el comportamiento del código de salida de una ejecución; la corrección registrada de 14 eventos con su diff de +1 -3 y su comprobación de exit-1; el etiquetado de aristas en el grafo orca; la cadencia de una instantánea por turno; la reproducción sin conexión con la red bloqueada; y la suite de 1393 pruebas en Node 20 y Node 22. En este artículo no se cita ninguna medición de terceros. La suite de 1393 pruebas es la única afirmación que puedes verificar por ti mismo, clonando el repositorio y ejecutándola. Todos los elementos se comprobaron por última vez el 4 de septiembre de 2026.