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

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.

한 줄 요약

AgentDebugX는 LLM 에이전트 실패를 추적·진단·복구하는 반복적 디버깅 프레임워크로, DeepDebug를 핵심으로 정확도와 복구 성능을 향상시킨다.

핵심 기여도

DeepDebug를 통해 Who&When 벤치마크에서 qwen3.5-9b 모델 기반으로 28.8%의 정확한 에이전트-스탭 속성 정확도 달성 (기존 최고 기록).
GAIA 데이터셋에서 DeepDebug의 단일 재실행으로 73개 실패 중 13개 복구, 정확도 55.8% → 63.6% 향상.
Detect → Attribute → Recover → Rerun의 반복적 디버깅 루프를 제공하며, Error Hub를 통해 실패-진단-복구 패키지를 공유 및 재사용 가능.

핵심 아이디어

LLM 에이전트의 실패는 종종 원인과 증상이 다른 단계에서 발생하기 때문에 디버깅이 어렵다. AgentDebugX는 이 문제를 해결하기 위해 실패 감지, 원인 추적, 복구, 재실행의 반복 루프를 구성한다. 이 루프의 핵심은 DeepDebug로, 전역 트레이잭토리 이해, 구조 지도형 조사, 후보 간 교차 검증을 통해 다중 턴의 원인 진단을 수행한다. DeepDebug는 단일 턴 기반 기법 대비 7.1% 높은 정확도를 보이며, GAIA 데이터셋에서 13개의 복구 성공 사례를 기록해 기존 4~6개 대비 2배 이상의 성능 향상을 보인다.

기술적 접근법

**DeepDebug**: 전역 트레이잭토리 이해, 구조 지도형 조사, 교차 검증을 통해 원인을 다중 턴으로 추적.
**Detect**: 실행 로그를 휴대용 트레이잭토리로 변환.
**Attribute**: 증상과 원인을 연결.
**Recover**: 진단을 구체적인 재실행 지시사항으로 변환.
**Rerun**: 수정된 실행을 테스트하며 비교.
**Error Hub**: 정제된 실패-진단-복구 패키지를 저장 및 공유.

주요 결과

**Who&When 벤치마크**: DeepDebug는 qwen3.5-9b에서 28.8%의 정확한 에이전트-스탭 속성 정확도를 달성 (기존 최고 기록).
**GAIA 데이터셋**: DeepDebug는 73개 실패 중 13개 복구 (기존 4~6개 대비 2배 이상), 전체 정확도 55.8% → 63.6% 향상.
**기존 기법 대비**: 단일 턴 기반 기법 대비 7.1% 높은 정확도, 복구 성공률 2배 이상 증가.

의의 및 한계

AgentDebugX는 LLM 에이전트의 실패를 체계적으로 추적하고 복구할 수 있는 첫 번째 반복적 디버깅 프레임워크로, DeepDebug의 정확한 원인 추적 능력과 Error Hub의 공유 기능은 향후 에이전트 개발의 신뢰성 향상에 기여할 수 있다. 그러나 현재는 open-weight 모델에만 적용되었으며, 다른 모델 아키텍처나 복잡한 다 에이전트 시스템에 대한 평가가 부족한 점은 한계로 작용한다.

실용적 활용

AgentDebugX는 LLM 에이전트 기반의 소프트웨어 개발, API 연동, 멀티에이전트 협업 시스템 등에서 실패를 체계적으로 관리하고 개선할 수 있는 도구로 활용 가능하다. 특히, CI/CD 파이프라인에서 실시간 실패 추적 및 복구를 지원하는 데 유용하다.