AgentDebugX：LLM智能体故障可观测、归因与恢复的开源工具包 AgentDebugX: An Open-Source Toolkit for Failure Observability, Attribution, and Recovery in LLM Agents
把智能体调试组织为检测-归因-恢复-重跑闭环，DeepDebug多轮根因诊断刷新归因SOTA
前置知识
执行轨迹（Trajectory / Trace）
智能体完成任务时产生的有序事件记录：LLM调用、工具调用与结果、记忆读写、智能体间交接、界面操作等，每个事件记录执行者、模块、步骤索引、输入输出与错误工件。轨迹相当于分布式系统中的分布式追踪，是调试的数据基础。
本文所有检测、归因、重跑都建立在统一的可移植轨迹表示 AgentTrajectory 之上，不理解轨迹概念就无法理解其框架无关设计与诊断叠加层机制。
故障归因（Failure Attribution）
在失败症状与真正原因之间建立因果联系：确定是哪一步、哪个智能体的哪个决定导致任务失败。它与故障检测不同——检测找到『哪里表现出错』，归因要找到『改掉哪里最可能避免失败』，二者往往相隔多个步骤。
论文的核心评测指标（Who&When 上的责任智能体准确率与步骤定位准确率）衡量的就是归因能力，DeepDebug 的四阶段设计全部服务于提升它。
自我纠错（Self-Correction）
让模型在失败后反思并重试的范式，代表工作包括 Reflexion、Self-Refine、CRITIC、AutoManual。Tyen 等 2024 年证明：模型在不知道错误位置时很难发现错误，但一旦给出错误位置，纠错可靠性大幅提升。
这解释了『归因先行』的合理性：本文把定位到的根因直接作为重试指令，GAIA 上修复数达到解耦自我纠错基线的 2–3 倍。
OpenTelemetry GenAI 语义约定
CNCF 开源可观测性标准 OpenTelemetry 针对生成式 AI 的语义约定，定义 invoke_agent、chat、execute_tool、handoff 等 span 类型，使不同框架产生的智能体执行能以统一格式导出，被通用 APM 工具采集与分析。
AgentDebugX 的事件可投影为 OTel GenAI span，这是其『轨迹格式框架无关、可与现有观测栈互操作』这一卖点的技术基础。
二分搜索式归因
把逐步检查轨迹的线性 $O(N)$ 成本降到对数 $O(\log N)$ 的策略：反复取当前步骤区间的中点，判断根因在中点之前还是之后，不断收缩区间直到逼近责任步骤，用少量 LLM 调用换取定位。
它是本文归因策略家族中的一档，也是 DeepDebug 结构引导侦查在单智能体分支上的原型，理解其成本分级设计需要这一概念。
研究动机
LLM 智能体在长程推理、外部工具调用、记忆与多智能体协作中一旦失败极难调试，核心困难是：错误暴露的步骤往往不是造成错误的步骤。例如智能体可能因为早期遗漏的规划约束、过期的记忆检索、无效的中间假设或智能体间错误交接而返回错误答案，但症状只在很多步之后才以失败的工具调用、下游不一致决策或无依据的最终回答的形式浮现，因此单纯回放轨迹很少够用。现有工具只覆盖链条片段：Langfuse、LangSmith、Phoenix 等可观测平台能录制并回放详细轨迹，却把『哪一步负责、为什么、怎么修』留给开发者；AgentDebug、MAST、Who&When、TRAIL、AgenTracer 等分类法与归因基准证明强模型也难以定位根因，但只作为独立分析而非可部署基础设施存在；Reflexion、Self-Refine 等自我纠错方法则表明纠错在错误位置已知时才可靠（Tyen et al., 2024），自身却缺少定位能力。
本文的目标是本文的目标是把智能体调试从『看日志猜原因』升级为一条可工程化落地的闭环流水线：给定一次线上执行或导出的日志，系统自动检测可观测的失败症状（Detect），把症状向上游追溯到『修复它最可能避免失败』的责任步骤（Attribute），把诊断转化为具体可执行的重试指令（Recover），再从合适检查点重跑并保留原轨迹与修复轨迹供对比验证（Rerun）；若重跑仍失败，新轨迹重新进入循环。同时作者要求诊断结果可审计（附证据与置信度）、可跨框架共享（统一轨迹表示与 OTel 导出）、可积累（把失败诊断-修复案例存入脱敏 Error Hub 作为团队调试记忆），并在 Who&When 归因基准和 GAIA 端到端恢复任务上验证：这套闭环确实能同时提高定位准确率与修复成功率。
与已有工作不同的是，独特切入角度是『打通全链路』而非单点改进：现有工作要么只做观测（轨迹平台）、要么只做归因（基准与分类法）、要么只做纠错（自我修正），彼此不衔接，Table 1 显示没有先例同时覆盖可移植 schema、分类学、归因、恢复与错误共享库五项。AgentDebugX 把四者接到同一个可移植调试工件 AgentTrajectory 上，且关键设计是诊断以『叠加层』附着在轨迹之上而不回写原始证据，同一份执行可被任何方法反复分析、跨版本比较、作为回归用例共享。另一差异点是成本感知的归因家族：从免费规则、单遍全文读取，到 $O(\log N)$ 二分与约 5 次调用的 DeepDebug 多轮代理，按精度-延迟分级、只升级含糊案例；并配套政策门控的重跑与模式脱敏的 Error Hub，把单次调试升级为组织级学习。
核心方法
直觉上调试智能体类似调试分布式系统：先确定『哪里看起来坏了』，再回溯『哪里真正坏了』，然后『修好并重跑验证』。AgentDebugX 把它实现为四阶段闭环：Detect 阶段先用确定性规则包零模型调用识别畸形工具调用、无进展循环、无效输出、过早宣告成功等机械可验证失败，不足时由 LLM 判官读取任务目标与有界轨迹窗口输出类型化发现（受影响事件、失败模式、证据、置信度）；Attribute 阶段用一组按成本分级的归因策略把症状追溯到责任步骤，每个归因器返回带置信度与出处的排序假设而非唯一断言，含糊案例升级给 DeepDebug；Recover 阶段把定位结果转成重试指令，默认直接采用 DeepDebug 的修复建议，Reflexion、CRITIC、AutoManual 作为替代恢复器（全部仅建议、需人工或政策批准）；Rerun 阶段把诊断、检查点和重试指令打包成重跑请求，执行器生成新轨迹并与原轨迹并列保存打分，成功存为已解决案例、失败重新进入检测。各阶段通过统一工件衔接，复杂案例交给 DeepDebug 多轮诊断代理。
核心创新是 DeepDebug 多轮根因诊断代理，针对单遍读轨迹无法可靠定位的失败。其出发点是两种单遍策略的互补盲区：全局通读保留任务上下文，但容易被最响亮的下游症状锚定；逐步扫描能聚焦，却丢失目标感、分不清『因果性错误』与『局部罕见但合法』的动作。DeepDebug 用四步化解：第一步全局通读整条轨迹、重建目标与历史并给出初始候选步骤；第二步按轨迹形状做结构引导侦查——多智能体运行沿交接级联从可见失败向上游走到最早毁掉任务的步骤，单智能体运行对步骤区间二分并重读存活区域，得到独立第二候选；第三步交叉质证，两候选一致即接受，不一致则并排检查两者的上下文、输入、输出与下游影响，选出更强的因果解释，把全轨迹搜索压缩为二元裁决；第四步输出结构化报告：责任智能体与步骤、通俗解释、引用证据和一个具体修复，每次检查留痕形成审计链；代理只读轨迹、绝不重新执行工具。
方法步骤详情
完整流程分四段。捕获：运行时适配器（ReAct、LangGraph、CrewAI、OpenAI Agents SDK、OTel GenAI）或离线导入器把框架事件转换为 AgentTrajectory——有序 AgentEvent 序列，记录执行智能体、步骤索引、输入输出、错误与截图等工件，可投影为 OTel span，轨迹以追加式 JSONL 或 SQLite 持久化。检测：规则包零模型调用标注机械可验证失败，不足时 LLM 判官在共享分类学（19 个种子模式，覆盖规划、记忆、工具、验证、协调）内输出带证据与置信度的类型化发现。归因：按预算从免费规则、All-at-Once 全文读取、逐步检查、二分搜索（$O(\log N)$）到约 5 次调用的 DeepDebug 中选择，歧义案例自动升级，每个归因器返回带出处的排序假设。恢复：把根因步骤、失败模式、证据与上下文转成重试指令。重跑：运行时专用执行器从检查点重生成，分支按目标打分、与原轨迹并列保存；控制台提供『选轨迹→跳到责任事件→看证据与修复→建重跑分支』四步工作流，另有 CLI 与可安装 skill。
技术新颖性
技术新颖性体现在四点。其一，归因以『策略家族』而非单一算法呈现，每个后端声明推理成本（免费规则、单次调用、$O(\log N)$/$O(N)$ 搜索、约 5 次调用的 DeepDebug），部署可按精度-延迟曲线调档；由于只升级歧义案例，DeepDebug 实测 12.8K token 仅为单遍 8.1K 的 1.6 倍。其二，交叉质证把根因选择从全轨迹搜索降为两个候选间的裁决，这是在 Who&When 上取得 28.8% 严格联合准确率的关键结构。其三，诊断以层叠方式附着在不可变轨迹上，配合可扩展失败分类学（诱导器对残留 novel 模式聚类、人工审核后入库而不覆盖种子集）与默认剥离输入并做凭证/PII 模式脱敏的 Error Hub，使失败知识可跨团队复用而不污染原始证据。其四，DeepDebug 打包成可安装的 agentic skill 与统一 CLI 契约，让 Claude Code、OpenClaw、Hermes 等宿主智能体自行规范化、诊断自己的失败运行并把修复写回下一次尝试——调试器本身成为智能体可调用的工具。
实验结果
归因：全部 184 条 Who&When 轨迹上（策略 qwen3.5-9b，诊断 gemini-2.5-flash），DeepDebug 责任智能体准确率 56.0% 对最强单遍基线 47.8%；精确步骤 28.8% 对 22.3%；严格『智能体+精确步骤』联合 28.8% 对 21.7%，±1 口径为 32.1% 对 23.9%。收益迁移到 qwen3.6-27b（38.0% 对 36.4%），但 gpt-5.4-mini 等托管模型上单遍读取已更强，多轮裁决是模型依赖的。优势集中在超 40 事件的长轨迹（仅 26 条）。恢复：GAIA 验证集 165 题中原始智能体失败 73 题，单次重跑 DeepDebug 修复 13/73，约为 Reflexion(6)、AutoManual(5)、CRITIC(4) 的 2–3 倍，总准确率 55.8%→63.6%，Level-2 多跳增益最大（48.8%→61.6%）。成本：约 12.8K token，仅为单遍 8.1K 的 1.6 倍；消融：结构引导侦查换为二次全局搜索，gpt-5.4-mini 严格准确率 0.310→0.262。
查看结构化数据
| 任务 | 指标 | 本文 | 基线 | 提升 |
|---|---|---|---|---|
| Who&When 多智能体故障归因（n=184，qwen3.5-9b） | 责任智能体准确率（who） | DeepDebug 56.0% | All-at-Once 47.8%（最强单遍基线） | +8.2 个百分点 |
| Who&When 故障归因（n=184，qwen3.5-9b） | 智能体+精确步骤联合准确率（A+S exact） | DeepDebug 28.8% | All-at-Once 21.7% | +7.1 个百分点 |
| Who&When 故障归因（n=184，qwen3.5-9b） | 步骤定位 ±1 准确率 | DeepDebug 44.0% | Binary-Search 38.6% | +5.4 个百分点 |
| GAIA 验证集端到端恢复（165 题，73 题原始失败） | 单次重跑修复任务数 | DeepDebug 13/73 | Reflexion 6/73、AutoManual 5/73、CRITIC 4/73 | 约 2–3 倍 |
| GAIA 验证集端到端恢复（165 题） | 总体准确率（官方评分器） | 63.6%（L1 81.1 / L2 61.6 / L3 34.6） | 原始智能体重跑 55.8% | +7.9 个百分点（L2 +12.8） |
局限与改进
作者明确承认的局限：评测只覆盖自动归因与恢复，未测量开发者实际调试时间或控制台可用性；评测期间诊断记忆与 Error Hub 保持为空，其检索增益与分类学归纳均『已实现但未评测』，归纳还需人工接受；重跑使用温度 0、固定步骤预算和与基线相同的搜索工具栈；GAIA 实验在固定 73 题失败子集上比较完整重试配方，既未单独隔离归因贡献，也非盲测单次打分；收益随模型变化（托管强模型上多轮无益），额外调用并非普遍有益。我的补充观察：Who&When 仅 184 条轨迹且长轨迹段只有 26 条，28.8% 的严格绝对准确率仍远低于可用水平，说明根因定位本质仍很难；恢复实验的被调试策略只有 qwen3.5-9b 一个；Error Hub 脱敏只做模式匹配与整字段剥离，无法保证清除任意敏感内容；19 种子分类学对各场景的覆盖率未量化。
独立分析的弱点
独立分析三个弱点。第一，严格联合准确率 28.8% 意味着七成以上失败仍定位错误，且 ±1 口径 32.1% 与精确口径差距明显，说明定位粒度对下游修复高度敏感——改进方向是把归因从单点责任扩展为因果链（如对前缀做反事实重放），给出『若在步骤 $k$ 纠正则成功概率提升多少』的量化估计，并对高风险场景输出多假设而非单一裁决。第二，GAIA 恢复实验用 DeepDebug 完整配方对比『只拿到泛化失败摘要』的解耦基线，增益可能混杂『修复文本本身质量』与『归因定位』两个因素——更干净的实验应给基线相同的定位信息以隔离归因贡献，作者也承认这点。第三，托管强模型上多轮裁决无益（gemini-3.5-flash 单读最强）但论文未给自动路由准则——可训练轻量元预测器，根据轨迹长度、模型与症状类型预判是否值得升级。另外 Error Hub 脱敏仅靠正则与整字段剥离，企业落地需与强制人工审核绑定；分类学归纳依赖人工接受，规模化后审核负担会快速增长。
未来方向
作者指出或隐含的方向：把 Error Hub 案例检索与分类学归纳真正接入诊断（当前『已实现但未评测』），让 DeepDebug 能检索相似历史失败来播种假设；评测开发者调试时间与控制台可用性；构建跨模型路由策略，让升级机制在托管强模型上自动退化为单遍读取。基于成果可延伸：其一，把 Error Hub 积累的案例变成动态演化基准，追踪归因方法随失败形态分布漂移的表现；其二，把政策门控重跑与 CI 集成，失败案例自动固化为回归测试，在合并前拦截已知根因复发；其三，结构引导侦查目前限于交接级联/二分，可推广到带工具副作用的环境状态反演——从最终环境快照反推最早破坏状态一致性的一步；其四，多智能体场景把归因与信用分配结合，用定位信号生成针对性微调数据（AgenTracer 式），形成『调试→归因→训练』飞轮；其五，GUI/computer-use 智能体的视觉通道根因推理目前只有 OSWorld 导入器雏形，值得深化。
复现评估
复现条件很好：MIT 许可完全开源，pip install agentdebugx 即装，代码、完整提示词库、附录 C 评测协议与一键重现 Table 3 的脚本随仓库发布；公开 API 仅 AgentDebug、TraceSession、AgentTrajectory、FailureFinding、DiagnosticReport 五个核心类型，一个上下文管理器即可接入。评测资产公开：Who&When 全部 184 条标注轨迹与 GAIA 验证集 165 题官方评分器均可得。算力门槛低：被调试策略 qwen3.5-9b 可本地部署，诊断用 gemini-2.5-flash 温度 0，DeepDebug 每案约 5 次调用、12.8K token，184 条归因加 73 题重跑在单卡或少量 API 预算内可完成。注意：自家框架需接到适配器或导入器（支持 ReAct/LangGraph/CrewAI/OpenAI Agents SDK/OTel GenAI）；托管模型结果随版本漂移，复现需锁定模型版本；Error Hub 与诊断记忆评测时为空，相关增益暂无公开数字。
论文图表