CodeTracer: К отслеживаемым состояниям агента

CodeTracer: Towards Traceable Agent States

April 13, 2026

Авторы: 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

Аннотация

Кодовые агенты быстро развиваются, но их отладка становится все сложнее. Поскольку фреймворки организуют параллельные вызовы инструментов и многоэтапные рабочие процессы для сложных задач, переходы между состояниями агента и распространение ошибок становятся труднонаблюдаемыми. В таких запусках ранняя ошибка может загнать агента в непродуктивные циклы или даже привести к фундаментальным сбоям, формируя скрытые цепочки ошибок, которые затрудняют определение момента и причины отклонения агента от правильного пути. Существующие методы трассировки агентов фокусируются либо на простом взаимодействии, либо полагаются на ручной анализ небольших масштабов, что ограничивает их масштабируемость и полезность для реальных рабочих процессов программирования. Мы представляем CodeTracer — архитектуру трассировки, которая анализирует гетерогенные артефакты выполнения с помощью развивающихся экстракторов, восстанавливает полную историю переходов состояний в виде иерархического дерева трассировки с постоянной памятью и выполняет локализацию начала сбоя для точного определения источника ошибки и ее последующей цепочки. Для систематической оценки мы создали CodeTraceBench на основе большой коллекции выполненных траекторий, сгенерированных четырьмя широко используемыми фреймворками кодовых агентов для различных задач (например, исправление ошибок, рефакторинг и взаимодействие с терминалом), с контролем на уровне этапов и шагов для локализации сбоев. Эксперименты показывают, что CodeTracer значительно превосходит прямое промптирование и облегченные базовые методы, а воспроизведение его диагностических сигналов стабильно восстанавливает первоначально неудачные запуски при сопоставимых ресурсах. Наш код и данные находятся в открытом доступе.

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.