CodeTracer: Auf dem Weg zu nachvollziehbaren Agentenzuständen

CodeTracer: Towards Traceable Agent States

April 13, 2026

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

Zusammenfassung

Code Agents entwickeln sich rasant, aber das Debugging wird zunehmend schwieriger. Da Frameworks parallele Tool-Aufrufe und mehrstufige Workflows für komplexe Aufgaben orchestrieren, werden die Zustandsübergänge des Agents und die Fehlerausbreitung schwer beobachtbar. Bei solchen Läufen kann ein früher Fehltritt den Agenten in unproduktiven Schleifen fangen oder sogar zu grundlegenden Fehlern kaskadieren, wodurch versteckte Fehlerketten entstehen, die es schwer machen zu erkennen, wann und warum der Agent vom Kurs abkommt. Bestehende Agent-Tracing-Analysen konzentrieren sich entweder auf einfache Interaktionen oder stützen sich auf manuelle Inspektion im kleinen Maßstab, was ihre Skalierbarkeit und Nützlichkeit für echte Code-Workflows einschränkt. Wir stellen CodeTracer vor, eine Tracing-Architektur, die heterogene Laufzeitartefakte durch sich entwickelnde Extraktoren analysiert, den vollständigen Zustandsübergangsverlauf als hierarchischen Trace-Baum mit persistentem Speicher rekonstruiert und eine Failure-Onset-Lokalisierung durchführt, um den Fehlerursprung und seine nachgelagerte Kette zu identifizieren. Um eine systematische Evaluation zu ermöglichen, haben wir CodeTraceBench aus einer großen Sammlung ausgeführter Trajektorien erstellt, die von vier weit verbreiteten Code-Agent-Frameworks auf verschiedenen Code-Aufgaben (z.B. Bugfixing, Refactoring und Terminalinteraktion) generiert wurden, mit Supervision auf sowohl Ebenen- als auch Schrittschritt-Ebene für die Fehlerlokalisierung. Experimente zeigen, dass CodeTracer direkte Prompting- und leichtgewichtige Baseline-Methoden erheblich übertrifft und dass das Replay seiner diagnostischen Signale ursprünglich fehlgeschlagene Läufe unter gleichen Budgetbedingungen konsistent wiederherstellt. Unser Code und unsere Daten sind öffentlich verfügbar.

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.