CodeTracer: Rumo a Estados de Agente Rastreáveis

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

Resumo

Os agentes de código estão avançando rapidamente, mas a depuração deles está se tornando cada vez mais difícil. À medida que os frameworks orquestram chamadas paralelas de ferramentas e fluxos de trabalho multiestágio em tarefas complexas, as transições de estado do agente e a propagação de erros tornam-se difíceis de observar. Nessas execuções, um passo em fogo inicial pode prender o agente em loops improdutivos ou mesmo desencadear erros fundamentais, formando cadeias de erros ocultas que dificultam a identificação de quando e por que o agente saiu do rumo. As análises de rastreamento de agentes existentes focam-se em interações simples ou dependem de inspeção manual em pequena escala, o que limita sua escalabilidade e utilidade para fluxos de trabalho reais de codificação. Apresentamos o CodeTracer, uma arquitetura de rastreamento que analisa artefatos de execução heterogéneos através de extratores em evolução, reconstrói o histórico completo de transições de estado como uma árvore de rastreamento hierárquica com memória persistente e realiza a localização do início da falha para identificar a origem da falha e sua cadeia descendente. Para permitir uma avaliação sistemática, construímos o CodeTraceBench a partir de uma grande coleção de trajetórias executadas geradas por quatro frameworks de agentes de código amplamente utilizados em diversas tarefas de código (por exemplo, correção de bugs, refatoração e interação com terminal), com supervisão tanto a nível de estágio quanto de etapa para localização de falhas. Os experimentos mostram que o CodeTracer supera substancialmente o *prompting* direto e as *baselines* leves, e que a reprodução dos seus sinais de diagnóstico recupera consistentemente execuções originalmente falhadas sob orçamentos equivalentes. O nosso código e dados estão publicamente disponíveis.

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.