CodeTracer: Hacia Estados de Agente Rastreables

CodeTracer: Towards Traceable Agent States

April 13, 2026

Autores: Han Li, Yifan Yao, Letian Zhu, Rili Feng, Hongyi Ye, Jiaming Wang, Yancheng He, Pengyu Zou, Lehan Zhang, Xinping Lei, Haoyang Huang, Ken Deng, Ming Sun, Zhaoxiang Zhang, He Ye, Jiaheng Liu

cs.AI

Resumen

Los agentes de código están avanzando rápidamente, pero depurarlos se está volviendo cada vez más difícil. A medida que los frameworks coordinan llamadas paralelas a herramientas y flujos de trabajo multi-etapa para tareas complejas, las transiciones de estado del agente y la propagación de errores se vuelven difíciles de observar. En estas ejecuciones, un paso en falso inicial puede atrapar al agente en bucles improductivos o incluso desencadenar errores fundamentales en cascada, formando cadenas de errores ocultas que dificultan identificar cuándo y por qué el agente se desvía del camino correcto. Los análisis de trazabilidad de agentes existentes se centran en interacciones simples o dependen de inspecciones manuales a pequeña escala, lo que limita su escalabilidad y utilidad para flujos de trabajo de codificación reales. Presentamos CodeTracer, una arquitectura de trazabilidad que analiza artefactos de ejecución heterogéneos mediante extractores en evolución, reconstruye el historial completo de transiciones de estado como un árbol de trazas jerárquico con memoria persistente y realiza una localización del inicio de fallos para identificar el origen del error y su cadena de propagación. Para permitir una evaluación sistemática, construimos CodeTraceBench a partir de una amplia colección de trayectorias ejecutadas generadas por cuatro frameworks de agentes de código ampliamente utilizados en diversas tareas de programación (por ejemplo, corrección de errores, refactorización e interacción con terminal), con supervisión a nivel de etapa y de paso para la localización de fallos. Los experimentos muestran que CodeTracer supera sustancialmente a los métodos de *prompting* directo y a las líneas base livianas, y que la reproducción de sus señales de diagnóstico recupera consistentemente las ejecuciones fallidas originales bajo presupuestos equivalentes. Nuestro código y datos están disponibles públicamente.

English

Code agents are advancing rapidly, but debugging them is becoming increasingly difficult. As frameworks orchestrate parallel tool calls and multi-stage workflows over complex tasks, making the agent's state transitions and error propagation hard to observe. In these runs, an early misstep can trap the agent in unproductive loops or even cascade into fundamental errors, forming hidden error chains that make it hard to tell when the agent goes off track and why. Existing agent tracing analyses either focus on simple interaction or rely on small-scale manual inspection, which limits their scalability and usefulness for real coding workflows. We present CodeTracer, a tracing architecture that parses heterogeneous run artifacts through evolving extractors, reconstructs the full state transition history as a hierarchical trace tree with persistent memory, and performs failure onset localization to pinpoint the failure origin and its downstream chain. To enable systematic evaluation, we construct CodeTraceBench from a large collection of executed trajectories generated by four widely used code agent frameworks on diverse code tasks (e.g., bug fixing, refactoring, and terminal interaction), with supervision at both the stage and step levels for failure localization. Experiments show that CodeTracer substantially outperforms direct prompting and lightweight baselines, and that replaying its diagnostic signals consistently recovers originally failed runs under matched budgets. Our code and data are publicly available.