CodeTracer: Verso Stati Agente Tracciabili

CodeTracer: Towards Traceable Agent States

April 13, 2026

Autori: 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

Abstract

Gli agenti di codice stanno progredendo rapidamente, ma il debug degli stessi sta diventando sempre più difficile. Poiché i framework orchestrano chiamate parallele a strumenti e flussi di lavoro multi-stadio su compiti complessi, le transizioni di stato dell'agente e la propagazione degli errori diventano difficili da osservare. In queste esecuzioni, un passo falso iniziale può intrappolare l'agente in loop improduttivi o persino degenerare in errori fondamentali, formando catene di errori nascoste che rendono difficile capire quando l'agente devia dal percorso e perché. Le attuali analisi di tracciamento degli agenti si concentrano su interazioni semplici o si basano su ispezioni manuali su piccola scala, limitandone la scalabilità e l'utilità per flussi di lavoro di codifica reali. Presentiamo CodeTracer, un'architettura di tracciamento che analizza artefatti di esecuzione eterogenei tramite estrattori evolutivi, ricostruisce la cronologia completa delle transizioni di stato come un albero di traccia gerarchico con memoria persistente ed esegue la localizzazione dell'insorgenza di fallimenti per identificare l'origine del fallimento e la sua catena discendente. Per abilitare una valutazione sistematica, costruiamo CodeTraceBench da una vasta raccolta di traiettorie eseguite generate da quattro framework di agenti di codice ampiamente utilizzati su vari compiti di programmazione (ad esempio, correzione di bug, refactoring e interazione con terminale), con supervisione a livello di stadio e di passo per la localizzazione dei fallimenti. Gli esperimenti mostrano che CodeTracer supera sostanzialmente il prompting diretto e i baseline leggeri, e che la riproduzione dei suoi segnali diagnostici recupera costantemente le esecuzioni originariamente fallite con budget equivalenti. Il nostro codice e i nostri dati sono pubblicamente disponibili.

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.