CodeTracer: Naar traceerbare agenttoestanden

CodeTracer: Towards Traceable Agent States

April 13, 2026

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

Samenvatting

Code-agents ontwikkelen zich snel, maar het debuggen ervan wordt steeds moeilijker. Doordat frameworks parallelle toolaanroepen en meerfasige workflows voor complexe taken aansturen, worden de toestandsovergangen van de agent en foutpropagatie lastig waarneembaar. Tijdens deze runs kan een vroege misstap de agent vastzetten in onproductieve loops of zelfs leiden tot fundamentele fouten, waarbij verborgen foutketens ontstaan die het moeilijk maken te zien wanneer en waarom de agent afdwaalt. Bestaande traceringsanalyses voor agents richten zich ofwel op eenvoudige interactie of vertrouwen op kleinschalige handmatige inspectie, wat hun schaalbaarheid en bruikbaarheid voor echte codeerworkflows beperkt. Wij presenteren CodeTracer, een traceringsarchitectuur die heterogene run-artefacten parseert via evoluerende extractors, de volledige geschiedenis van toestandsovergangen reconstrueert als een hiërarchische traceboom met persistent geheugen, en de oorsprong van fouten lokaliseert om de foutbron en de downstream-keten aan te wijzen. Voor een systematische evaluatie bouwen we CodeTraceBench vanuit een grote verzameling uitgevoerde trajecten, gegenereerd door vier veelgebruikte code-agentframeworks voor diverse codetaken (zoals bugfixes, refactoring en terminalinteractie), met supervisie op zowel stadium- als stapniveau voor foutlocalisatie. Experimenten tonen aan dat CodeTracer direct prompting en lichtgewicht baseline-methoden aanzienlijk overtreft, en dat het opnieuw afspelen van zijn diagnostische signalen oorspronkelijk mislukte runs consistent herstelt binnen gelijke budgetten. Onze code en data zijn openbaar beschikbaar.

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.