# AgentDebugX：面向LLM智能体的开源故障调试框架 - 来源：HuggingFace Daily Papers（社区热门论文） - 发布时间：2026-07-21 08:00 - AIHOT 分数：71 - AIHOT 标记：精选 - AIHOT 链接：https://aihot.virxact.com/items/cmrvnxfx7047nbihbzr6crygg - 原文链接：https://arxiv.org/abs/2607.18754 ## 精选理由 这个框架把调试从单步检测变成归因-恢复的闭环，DeepDebug的多轮诊断在GAIA上修好了13个失败案例，我觉得做agent开发的都可以装一个试试。 ## AI 摘要 AgentDebugX是一个开源调试框架，将LLM智能体调试组织为“检测-归因-恢复-重跑”闭环。其核心DeepDebug在Who&When基准上对qwen3.5-9b达到精确的智能体与步骤归因准确率，在GAIA上单次重跑即可修复失败任务。该工具提供Python库、CLI、Web控制台和可安装的智能体技能。 ## 正文 昆仑朱 叶旭彦 韩志光 赵宇晨 李炳轩 张伟嘉 田沐昕 汤祥如 游嘉轩 季衡 kunlunz2@illinois.edu 摘要 大语言模型智能体的故障很难调试，因为错误暴露的步骤往往不是导致错误的根源。现有的可观测性工具会重放执行轨迹，但在识别根本原因或将诊断转化为恢复方面提供的支持很少。我们提出 AgentDebugX，一个开源调试框架，将调试组织为检测、归因、恢复和重跑的闭环。其核心 DeepDebug 通过全局轨迹理解、结构引导调查和交叉审查执行多轮根本原因诊断。在 Who&Bench 基准上，DeepDebug 在两个测试的开源骨干模型上均取得了评估方法中最佳的严格归因准确率，在 qwen3.5-9b 上达到了精确的智能体和步骤准确率，而最强的单次基线则未能达到。在 GAIA 上，DeepDebug 在单次重跑中修复了失败任务，而三个解耦的自我修正基线则分别为 –，将整体准确率从 提升至 。AgentDebugX 通过 Python 库、CLI、Web 控制台和可安装的智能体技能暴露此工作流，并提供一个可选的错误中心，用于共享经过清理的故障-诊断-修复包，并将其作为调试记忆重用。 AgentDebugX：面向大语言模型智能体的故障可观测性、归因与恢复的开源工具包 昆仑朱1∗ 叶旭彦1∗ 韩志光1∗ 赵宇晨1 李炳轩1 张伟嘉1 田沐昕2 汤祥如3 潘璐4 詹姆斯·邹4 游嘉轩1 季衡1 1伊利诺伊大学厄巴纳-香槟分校 2多伦多大学 3谷歌 4斯坦福大学 kunlunz2@illinois.edu ∗同等贡献。 媒体内容 · 前往原文查看 端口 分类 归因 恢复 错误 系统 模式 命名法 贡献 恢复 中心 AgentDebug (Zhu 等人, 2025) – – MAST (Cemri 等人, 2026) – – – Who&When (Zhang 等人, 2025) – – – AgentDiagnose (Ou 等人, 2025) – – AgentRx (Barke 等人, 2026) – – Langfuse (Langfuse, 2023) – – – – AgentDebugX (本文) 表1：能力覆盖范围与先前工作的对比。= 一流支持，= 部分支持，– 不支持。可移植模式（Port. schema）：一种可移植、与框架无关的追踪格式，支持重新分析、比较和共享（非厂商专有跨度格式）。分类体系（Taxonomy）：一套带标签的故障模式词汇表。归因（Attribution）：定位到具体出错的步骤/智能体，而不仅仅是崩溃点。恢复（Recovery）：将诊断结果转化为可重新运行的修复方案。错误中心（Error hub）：一个可共享的跨团队诊断故障语料库。 1 引言 大语言模型（LLM）智能体正越来越多地部署在需要长程推理、外部工具调用、记忆以及跨组件协调的场景中。它们通过实时 API 处理请求、修改软件仓库、操作图形界面，并通过规划器-执行器及多智能体工作流进行协作（Aghzal 等人，2025；Liu 等人，2025；Li 等人，2025；Yang 等人，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 所示的迭代循环（检测、归因、恢复、重新运行）来弥合上述断层。给定实时执行或导出的日志后，AgentDebugX 首先将框架特定事件转换为可移植的轨迹表示。检测环节识别可观测的失败，并将其与结构化故障模式关联。归因环节随后将这些症状反向追溯至最可能通过修正来避免失败的智能体与步骤。恢复环节将诊断结果转化为具体的重试指令，重新运行环节则从合适的检查点应用已批准的修正，同时保留原始分支与修复分支以供对比。若重新运行仍不成功，其新轨迹将重新进入同一循环。 AgentDebugX 的核心是 DeepDebug，这是一个专为无法通过单次轨迹读取可靠定位的故障而设计的多轮根因诊断智能体。DeepDebug 将全局轨迹读取与结构引导探查相结合——在多智能体运行中追踪交接过程，或在单智能体轨迹中进行二分查找。它会交叉比对相互矛盾的候选结果，并输出一份可审计的报告，其中包含责任智能体及步骤、支持性证据、解释说明以及一项具体修复方案。只有当诊断能够改进下一次执行时，它才具有操作上的实用性。因此，AgentDebugX 将归因直接连接到一个策略门控的重运行循环。其原生恢复路径使用 DeepDebug 基于局部证据的修正作为重试指令，而其他恢复器则可以对同一诊断结果进行重新表述。 除了单个调试会话之外，AgentDebugX 还提供了一个可选的错误中心，用于存储经过脱敏处理的轨迹-诊断-修复数据包。这些数据包可作为事件记录、持续集成回归测试用例以及可复用的调试记忆。通过一种共享的、与框架无关的格式，团队可以跨方法和版本比较诊断结果，检索相似的历史故障，并积累经过审查的长尾故障模式案例，而无需修改原始的执行证据。 我们评估了 AgentDebugX 的两项能力：准确定位故障原因，以及将该诊断转化为成功的修复。在 Who&When 基准测试上，DeepDebug 在两种测试的开源骨干模型上均取得了评估方法中最强的归因性能。使用 qwen3.5-9b 时，其严格智能体及精确步骤准确率达到 28.8%，而最强的单次基线方法为 21.7%。在 GAIA 上，将 DeepDebug 的诊断应用于单次重运行，可修复底层智能体最初失败的 73 条轨迹中的 13 条，而三种解耦的自我修正基线方法仅能修复 4 到 6 条，从而将整体准确率从 55.8% 提升至 63.6%。 图 1：AgentDebugX 概览。AgentDebugX 形成了一个闭环调试流程：检测（Detect）识别步骤级错误，归因（Attribute）定位其根本原因，修复（Recover）提出排序后的修复方案，重跑（Rerun）在故障点周围重新生成轨迹。困难案例会升级至 DeepDebug——一个多轮诊断智能体，它能生成一份可审计的根本原因报告，附带证据和推荐的修复方案。AgentDebugX 支持本地和 Web 用户界面、可复用的错误共享、基线评估，以及广泛的智能体框架兼容性。 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，即智能体执行过程的可移植记录。运行时层将智能体框架产生的事件——包括大语言模型调用、工具调用及其结果、记忆操作、任务移交、用户界面操作——转换为有序的AgentEvent序列。每个事件记录执行该操作的智能体、模块、步骤索引、父事件、输入、输出、元数据，以及产生的任何错误或工件（包括图形用户界面智能体的截图）。轨迹可以通过适配器（LangGraph、CrewAI、OpenAI Agents SDK、OpenTelemetry、原始ReAct）从实时运行中捕获，也可以通过离线导入器从导出的日志中重建；所有机制都产生相同的表示形式，因此诊断过程与原始框架无关。关键在于，诊断是叠加在此记录之上，而非写回记录之中：同一执行过程可以被任何方法重新分析，跨版本进行比较，并作为回归测试案例共享，而不会改变原始证据。 3.2 闭环调试流水线 给定一个捕获到的轨迹，AgentDebugX运行图1所示的四阶段循环。每个阶段都消耗前一阶段的结构化输出，并产生可供检查的工件。 检测。 确定性规则包首先针对可机械验证的故障——格式错误的工具调用、无进展循环、无效输出、过早的成功——进行处理，此过程无需模型调用。当规则不足时，由一个大语言模型评判器读取目标和一段有限的轨迹窗口，并返回类型化的发现结果（受影响的事件、故障模式、证据、置信度），这些结果使用一个共享分类体系来表达，该分类体系的种子包含了涵盖规划、记忆、工具使用、验证和协调等模式的故障模式（附录A）。检测环节定位故障表现的位置；被检测到的事件不一定是责任事件，因此其发现结果用于引导归因，而非定论。 Attribute. 归因阶段将症状追溯至导致任务失败的步骤，采用一系列在成本与解析度之间权衡的策略：低成本启发式方法、单次全轨迹读取，然后是二分搜索、逐步骤检查以及预算受限的集成方法。每个归因器返回带有置信度和来源的排序假设，而非一个未经限定的责任归属，因此部署时可根据准确性与延迟和 token 成本进行调节。仍存在歧义的案例将升级至 DeepDebug（第 3.3 节）。 恢复。 一旦定位到责任步骤，恢复阶段会将发现转化为具体的重试方案，该方案基于根本原因步骤、失败模式、证据及周围上下文。原生路径使用 DeepDebug 自身的修正作为重试指令，在诊断后无需额外的模型调用；Reflexion（Shinn 等人，2023）、CRITIC（Gou 等人，2024）和 AutoManual（Chen 等人，2024）作为替代策略和基线提供。所有方案仅为建议性质：由于修复后的操作可能改变世界状态，其应用始终位于明确的人工或策略门控之后。 重运行。 AgentDebugX 将诊断结果、选定的检查点以及重试指令打包成一个重运行请求；特定运行时的执行器消费该请求以生成新的轨迹，控制台还支持模型生成的延续分支用于交互式比较。该分支根据目标进行评分，并与原始轨迹并列保存，同时保留失败和尝试修复的记录；成功的分支将保存为已解决案例，失败的分支则重新进入检测流程。AgentDebugX 不会自动重放从导入日志中获取的任意外部工具。 3.3 DeepDebug：多轮根本原因智能体 单次归因存在互补的盲点：全局读取保留了任务上下文，但锚定在最突出的下游症状上；而狭窄的逐步骤扫描则失去了对目标的把握。DeepDebug（图 1 下方面板）通过在捕获的轨迹上执行多轮、只读的过程来解决此问题，该过程分为四个阶段。 阶段 1——全局读取。 智能体读取整个轨迹，重构目标与历史，并命名一个初始候选步骤作为关键决策点，同时保留必要的上下文，以区分因果错误与局部异常但有效的动作。 第二阶段——结构引导式调查。 第二轮分析采用与轨迹形态相匹配的策略：对于多智能体运行，它沿着交接链从可见故障向上游追溯，直至导致运行失败的初始步骤；对于单智能体运行，它二分步骤区间并重新读取幸存区域，从而得出独立的第二候选步骤。 第三阶段——交叉验证。 如果两轮分析结果一致，则接受该步骤；如果结果不一致，DeepDebug 会并排检查两个候选步骤及其上下文、输入、输出和下游影响，并选择因果解释更强的一方——从而将根因选择从对整个轨迹的搜索缩小为对两个假设的聚焦裁决。 第四阶段——诊断与建议。 确定步骤后，DeepDebug 会生成一份结构化报告：包含责任智能体与步骤、通俗语言解释、引用证据，以及一个恢复机制可直接使用或重新表述的具体修复方案。每次检查均有记录，因此结论附带完整的审计追踪。智能体仅检查轨迹，但绝不重新执行运行中的工具。 3.4 可扩展的故障分类体系 检测与诊断共享一套结构化的故障模式词汇表。固定的分类体系无法预见所有长尾错误，因此 AgentDebugX 提出了供人工审核的扩展机制：当裁判遇到种子集之外的重复性故障时，会记录一个新型模式候选；归纳器收集此类残留项，通过聚类（先标注，再基于词汇或嵌入向量相似度，以支持度阈值为门控）为每个聚类提出一个候选模式，并与种子集去重。提议从不覆盖人工策划的分类体系：例如，当多次运行显示智能体相互无限等待时，归纳器会提出一个新的多智能体死锁模式，注明其与现有交接丢失类别的关联，并将决策权留给维护者。 3.5 系统界面与集成 图 2：AgentDebugX 控制台在一次失败运行中的界面，展示了一个四步工作流：(1) 在运行导航器中选择一条存储的追踪记录；(2) 从可见的失败点跳转到被归因的责任事件；(3) 在诊断面板中读取失败模式、证据和建议的修复方案；(4) 创建一个策略门控的重运行分支，并与原始时间线进行对比。除非显式导出为包，否则所有工件都保留在本地存储中。 该流水线通过共享相同轨迹、发现、报告和恢复类型的界面暴露出来，因此在一个界面中创建的案例可以在另一个界面中继续处理。交互式控制台（图 2）通过 `agentdebug serve` 命令启动，基于该库写入的本地存储运行；作为一个打包在 wheel 文件中的免构建单页应用，它能让开发者从 `pip install` 直接进入实时调试器。典型的会话遵循图 2 中编号的四个步骤：选择一次失败的运行，从可见的失败点跳转到被归因的责任事件，审查证据和建议的修复方案，然后分叉出一个从该步骤开始重运行的分支，并与原始运行进行评分对比。同样的视图也服务于计算机使用型智能体：OSWorld 导入器将截图和操作步骤标准化，GUI 根因模式通过视觉通道进行推理，而 Python 风格的堆栈追踪或 JSON 报告则在无需浏览器时服务于 CI 流程。 Error Hub 将事件转化为共享知识。一条轨迹、其报告及相关产物被打包成一个数据包，其清理器默认会整体剥离事件输入——即携带提示词和工具参数的字段——并对所有剩余字符串应用已知模式的凭证和 PII 脱敏处理；由于模式脱敏无法保证移除任意敏感内容，共享仍为自愿选择，且数据包在发布前应经过审查。数据包可写入本地目录、私有 Git 远程仓库或公开数据集，同时充当 CI 测试夹具和跨团队语料库中的条目。该语料库也是 AgentDebugX 的长期记忆：DeepDebug 可检索相似历史案例来生成其假设，并将每个新案例写回；通过共享的数据包格式，已接受的条目和经审查的分类补充将可供未来诊断使用（此效果尚未评估）。最后，DeepDebug 被打包成一个可安装的智能体技能和 CLI，因此使用工具的智能体（Claude Code、OpenClaw 和 Hermes，各自安装该技能）可以规范化其自身的失败运行、进行诊断，并将修复方案反馈到下一次尝试中——这是一个统一的 CLI 接口，受支持的主机智能体可通过它诊断自身运行及彼此的运行。 4 评估 我们按流水线顺序评估一个已部署的调试器必须完成的两件事：准确定位原因，然后将该诊断转化为修复方案。 设置。 除非另有说明，被调试的策略为 qwen3.5-9b，所有诊断（评判模型和 DeepDebug）均在 gemini-2.5-flash 上运行，温度为默认值且禁用思考功能。诊断记忆和 Error Hub 始终保持为空。每个任务的输出、配置以及用于重新生成表 3 的脚本随代码一同提供；完整协议见附录 C。 故障归因。 我们在所有 Who&When 轨迹（Zhang 等人，2025）上进行评估。每条轨迹都标注了谁犯了错——即负有责任的智能体，其决策导致了运行失败——以及何时犯错——即确切的错误步骤。按照该基准的参考答案协议，每个方法都会收到任务的参考答案，但不会收到任何黄金标签。使用 qwen3.5-9b（表 2）时，DeepDebug 的双轮阅读裁决方法在所有五项报告指标上均优于评估的单一策略定位器——即负责智能体（ vs ）、精确/近似（）步骤（/ vs /）以及严格的智能体与步骤联合指标（/ vs /）。这种联合增益在 qwen3.6-27b 上得以延续（严格 vs ）。该收益依赖于模型：在附录 C 的托管骨干模型上，单次全局阅读已经更强，裁决并未带来改进，这促使我们采用按模型路由的策略，而非无条件调用多次调用方法。将结构感知阅读替换为第二个全局搜索器，在 gpt-5.4-mini 上损失了严格指标点数（消融实验，附录 C）。 多轮智能体发挥价值之处。 图 3 按轨迹长度对同一运行结果进行了分解：优势集中在长度超过事件的轨迹上，这正是结构引导轮次与交叉审查所针对的场景。只有 条轨迹落在此范围内，因此我们将其视为描述性证据。 图 3：按轨迹长度划分的 Who&When 准确率（；qwen3.5-9b）。左图：负责智能体准确率（who）。右图：要求同时正确识别负责智能体与确切错误步骤的严格联合准确率（who+when）。 媒体内容 · 前往原文查看 方法 智能体 步骤 步骤 智能体+步骤 智能体+步骤 （精确） （） （精确） （） 规则启发式 14.1 1.6 6.5 1.6 2.7 一次性 47.8 22.3 35.3 21.7 23.9 逐步 41.8 18.5 38.0 17.9 19.6 二分搜索 41.8 17.4 38.6 17.4 20.1 DeepDebug 56.0 28.8 44.0 28.8 32.1 表 2：在完整 Who&When 基准上的失败归因（；qwen3.5-9b）。“智能体”衡量负责智能体的准确率（who）；“步骤”衡量在精确和 标准下的错误步骤定位（when）；“智能体+步骤”要求智能体和步骤均正确。 在 GAIA 上的端到端恢复。 定位只有在改变结果时才有用，因此我们形成了闭环。一个普通的 qwen3.5-9b Open-Deep-Research 智能体解决了 GAIA 验证集的部分任务，并在其他任务上失败；我们诊断每次失败并重新运行一次。AgentDebugX 的原生路径将 DeepDebug 自身的定位修复直接注入重试流程；Reflexion、CRITIC 和 AutoManual 作为解耦基线运行：使用相同的失败任务上下文，加上通用评判器生成的失败摘要，但不包含 DeepDebug 的定位、证据或编写的修复。在此共享子集下，DeepDebug 的恢复机制在一次重试中产生的修复数量是解耦基线的两倍以上（表 3），在 Level-2 多跳任务上提升最大（）——这证明了其基于定位、有证据支持的修复是有效的，尽管该实验评估的是完整方案而非单独归因。 媒体内容 · 前往原文查看 方法 恢复数 L1 L2 L3 全部 普通 qwen3.5-9b — 77.4 48.8 34.6 55.8 + CRITIC 4/73 81.1 51.2 34.6 58.2 + AutoManual 5/73 79.2 53.5 34.6 58.8 + Reflexion 6/73 77.4 55.8 34.6 59.4 + DeepDebug（我们的方法） 13/73 81.1 61.6 34.6 63.6 表 3：GAIA 验证集上的端到端恢复结果（共 个任务；官方评分器）。“恢复数”表示在普通模型失败轨迹中得到修复的案例数量。准确率（%）按难度级别和单次重试后的总体情况报告。 成本感知选择。 每个后端声明其推理成本（免费规则；All-at-Once 和评判器各一次调用； 次搜索；DeepDebug 需 次调用），使部署能够根据模型调用次数来权衡定位精度。升级机制的实际成本低于调用次数所暗示的水平：在一个基于 条轨迹分层的 Who&When 样本上，一次完整轨迹遍历平均消耗 K 个 token，而 DeepDebug 消耗 K 个 token（；其后续轮次读取聚焦窗口），因此仅对模糊案例进行升级可使预期成本接近单次遍历；每个归因器返回的是带有来源的排序假设，而非单一的权威责任判定。 5 用例与应用 AgentDebugX 支持一系列调试工作流程。一个典型的会话从捕获或导入一次失败的执行开始。随后，DeepDebug 会定位出问题的步骤，解释根本原因，并提出修复方案，该方案可在策略控制的重新运行前进行审查。由此产生的执行轨迹会与原始轨迹一同保留，并可选择性地存储在错误中心中，作为可复用的调试记忆。此工作流程支持交互式调试、CI 回归测试、事件响应以及自我调试型智能体。 6 结论 在本文中，我们提出了 AgentDebugX，一个连接了大语言模型智能体的故障检测、根因归因、恢复与重新运行的闭环调试框架。其核心方法 DeepDebug 表明，改进故障归因能够转化为下游恢复中可衡量的收益。我们希望 AgentDebugX 能为调试能力日益增强的大语言模型智能体提供一个实用的基础，并促进未来关于可靠智能体开发的研究。 伦理考量 AgentDebugX 会收集可能包含敏感信息的智能体轨迹，包括提示词、工具参数、用户数据、文件、截图和输出。默认部署方式为本地优先，共享语料库的上传是用户主动选择的。任何生产环境部署在收集用户数据之前，都应配置好脱敏、保留策略、访问控制和审计日志。诊断标签和恢复建议可能出错，因此用户界面和 API 应呈现置信度和证据，而非将归因结果视为绝对事实。对于高影响领域，部署应要求人工或策略批准，而非自动恢复。 更广泛的影响 AgentDebugX 能够帮助将智能体可靠性转变为一项可检查、可度量的工程实践。目前，故障往往被私下修补后便遭遗忘；而系统化的归因与恢复证据，则可以为审计追踪、部署门禁、回归测试，以及判断智能体何时不应被信任等决策提供依据。这一点至关重要，因为智能体正进入软件开发、科学、教育、无障碍服务以及面向公众的服务领域，在这些场景中，静默或重复出现的错误可能会在单次运行之外持续扩散。一个开源工具包和通用的追踪表示形式，也能降低研究人员和小型组织研究鲁棒性、并基于共享证据比较不同系统的成本。 错误中心（Error Hub）将这种影响从单个部署扩展到了整个社区：一个团队的失败可以成为另一个团队的回归测试用例，并在规模化后，有助于构建更真实的基准测试、不断演进的分类体系，以及更优的诊断或恢复方法。AgentDebugX 与错误中心共同开辟了一条从孤立事件走向组织学习，并最终迈向共享鲁棒性标准的路径。实现这一愿景需要获得同意、确保来源可追溯、进行有效的脱敏处理、建立审核与下架流程，并对哪些系统及故障在记录中代表性不足进行审计。有了这些保障措施，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. 被 §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 被 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 被 Table 1, §2 引用。 M. Chen, Y. Li, Y. Yang, S. Yu, B. Lin 和 X. He (2024)《AutoManual：通过交互式环境学习由大语言模型智能体构建操作手册》。外部链接：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：实现大语言模型智能体的可观测性》。外部链接：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：开源大语言模型工程平台》。注释：https://github.com/langfuse/langfuse 面向大语言模型应用的开源追踪与可观测性工具。引用自：表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：通用人工智能助手的基准测试》。载于第十二届国际学习表征会议，外部链接：链接。引用自：附录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 页。外部链接：链接，DOI，ISBN 979-8-89176-334-0 引用自：表 1，§2。 N. Shinn、F. Cassano、A. Gopinath、K. R. Narasimhan 和 S. Yao（2023）《Reflexion：具有语言强化学习的语言智能体》。载于《第三十七届神经信息处理系统会议》。外部链接：链接 引用自：§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 页。外部链接：链接，DOI 引用自：§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 智能体系统失败？》。载于《第十四届国际学习表征会议》。外部链接：链接 引用自：§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 多智能体系统自动故障归因的研究》。载于《第四十二届国际机器学习会议》。外部链接：链接 引用自：附录 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 系统与提示词详情 追踪模式。 每次运行都是一个由AgentEvent（类型、智能体、模块、步骤索引、父级、时间戳、输入/输出、错误、持续时间、元数据、工件）组成的AgentTrajectory。工件可以包含文本、图像、音频、UI状态、文件或环境快照，并且相同的事件会映射到OpenTelemetry GenAI跨度（invoke_agent、chat、execute_tool、handoff）。诊断层由紧凑的、受JSON约束的提示词驱动；我们在下方复现了其中承载量最大的几个（完整的提示词库随仓库一起提供），随后是在GAIA实验期间生成的一份完整诊断报告。 诊断报告示例。 下方这份节略的报告是DeepDebug在GAIA验证任务上的实际输出，该任务中普通智能体失败了（这是一个关于1002篇论文的统计问题，涉及平均值）；该智能体曾假设值是均匀分布的，以此来估算错误论文的数量。将此诊断报告逐字作为重试指令输入后，重新运行得到了正确答案（），这是表3中恢复成功的案例之一。 附录B 部署要求 该设计遵循了生产级智能体运维的五项要求：低摩擦捕获（通过上下文管理器、回调或导入器）；具有OpenTelemetry GenAI导出路径的可移植表示（OpenTelemetry，2026）；类型化诊断（根本原因、证据、置信度、修复）；本地优先存储，在共享前进行明确的脱敏处理；以及成本感知分析，其中确定性分类是免费的，而LLM深度分析则为可选加入。 附录C 评估协议 基准测试。 Who&When（Zhang等人，2025）被完整使用（：算法生成、手工制作），每个追踪都标注了金牌责任智能体和错误步骤。GAIA（Mialon等人，2024）验证（涵盖三个难度级别的任务）用于端到端恢复，由官方问题评分器进行评分。 归因协议。 在 Who&When“带真实标注”设定下，每种方法都会获得任务的参考答案作为上下文；没有任何方法能看到真实智能体或步骤。解码时关闭模型侧思考，温度参数设为固定值；补全内容以 token 数（用于仲裁）为上限。智能体名称在比较前会进行归一化处理，步骤匹配采用精确索引相等。我们报告了责任智能体准确率、精确步骤定位准确率、步骤定位准确率，以及智能体与步骤联合（A+S）指标。基础模型涵盖开源权重（qwen3.5-9b、qwen3.6-27b）和托管服务（gpt-5.4-mini、gemini-3.5-flash）两类，均通过兼容 OpenAI 的接口提供服务。 GAIA 恢复协议。 一个标准的 Open-Deep-Research 智能体（qwen3.5-9b 策略，Gemini-2.5-flash 搜索）在所有验证任务上运行一次，产生一个包含若干任务失败的子集。每个失败的轨迹被转换为 AgentTrajectory，由 LLM 评判器进行诊断，对于原生路径则使用 DeepDebug。随后，恢复过程仅对失败任务重新运行一次，采用四种策略之一：AgentDebugX 的原生 DeepDebug 指令，或解耦的 Reflexion / CRITIC / AutoManual 基线（这些基线接收的是通用评判摘要，而非 DeepDebug 的局部诊断）。为保持对比的纯净性，评估期间诊断记忆和错误中心为空；两者在实际部署中均为可选启用。重新运行时使用固定温度参数、固定的步骤预算，以及与基线相同的搜索和工具栈。“Rec.”统计的是在失败子集上修复的任务数；“All”则是在完整验证集上推算出的已修正任务数。 定位器设计消融实验。 DeepDebug 的轮次设计是通过在分层抽样的 Who&When 样本上进行测量来确定的：将结构引导轮次替换为第二次全局搜索，在 gpt-5.4-mini 上将严格准确率从某个值降至另一个值，而实际采用的配对方式将智能体准确率提升至某个值（对比单次读取的另一个值）；在 gemini-3.5-flash 上，单次读取已经是最优方案——裁决在评估的开源权重基础模型上有效，但在托管模型上无效——这是一个模型相关的效应。 附录 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 实验在固定的失败子集上评估一个策略模型，并比较完整的重试方案；它既未单独隔离归因的效果，也不是盲测单次得分。错误中心检索和分类体系归纳已实现但尚未评估，且归纳过程需要人工确认。清洗器会剥离事件输入并删除已知的凭证/个人身份信息模式，但不会处理任意内容；恢复执行仍受人工审批控制。