AgentDebugX: An Open-Source Toolkit for Failure Observability, Attribution, and Recovery in LLM Agents
Kunlun Zhu, Xuyan Ye, Zhiguang Han, Yuchen Zhao, Bingxuan Li, Weijia Zhang, Muxin Tian, Xiangru Tang, Pan Lu, James Zou, Jiaxuan You, Heng Ji
cs.AI, cs.CL
2026-07-21
LLM agent 的报错常出现在错的步骤。AgentDebugX 把调试做成 Detect→Attribute→Recover→Rerun 闭环,核心 DeepDebug 多轮定位根因,在 GAIA 上把失败任务救回 13/73,整体准确率 55.8%→63.6%。
LLM agent 跑起来是多步的:调工具、读返回、再决策。一旦失败,报错往往冒在某一步,真正出问题的却是更早的一步。参数拼错了、上下文漏了一条信息,几步之后才表现为结果不对。现有可观测工具能把执行轨迹重放出来,但重放只让你「看到哪步炸了」,不告诉你「根因是哪步」,更不会把诊断变成可执行的修复。AgentDebugX 想补上从观测到修复这一段。
框架把调试组织成一个闭环,四步循环:Detect(检测)用确定性规则包加 LLM 裁判,在一个 19 类的失败模式分类法下识别可观测失败;Attribute(归因)把症状追溯回责任步骤,手段从轻到重是启发式、单遍读轨迹、二分搜索、集成;Recover(修复)把诊断翻成重试指令,可走原生 DeepDebug 通道,也可接 Reflexion、CRITIC、AutoManual;Rerun(重跑)从检查点执行修正,带策略门控。
核心是 DeepDebug,一个多轮根因诊断 agent。它先全局读一遍轨迹挑一个初始候选步骤;再结构化深挖,多 agent 场景走「交接级联」(handoff cascade),单 agent 走二分;接着交叉质询(cross-examination)在两个候选之间裁决;最后产出结构化报告,含责任 agent/步骤、证据、解释、具体改法。
几个设计决定了它能不能落地。轨迹用一个与框架无关的中间表示(AgentTrajectory 加 AgentEvents),诊断叠在轨迹之上、不篡改原始证据,因此能接到不同 agent 框架上。成本是逐级升级的:规则能解决就不动模型,单遍不够才上 DeepDebug,后者约是单遍的 1.6 倍 token 开销。存储本地优先,可选地把脱敏后的「轨迹-诊断-修复」包共享到一个 Error Hub。
Who&When 基准(184 条轨迹)上,DeepDebug(qwen3.5-9b)的严格「agent 加步骤」准确率 28.8%,最好的单遍基线 21.7%;责任 agent 准确率 56.0% vs 47.8%;步骤定位(±1)44.0% vs 38.6%。换 qwen3.6-27b,严格准确率 38.0% vs 36.4%。多轮的优势集中在 40 个事件以上的长轨迹。
端到端的 GAIA 验证(165 个任务)更能说明问题。基线 agent(qwen3.5-9b)准确率 55.8%,有 73 个失败任务;DeepDebug 单次重跑救回 13/73,整体准确率提到 63.6%。对照几个解耦的修复方法:Reflexion 6/73(59.4%)、AutoManual 5/73(58.8%)、CRITIC 4/73(58.2%)。最大增益出现在 Level-2 多跳任务,从 48.8% 升到 61.6%。
成本上,单遍通读一条完整轨迹约 8.1K token,DeepDebug 约 12.8K(1.6 倍),靠后几轮聚焦读窗口压住了开销。
对做 agent 的工程团队,这是一个可直接拿来用的开源调试基建。它把「失败可观测」往前推到了「失败可归因、可修复」,而且归因模块设计成框架无关,接到自家 agent 栈上不用大改。13/73 的救回率不算惊艳,但这是单次重跑、无人工介入的结果,且明确指向「根因定位比盲目重试有用」这个方向。
作者自己划的边界:评测只覆盖自动归因和修复,没量化开发者省下的调试时间或控制台好不好用;Who&When 用的是参考答案协议,DeepDebug 的增益随底座模型波动;GAIA 只评了一个策略模型、一个固定子集,没有单独隔离归因这一环的贡献。Error Hub 的检索和分类法归纳实现了但还没评。
还有两处工程上的现实约束:脱敏靠模式匹配,作者明确说不能保证抹掉任意敏感内容;重跑修复需要人工审批门控,不是全自动。