AgentDebugX：面向LLM智能体的开源故障调试框架

朱昆仑

叶旭炎

韩志光

赵宇辰

李秉轩

张伟嘉

田沐昕

唐祥儒

尤佳轩

姬恒

kunlunz2@illinois.edu

摘要

大语言模型智能体的故障很难调试，因为错误暴露出来的步骤往往不是导致错误的那个步骤。现有的可观测性工具会重放执行轨迹，但在识别根本原因或将诊断转化为恢复措施方面提供的支持很少。我们提出了 AgentDebugX，一个开源调试框架，它将调试组织为“检测、归因、恢复、重跑”的闭环。其核心组件 DeepDebug 通过全局轨迹理解、结构引导调查和交叉质询进行多轮根本原因诊断。在 Who&When 基准上，DeepDebug 在两种测试的开源权重骨干模型上均取得了所评估方法中最高的严格归因准确率，在 qwen3.5-9b 上达到了精确的智能体与步骤级准确率，而最强的单次通过基线仅为 [原文缺失具体数值]。在 GAIA 基准上，DeepDebug 通过单次重跑修复了失败任务，而三个解耦的自我修正基线则分别为 [原文缺失具体数值]，将整体准确率从 [原文缺失具体数值] 提升至 [原文缺失具体数值]。AgentDebugX 通过 Python 库、CLI、Web 控制台和可安装的智能体技能暴露此工作流，并提供了一个可选的 Error Hub，用于共享经过脱敏处理的“故障–诊断–修复”数据包，并将其作为调试记忆复用。28.8%21.7%13734655.8%63.6%

AgentDebugX：面向大语言模型智能体的故障可观测性、归因与恢复的开源工具包

朱昆仑1∗ 叶旭炎1∗ 韩志光1∗ 赵宇辰1 李秉轩1 张伟嘉1 田沐昕2 唐祥儒3 潘璐4 詹姆斯·邹4 尤佳轩1 姬恒1 1伊利诺伊大学厄巴纳-香槟分校 2多伦多大学 3谷歌 4斯坦福大学 kunlunz2@illinois.edu ∗同等贡献。

1 引言

大语言模型（LLM）智能体正越来越多地被部署在需要长程推理、外部工具调用、记忆以及跨组件协调的场景中。它们通过实时 API 处理请求、修改软件代码库、操作图形界面，并通过规划器-执行器及多智能体工作流进行协作（Aghzal et al., 2025; Liu et al., 2025; Li et al., 2025; Yang et al., 2025）。这种灵活性也使得它们的故障难以诊断。然而，随着这些系统能力的增强，其故障的调试难度也大幅提升。¹¹¹ 项目主页：https://www.agentdebugx.com。代码：https://github.com/AgentDebugX/AgentDebugX。软件包：https://pypi.org/project/agentdebugx/（pip install agentdebugx）。演示视频：https://youtu.be/ztni6w0o_l8。该项目以 MIT 许可证发布。

核心难点在于，故障显现出来的步骤往往并非导致故障的步骤。智能体可能因为很早之前遗漏的规划约束、过时的记忆检索、无效的中间假设或智能体之间错误的交接，而返回错误的最终答案。由此产生的症状可能只有在执行了许多看似合理的操作之后才会浮出水面，例如一次失败的工具调用、一个不一致的下游决策，或一个缺乏依据的最终响应。因此，仅仅重放执行轨迹通常是不够的：开发者必须确定是哪个更早的决策导致运行失败，解释其为何具有决定性，并将该诊断转化为可测试的修正方案。

现有工具仅能解决这一挑战的局部问题。通用可观测性平台能提供详细的执行轨迹，但根因分析和修复工作在很大程度上仍留给开发者自行完成。失败分类体系和归因基准将常见错误模式形式化，并评估某种方法能否识别出责任智能体或步骤，但这些通常以独立分析的形式呈现，而非可直接部署的调试基础设施。自我修正方法能够修正失败行为，然而当底层错误的位置已知时，修正的可靠性会显著提高（Tyen 等人，2024）。如表 1 所总结，当前系统因此在观察失败执行、归因其根因、提出可操作的修复方案以及通过重新运行验证修复之间留下了空白。

为填补这一空白，我们推出了 AgentDebugX，一个开源工具包，通过将智能体调试组织为图 1 所示的迭代循环来弥合这一差距：检测（Detect）、归因（Attribute）、恢复（Recover）和重跑（Rerun）。给定实时执行或导出的日志，AgentDebugX 首先将框架特定事件转换为可移植的轨迹表示。检测环节识别可观察的失败，并将其与结构化的失败模式关联起来。归因环节随后将这些症状反向追溯到最有可能通过修正来避免失败的智能体和步骤。恢复环节将所得诊断转化为具体的重试指令，而重跑环节则从适当的检查点应用已批准的修正，同时保留原始分支和修复分支以供对比。当重跑仍然失败时，其新轨迹会重新进入同一循环。

AgentDebugX 的核心是 DeepDebug，这是一个多轮根因诊断智能体，专为无法通过单次轨迹读取可靠定位的故障而设计。DeepDebug 将全局轨迹读取与结构引导式探测相结合——在多智能体运行中追踪交接过程，或在单智能体轨迹中进行二分定位。它会交叉审查相互矛盾的候选结果，并输出一份可审计的报告，其中包含责任智能体及步骤、支持证据、解释以及一项具体修复建议。只有当诊断能够改进下一次执行时，它才具有实际操作性。因此，AgentDebugX 将归因直接连接到策略门控的重跑循环。其原生恢复路径以 DeepDebug 定位精准、有证据支撑的修正作为重试指令，而其他恢复器则可以重新表述同一诊断结果。

除了单个调试会话之外，AgentDebugX 还提供了一个可选的 Error Hub，用于存储经过脱敏处理的轨迹–诊断–修复数据包。这些数据包可作为事件记录、持续集成回归测试夹具以及可复用的调试记忆。通过一种共享的、框架无关的格式，团队可以跨方法和版本比较诊断结果、检索相似的历史故障，并积累经过审核的长尾故障模式示例，而无需修改原始执行证据。

我们评估了 AgentDebugX 的两项能力：准确定位故障原因，以及将该诊断转化为成功修复。在 Who&When 基准上，DeepDebug 在两个受测开源骨干模型上均取得了所评估方法中最强的归因性能。使用 qwen3.5-9b 时，其严格智能体加精确步骤准确率达到 28.8%，而最强的单次通过基线为 21.7%。在 GAIA 上，将 DeepDebug 的诊断应用于单次重跑，可修复底层智能体最初失败的 73 条轨迹中的 13 条，而三个解耦的自我修正基线仅能修复 4–6 条，整体准确率从 55.8% 提升至 63.6%。

2 相关工作

现有研究为观察、诊断或纠正智能体故障提供了强有力的组件，但很少将它们连接成一个从故障检测到验证修复的统一工作流。LangSmith、Langfuse 和 Phoenix 等可观测性平台能够捕获并回放详细的智能体轨迹（Dong 等，2024），但需要开发者自行判断哪一步出了问题、为什么出问题以及如何修复该次运行。另一条研究路线通过分类体系、归因基准和轨迹诊断来形式化智能体故障——包括 AgentDebug（Zhu 等，2025）、MAST（Cemri 等，2026）、Who&When（Zhang 等，2025）、TRAIL（Deshpande 等，2025）和 AgenTracer（Zhang 等，2026）。这些研究表明，即使是强大的模型也难以进行根本原因定位，但它们是以独立的分类体系、基准或归因方法的形式呈现，而非面向异构运行时的可部署基础设施。最接近的系统是 AgentDiagnose（Ou 等，2025），它提供了一个开放工具包，用于沿可解释维度对轨迹进行评分并整理训练数据，但并未将步骤级归因与验证修复或共享事件语料库连接起来。自我修正方法——Reflexion（Shinn 等，2023）、Self-Refine（Madaan 等，2023）、CRITIC（Gou 等，2024）、AutoManual（Chen 等，2024）——研究模型如何修正失败行为，这与我们的场景互补：当错误位置被明确给出时，模型修正错误的可靠性会大幅提升（Tyen 等，2024），而这正是 AgentDebugX 的归因功能所提供的。

3 系统概览

图 1 展示了 AgentDebugX，这是一个由四个阶段组成的闭环调试框架：检测（Detect）、归因（Attribute）、恢复（Recover）和重跑（Rerun）。这些阶段通过一个可移植的调试工件进行协调，而困难案例则升级至 DeepDebug 智能体进行诊断和恢复。

3.1 轨迹捕获与表示

该循环的输入是 AgentTrajectory，即智能体执行过程的可移植记录。运行时层将智能体框架发出的事件——LLM 调用、工具调用及结果、记忆操作、交接、UI 操作——转换为有序的 AgentEvents 序列。每个事件记录执行智能体、模块、步骤索引、父事件、输入、输出、元数据，以及产生的任何错误或工件（包括 GUI 智能体的截图）。轨迹既可通过适配器（LangGraph、CrewAI、OpenAI Agents SDK、OpenTelemetry、原始 ReAct）从实时运行时捕获，也可通过离线导入器从导出的日志中重建；所有机制都产生相同的表示形式，因此诊断与原始框架无关。关键在于，诊断是叠加在该记录之上的，而非写回记录之中：同一执行过程可被任何方法重新分析、跨版本比较，并作为回归案例共享，而不会改变证据本身。

3.2 闭环调试流水线

给定捕获的轨迹后，AgentDebugX 运行图 1 中的四阶段循环。每个阶段都消费前一阶段的结构化输出，并产生可检查的工件。

检测（Detect）。

确定性规则包首先针对可机械验证的失败——格式错误的工具调用、无进展循环、无效输出、过早成功——且不涉及模型调用。当规则不足时，LLM 评判器读取目标和有界轨迹窗口，并返回类型化的发现（受影响事件、失败模式、证据、置信度），这些发现以共享分类体系表达，其种子包含涵盖规划、记忆、工具使用、验证和协调的模式（附录 A）。检测定位失败显现的位置；被检测到的事件不一定是责任事件，因此其发现为归因提供线索，而非定论。19

归因（Attribute）。

归因阶段将症状追溯至导致任务失败的步骤，采用一系列在成本与分辨率之间权衡的策略：先使用廉价启发式方法和单次全轨迹阅读，然后进行二分搜索、逐步检查以及有预算限制的集成方法。每个归因器返回带有置信度和来源的排序假设，而非单一无保留的归责判定，因此部署时可以在准确性与延迟和 token 成本之间进行调节。仍然存在歧义的案例会升级至 DeepDebug（见第 3.3 节）。

恢复。

一旦定位到责任步骤，恢复阶段将发现转化为具体的重试提案，该提案基于根因步骤、失败模式、证据和周围上下文。原生路径使用 DeepDebug 自身的修正作为重试指令，诊断后无需额外模型调用；Reflexion（Shinn 等人，2023）、CRITIC（Gou 等人，2024）和 AutoManual（Chen 等人，2024）作为替代策略和基线提供。所有方案均仅作建议：因为修复后的动作可能改变世界状态，应用始终处于明确的人工或策略门控之后。

重跑。

AgentDebugX 将诊断结果、选定的检查点和重试指令打包为重跑请求；运行时特定的执行器消费该请求以生成新的轨迹，控制台还支持模型生成的延续分支，用于交互式对比。分支根据目标进行评分，并与原始轨迹并列保存，既保留失败也保留尝试修复的记录；成功的分支保存为已解决案例，失败的分支重新进入检测阶段。AgentDebugX 不会从导入的日志中自动重放任意外部工具。

3.3 DeepDebug：多轮根因智能体

单次归因存在互补的盲区：全局阅读保留了任务上下文，但锚定在最响亮的后续症状上；而狭窄的逐步扫描则失去了对目标的把握。DeepDebug（图 1 下半部分）通过对捕获的轨迹进行多轮、只读的过程来解决这一问题，共分四个阶段。

第一阶段——全局阅读。

智能体读取完整轨迹，重建目标和历史，并为关键步骤命名一个初始候选，同时保留必要的上下文，以便区分因果错误与局部异常但有效的动作。

阶段 2——结构引导式调查。

第二轮扫描使用与轨迹形态相匹配的策略：对于多智能体运行，它从可见故障处沿交接链向上游回溯，定位到导致运行失败的最早步骤；对于单智能体运行，它对步骤区间进行二分查找并重新读取存续区域，从而得出一个独立的第二候选。

阶段 3——交叉质询。

如果两轮扫描结论一致，则该步骤被接受；如果结论不一致，DeepDebug 会并排检查两个候选及其上下文、输入、输出和下游影响，并选择因果解释更强的一个——从而将根因选择从对整个轨迹的搜索缩减为对两个假设的聚焦裁决。

阶段 4——诊断与建议。

确定步骤后，DeepDebug 会输出一份结构化报告：责任智能体及步骤、通俗语言解释、引用的证据，以及一条恢复机制可直接使用或重新表述的具体修复建议。每次检查都会被记录，因此结论会附带完整的审计轨迹。智能体只检查轨迹，绝不重新执行运行中的工具。

3.4 可扩展的故障分类体系

检测与诊断共享一套结构化的故障模式词汇表。固定的分类体系无法预见所有长尾错误，因此 AgentDebugX 提出了供人工审核的扩展机制：当裁判遇到种子集合之外反复出现的故障时，它会记录一个新模式候选；归纳器收集此类残余样本，对其进行聚类（先按标签，再按词法或嵌入向量相似度，并以支持度阈值为门槛），为每个聚类提出一个候选模式，并与种子集合去重。提议永远不会覆盖人工整理的分类体系：例如，当多次运行显示智能体无限期地相互等待时，归纳器会提出一个新的多智能体死锁模式，注明它与现有“交接丢失”类别的亲缘关系，并将最终决定留给维护者。

3.5 系统接口与集成

该流水线通过共享相同轨迹、发现、报告和恢复类型的多个界面暴露出来，因此在一个界面中创建的案例可以在另一个界面中继续处理。交互式控制台（图 2）通过 `agentdebug serve` 在库所写入的本地存储上启动；作为随 wheel 包分发的免构建单页应用，它能让开发者从 `pip install` 直接进入实时调试器。典型会话遵循图 2 中编号的四步流程：选择一次失败的运行，从可见的失败处跳转到被归因的责任事件，审阅证据和建议的修复方案，然后派生一条从该步骤重跑的分支，并与原始运行进行评分对比。相同的视图也服务于计算机使用型智能体：OSWorld 导入器会规范化截图与操作步骤，GUI 根因模式在视觉通道上进行推理，而 Python 风格的 traceback 或 JSON 报告则在无需浏览器时服务于 CI。

Error Hub 将事故转化为共享知识。一条轨迹、其报告及相关工件被打包成一个 bundle，其 scrubber 默认会整体剥离事件输入——即承载提示词和工具参数的字段——并对所有剩余字符串应用已知模式的凭据和 PII 脱敏；由于模式脱敏无法保证移除任意敏感内容，共享保持自愿加入（opt-in），且 bundle 在发布前应经过审查。Bundle 可写入本地目录、私有 Git 远程仓库或公共数据集，同时充当 CI 夹具和跨团队语料库中的一个条目。该语料库也是 AgentDebugX 的长期记忆：DeepDebug 可以检索相似的历史案例来为假设提供种子，并将每个新案例写回；通过共享的 bundle 格式，被接受的条目和经审查的分类法新增内容可供未来诊断使用（此效果尚未评估）。最后，DeepDebug 被打包为可安装的智能体技能和 CLI，因此使用工具的智能体（Claude Code、OpenClaw 和 Hermes，各自安装该技能）可以规范化自身失败的运行、进行诊断，并将修复反馈到下一次尝试中——通过这一个 CLI 契约，受支持的主机智能体可以诊断自身运行以及彼此的运行。

4 评估

我们按流水线顺序评估一个已部署的调试器必须完成的两件事：先准确定位原因，再将诊断转化为修复。

设置。

除非另有说明，被调试的策略为 qwen3.5-9b，所有诊断（judge 和 DeepDebug）均在 gemini-2.5-flash 上运行，温度为默认值且禁用思考。诊断记忆和 Error Hub 全程保持为空。每个任务的输出、配置以及重新生成表 3 的脚本随代码一同提供；完整协议见附录 C。0

失败归因。

我们在全部 Who&When 轨迹（Zhang 等人，2025）上进行评估。每条轨迹都标注了谁出错——即负有责任的智能体，其决策导致运行失败——以及何时出错——即确切错误步骤。按照该基准的参考答案协议，每种方法都会获得任务的参考答案，但不会获得两个金标准标签。使用 qwen3.5-9b（表 2）时，DeepDebug 的两遍阅读裁决方法在所有五项报告指标上均优于所评估的单策略定位器——负责任智能体（ vs ）、精确/近似（）步骤（/ vs /）以及严格的智能体与步骤联合（/ vs /）。这一联合增益延续到 qwen3.6-27b（严格 vs ）。该收益依赖于模型：在附录 C 的托管骨干模型上，单次全局阅读已经更强，裁决并未带来改进，这促使我们采用按模型路由而非无条件调用多调用方法。将结构感知阅读替换为第二个全局搜索器会在 gpt-5.4-mini 上损失严格指标点数（消融实验，附录 C）。18456.047.8±128.844.022.338.628.832.121.723.938.036.44.8

多轮智能体发挥价值之处。

图 3 按轨迹长度分解了同一运行结果：优势集中在长度超过事件的轨迹上，这正是结构引导轮次和交叉质询所针对的场景。只有条轨迹落在此范围内，因此我们将其视为描述性证据。4026

GAIA 上的端到端恢复。

定位只有在能够改变结果时才有意义，因此我们闭环验证。一个原生的 qwen3.5-9b Open-Deep-Research 智能体解决了部分 GAIA 验证任务，并在其余任务上失败；我们逐一诊断每次失败并重跑一次。AgentDebugX 的原生路径将 DeepDebug 自身的定位修复直接注入重试流程；Reflexion、CRITIC 和 AutoManual 作为解耦基线运行：使用相同的失败任务上下文，外加一个通用评判器生成的失败摘要，但不包含 DeepDebug 的定位信息、证据或撰写的修复方案。在这一共享子集下，DeepDebug 的恢复机制产生的单次重跑修复数量是解耦基线的两倍以上（表 3），其中在 Level-2 多跳任务上提升最大（）——这证明其基于定位、有证据支撑的修复方案是有效的，尽管该实验评估的是完整方案而非单独隔离归因贡献。55.8%7348.8→61.6

成本感知选择。

每个后端都声明其推理成本（免费规则；All-at-Once 和评判器各一次调用；/ 次搜索；DeepDebug 需 次调用），使部署方能够在模型调用次数与定位精度之间进行权衡。升级策略的实际成本低于调用次数所暗示的水平：在一个按轨迹分层的 Who&When 样本上，一次全轨迹遍历平均消耗 K 个 token，而 DeepDebug 为 K（；其后续轮次只读取聚焦窗口），因此仅对模糊案例进行升级可将预期成本保持在接近单次遍历的水平；每个归因器返回的是带来源依据的排序假设，而非单一的权威责任判定。O​(log⁡N)O​(N)∼5258.112.81.6×

5 使用场景与应用

AgentDebugX 支持多种调试工作流。一个典型的会话始于捕获或导入一次失败的执行过程。随后，DeepDebug 会定位出问题的步骤，解释根本原因，并提出修复方案，该方案可在受策略控制的重新运行之前进行审查。由此产生的执行轨迹会与原始轨迹一同保留，并可选择性地存入 Error Hub，作为可复用的调试记忆。该工作流支持交互式调试、CI 回归测试、事件响应以及自我调试型智能体。

6 结论

在本工作中，我们提出了 AgentDebugX，一个闭环调试框架，它将大语言模型智能体的故障检测、根因归因、恢复和重新运行连接起来。其核心方法 DeepDebug 证明，改进故障归因可以转化为下游恢复中可衡量的收益。我们希望 AgentDebugX 能为调试能力日益强大的大语言模型智能体提供实用基础，并促进关于可靠智能体开发的未来研究。

伦理考量

AgentDebugX 会收集可能敏感的智能体轨迹，包括提示词、工具参数、用户数据、文件、截图和输出。默认部署以本地优先为原则，共享语料库上传为自愿选择。任何生产环境部署都应在收集用户数据之前配置脱敏、留存、访问控制和审计日志。诊断标签和恢复建议可能出错，因此 UI 和 API 应呈现置信度和证据，而非将归因视为绝对事实。对于高影响领域，部署应要求人工或策略审批，而非自动恢复。

更广泛的影响

AgentDebugX 可以帮助将智能体可靠性转变为一种可检查、可度量的工程实践。如今，故障往往被私下修补，随后便被遗忘；而系统化的归因与恢复证据，则可以为审计追踪、部署门禁、回归测试，以及关于何时不应信任某个智能体的决策提供依据。这一点之所以重要，是因为智能体正在进入软件开发、科学、教育、无障碍服务以及面向公众的服务等领域，在这些场景中，静默或反复出现的错误可能会波及单次运行之外的范围。一个开源工具包和统一的轨迹表示形式，也能降低研究人员和中小型组织研究鲁棒性、并在共享证据基础上比较不同系统的成本。

Error Hub 将这种影响从单个部署扩展到整个社区：一个团队的失败可以成为另一个团队的回归用例，并且在规模化之后，还能为更贴近现实的基准测试、不断演进的分类体系，以及更好的诊断或恢复方法做出贡献。AgentDebugX 与 Hub 共同开辟了一条从孤立事件走向组织学习、最终迈向共享鲁棒性标准的路径。要实现这一愿景，需要获得同意、保证来源可溯、进行有效的脱敏处理、内容审核、下架流程，以及对哪些系统和故障仍未被充分代表的审计。有了这些保障措施，AgentDebugX 就能让智能体鲁棒性变得更加具有累积性、协作性和广泛可及性，而不是一种专有的竞争优势。

参考文献

• M. Aghzal, E. Plaku, G. J. Stein, and Z. Yao (2025) A survey on large language models for automated planning. arXiv preprint arXiv:2502.12435. Cited by: §1.
• S. Barke, A. Goyal, A. Khare, A. Singh, S. Nath, and C. Bansal (2026) AgentRx: diagnosing ai agent failures from execution trajectories. External Links: 2602.02475, Link Cited by: Table 1.
• M. Cemri, M. Z. Pan, S. Yang, L. A. Agrawal, B. Chopra, R. Tiwari, K. Keutzer, A. Parameswaran, D. Klein, K. Ramchandran, M. Zaharia, J. E. Gonzalez, and I. Stoica (2026) Why do multi-agent LLM systems fail?. In The Thirty-ninth Annual Conference on Neural Information Processing Systems Datasets and Benchmarks Track, External Links: Link Cited by: Table 1, §2.
• M. Chen、Y. Li、Y. Yang、S. Yu、B. Lin 和 X. He（2024）AutoManual：通过交互式环境学习，让 LLM 智能体构建指令手册。外部链接：2405.16247，链接 引用自：§2、§3.2。
• D. Deshpande、V. Gangal、H. Mehta、J. Krishnan、A. Kannappan 和 R. Qian（2025）TRAIL：轨迹推理与智能体问题定位。外部链接：2505.08638，链接 引用自：§2。
• L. Dong、Q. Lu 和 L. Zhu（2024）AgentOps：实现 LLM 智能体的可观测性。外部链接：2411.05285，链接 引用自：§2。
• Z. Gou、Z. Shao、Y. Gong、yelong shen、Y. Yang、N. Duan 和 W. Chen（2024）CRITIC：大语言模型可通过工具交互式批判实现自我修正。载于第十二届国际学习表征会议，外部链接：链接 引用自：§2、§3.2。
• Langfuse（2023）Langfuse：开源 LLM 工程平台。注：https://github.com/langfuse/langfuse 面向 LLM 应用的开源追踪与可观测性工具 引用自：表 1。
• B. Li、Y. Wang、J. Gu、K. Chang 和 N. Peng（2025）METAL：一种支持测试时扩展的多智能体图表生成框架。载于第 63 届计算语言学协会年会论文集（第 1 卷：长文），W. Che、J. Nabende、E. Shutova 和 M. T. Pilehvar（编），奥地利维也纳，第 30054–30069 页。外部链接：链接、文档、ISBN 979-8-89176-251-0 引用自：§1。
• J. Liu、D. Zhu、Z. Bai、Y. He、H. Liao、H. Que、Z. Wang、C. Zhang、G. Zhang、J. Zhang 等（2025）长上下文语言建模综合综述。arXiv 预印本 arXiv:2503.17407。引用自：§1。
• A. Madaan、N. Tandon、P. Gupta、S. Hallinan、L. Gao、S. Wiegreffe、U. Alon、N. Dziri、S. Prabhumoye、Y. Yang、S. Gupta、B. P. Majumder、K. Hermann、S. Welleck、A. Yazdanbakhsh 和 P. Clark（2023）Self-refine：基于自我反馈的迭代精炼。载于第三十七届神经信息处理系统会议，外部链接：链接 引用自：§2。
• G. Mialon、C. Fourrier、T. Wolf、Y. LeCun 和 T. Scialom（2024）GAIA：通用 AI 助手的基准测试。载于第十二届国际学习表征会议，外部链接：链接 引用自：附录 C。
• OpenTelemetry（2026）OpenTelemetry 生成式 AI 语义约定。注：https://github.com/open-telemetry/semantic-conventions-genai 访问于 2026-07-09 引用自：附录 B。
• T. Ou、W. Guo、A. Gandhi、G. Neubig 和 X. Yue（2025）AgentDiagnose：用于诊断 LLM 智能体轨迹的开放工具包。载于《2025 年自然语言处理经验方法会议论文集：系统演示》，I. Habernal、P. Schulam 和 J. Tiedemann（编），中国苏州，第 207–215 页。外部链接：Link、Document，ISBN 979-8-89176-334-0 引用自：表 1、§2。
• N. Shinn、F. Cassano、A. Gopinath、K. R. Narasimhan 和 S. Yao（2023）Reflexion：具有言语强化学习的语言智能体。载于《第三十七届神经信息处理系统会议》，外部链接：Link 引用自：§2、§3.2。
• G. Tyen、H. Mansoor、V. Carbune、P. Chen 和 T. Mak（2024）LLM 无法发现推理错误，但在给定错误位置后可以纠正它们。载于《计算语言学协会发现：ACL 2024》，L. Ku、A. Martins 和 V. Srikumar（编），泰国曼谷，第 13894–13908 页。外部链接：Link、Document 引用自：§1、§2。
• J. Yang、X. Liu、W. Lv、K. Deng、S. Guo、L. Jing、Y. Li、S. Liu、X. Luo、Y. Luo 等（2025）从代码基础模型到智能体与应用：代码智能的综合综述与实践指南。arXiv 预印本 arXiv:2511.18538。引用自：§1。
• G. Zhang、J. Wang、J. Chen、W. Zhou、K. Wang 和 S. YAN（2026）AgenTracer：谁在导致 LLM 智能体系统失败？载于《第十四届国际学习表征会议》，外部链接：Link 引用自：§2。
• S. Zhang、M. Yin、J. Zhang、J. Liu、Z. Han、J. Zhang、B. Li、C. Wang、H. Wang、Y. Chen 和 Q. Wu（2025）哪个智能体导致任务失败以及何时导致？关于 LLM 多智能体系统的自动化失败归因。载于《第四十二届国际机器学习会议》，外部链接：Link 引用自：附录 C、表 1、§2、§4。
• K. Zhu, Z. Liu, B. Li, M. Tian, Y. Yang, J. Zhang, P. Han, Q. Xie, F. Cui, W. Zhang, X. Ma, X. Yu, G. Ramesh, J. Wu, Z. Liu, P. Lu, J. Zou, 和 J. You（2025）《大语言模型智能体在哪里失败，以及它们如何从失败中学习》。外部链接：2509.25370，链接 引用：表 1，§2。

附录 A 系统与提示词细节

轨迹模式。

每次运行都是一个 AgentTrajectory，由 AgentEvents（类型、智能体、模块、步骤索引、父节点、时间戳、输入/输出、错误、持续时间、元数据、工件）组成。工件可以包含文本、图像、音频、UI 状态、文件或环境快照，并且相同的事件会映射到 OpenTelemetry GenAI 跨度（invoke_agent、chat、execute_tool、handoff）。诊断层由紧凑的、受 JSON 约束的提示词驱动；我们在下面复现了其中最关键的部分（完整提示词库随仓库发布），随后附上 GAIA 实验期间生成的一份完整诊断报告。

示例诊断报告。

下面这份节选报告是 DeepDebug 在 GAIA 验证任务上的实际输出，该任务中普通智能体失败了（一个关于 1,002 篇论文、平均 -值 的统计问题）；该智能体曾假设 -值均匀分布来估算错误论文的数量。这份诊断被原样作为重试指令输入，引导重新运行得出了正确答案（），这是表 3 中的恢复案例之一。p0.04p4113/73

附录 B 部署要求

该设计遵循生产环境智能体运维的五项要求：低摩擦捕获（上下文管理器、回调或导入器）；具有 OpenTelemetry GenAI 导出路径的可移植表示（OpenTelemetry，2026）；类型化诊断（根因、证据、置信度、修复方案）；本地优先存储，在共享前明确清理；以及成本感知分析，其中确定性分类是免费的，LLM 深度分析为可选启用。

附录 C 评估协议

基准测试。

Who&When（Zhang 等人，2025）被完整使用（：算法生成的、手工制作的），每条轨迹都标注了黄金责任智能体和错误步骤。GAIA（Mialon 等人，2024）验证集（三个难度级别的 个任务）用于端到端恢复评估，由官方问题评分器评分。n=18412658165

归因协议。

遵循 Who&When “带真实答案”的设置，每种方法都会获得任务的参考答案作为上下文；没有任何方法能看到金牌智能体或步骤。解码在模型侧思考关闭的情况下以温度参数进行；补全被限制在 token 数以内（用于仲裁）。智能体名称在比较前会进行归一化处理，步骤匹配则采用精确索引相等。我们报告了责任智能体准确率、精确匹配与步骤定位准确率，以及智能体与步骤联合（A+S）指标。骨干模型涵盖开放权重（qwen3.5-9b、qwen3.6-27b）和托管（gpt-5.4-mini、gemini-3.5-flash）模型，全部通过兼容 OpenAI 的端点提供服务。04,096512±1

GAIA 恢复协议。

一个普通的 Open-Deep-Research 智能体（qwen3.5-9b 策略，Gemini-2.5-flash 搜索）在全部验证任务上运行一次，产生一个包含 -task 失败子集。每个失败轨迹被转换为 AgentTrajectory，由 LLM 评判器诊断，对于原生路径则由 DeepDebug 诊断。随后恢复过程仅对失败任务重新运行一次，采用四种策略之一：AgentDebugX 的原生 DeepDebug 指令，或解耦的 Reflexion / CRITIC / AutoManual 基线（它们看到的是通用评判器摘要，而非 DeepDebug 的局部化诊断）。为保持对比的纯净性，评估期间诊断记忆和 Error Hub 均为空；两者在实际部署中均为可选启用。重新运行使用温度参数、固定的步骤预算，以及与基线相同的搜索和工具栈。“Rec.”统计在 上修复的任务数；“All”将修正后的任务投影到完整 上。1657373073165

定位器设计消融。

DeepDebug 的回合设计是通过在分层 -trace Who&When 样本上的测量来确定的：将结构引导回合替换为第二次全局搜索，会使 gpt-5.4-mini 上的严格准确率从 降至 ，而实际采用的配对组合将智能体准确率提升至 ，对比单次读取的 ；在 gemini-3.5-flash 上，单次读取已经是最强的——仲裁在评估的开放权重骨干上有效，但在托管骨干上无效——这是一个依赖模型的效应。420.3100.2620.5240.429

附录 D 实现

AgentDebugX 是一个依赖极少、采用 MIT 许可的 Python 包：通过 `pip install agentdebugx` 安装，以 `agentdebug` 方式导入。其公共 API 以 AgentDebug、TraceSession、AgentTrajectory、FailureFinding 和 DiagnosticReport 为核心；使用方式仅需一个上下文管理器：

from agentdebug import AgentDebug, EventType
dbg = AgentDebug()
with dbg.trace(goal="Book flight",
               framework="my-agent") as t:
    t.record(EventType.PLAN, agent_name=
      "planner", output="Search fares")
    t.record(EventType.TOOL_RESULT,
      agent_name="browser", step_index=3,
      error="Checkout timeout")
    report = t.analyze()

轨迹数据持久化到追加式 JSONL 或 SQLite 中。三种采集面输出相同的模式：运行时适配器（原始 ReAct、LangChain/LangGraph、CrewAI、OpenAI Agents SDK、OpenTelemetry GenAI）、离线导入器（消息列表、对话、事件列表、WebShop 页面、OpenAI Agents spans、CrewAI 事件、OpenClaw 会话），以及宿主集成（一个 Claude Code 技能和一个面向工具型智能体的 CLI 技能契约），因此检测、归因和恢复均与数据源无关。CLI 将工作流呈现为 ingest / diagnose / inspect / act 四个阶段，并通过 serve 提供控制台功能。

附录 E 局限性

我们的评估涵盖自动归因和恢复，但不涉及开发者调试时间或控制台可用性。Who&When 采用基准测试的参考答案协议，而 DeepDebug 的收益因模型而异，因此其额外调用并非对所有情况都有益。GAIA 实验在固定的失败子集上评估单一策略模型，并比较完整的重试方案；它既未单独隔离归因的效果，也不是盲测的单次得分。Error Hub 检索和分类体系归纳已实现但尚未评估，且归纳过程需要人工验收。清洗器会剥离事件输入并脱敏已知的凭据/PII 模式，但不会处理任意内容；恢复执行仍以人工批准为前提。