AgentDebugX: An Open-Source Toolkit for Failure Observability, Attribution, and Recovery in LLM Agents

2026-07-21

AI Summary

This work addresses the challenge that errors in large language model (LLM) agents often manifest at locations distinct from their root causes, hindering precise diagnosis and repair. To tackle this, we propose DeepDebug, a closed-loop debugging framework that systematically diagnoses failures through four stages: detection, attribution, recovery, and re-execution. Its key innovation lies in a multi-round root cause diagnosis mechanism that integrates global trajectory understanding, structure-guided investigation, and cross-validation, alongside a shareable knowledge base of error diagnoses and fixes. DeepDebug offers a Python library, CLI, web console, and installable agent skills to support trajectory analysis and automated repair. Evaluated on the Who and When benchmark, it achieves a root cause attribution accuracy of 28.8%, and on the GAIA dataset, it successfully repairs 13 previously failed tasks in a single re-execution, improving overall accuracy from 55.8% to 63.6%.

Abstract

LLM agent failures are difficult to debug because the step where an error surfaces is often not the one that caused it. Existing observability tools replay execution traces but provide little support for identifying the root cause or translating diagnosis into recovery. We present AgentDebugX, an open-source debugging framework that organizes debugging as a closed loop of Detect, Attribute, Recover, and Rerun. At its core, DeepDebug performs multi-turn root-cause diagnosis through global trajectory understanding, structure-guided investigation, and cross-examination. On the Who and When benchmark, DeepDebug achieves the best strict attribution accuracy among the evaluated methods on both tested open-weight backbones, reaching 28.8 percent exact agent-and-step accuracy on qwen3.5-9b versus 21.7 percent for the strongest single-pass baseline. On GAIA, DeepDebug repairs 13 of 73 failed tasks in a single rerun, compared with 4 to 6 for three decoupled self-correction baselines, improving overall accuracy from 55.8 percent to 63.6 percent. AgentDebugX exposes this workflow through a Python library, CLI, web console, and installable agentic skill, and provides an opt-in Error Hub for sharing scrubbed failure-diagnosis-repair bundles and reusing them as debugging memory.

Problem

• LLM agents
• failure debugging
• root cause attribution
• error recovery
• observability

Innovation

• LLM agent debugging
• root-cause attribution
• failure recovery
• observability framework
• error memory