排查 AI Agent 执行失败，先找实际路径中第一处偏离预期的事件。任务状态用来确认执行停在哪里，Trace 用来还原模型、Workflow 与工具调用的先后关系，组件日志再解释具体错误。涉及文件、消息或数据写入时，还要核对外部系统留下的结果标识。

ZGI 把 Agent、Workflow、模型路由和运行组件放在同一个 Agent Runtime 工作区。排障时可以先从 Workflow Run 和 Node 记录缩小范围，再接着检查模型路由、工具请求与返回结果。这样查的是一次完整执行，避免在几套互不关联的日志里碰运气。

别从最后一条报错开始

一项文件生成任务显示“已完成”，用户却没有收到产物。期望路径通常包含生成、保存、上传和交付四个事件。交付步骤报错时，真正的偏差可能更早出现：保存步骤没有返回文件标识，后面的上传仍被触发，直到交付时才抛出“文件不存在”。

最后一条错误只说明系统在哪里停下。排障要顺着同一个 Run ID 回到时间线开头，找到最后一个符合预期的事件，再检查紧随其后的变化。后续十条错误可能都由这一个断点引起。

概念示意图：围绕同一个 Run ID 检查生成、保存、上传和交付事件，先定位第一处异常，再查看对应日志。

沿着关联标识逐层缩小范围

先保存失败现场，包括 Run ID、发起时间、任务版本、输入摘要和期望产物。页面刷新、重新提交或手动重试可能改变现场，原始执行记录丢失后，后面的判断只能依靠猜测。

接着检查任务状态和节点顺序。节点停在等待状态，要看它在等人工确认、外部回调还是资源；节点已经失败，就找前一个成功节点的输出是否满足下游输入。实际路径与设计路径不同，还要检查分支条件、Agent 交接和循环终止条件。

模型调用出现异常时，核对使用的模型、路由结果、输入摘要、结束原因、耗时和返回格式。工具调用则要把请求与外部回执放在一起看。HTTP 超时无法直接证明动作失败，目标系统里的文件 ID、任务号或写入记录更接近真实结果。

组件日志放到范围已经缩小以后再查。此时已经知道具体 Run、节点、调用和时间段，错误栈才有上下文。直接搜索整套服务日志，容易被重试、健康检查和其他并发任务淹没。

在 ZGI 中保留一条可追踪的执行链

ZGI 的 Workflow 运行记录按 run 和 node 保存状态、时间、输入输出元数据与失败摘要。启用 OpenTelemetry 后，模型网关的 Span 可带 provider、route、attempt 和 trace 元数据。团队可以用这些关联信息把一次任务从 Workflow 节点追到模型调用，再核对工具结果。

记录范围也要受控。提示词、工具参数和模型输出可能带有业务资料、个人信息或凭据，运行日志应保存必要摘要，对敏感字段做遮盖，并限制查看权限与保留时间。Trace 能帮人还原路径，也可能成为新的敏感数据集合。

一张简短的故障记录卡已经够用：Run ID、期望结果、第一异常节点、Trace ID、工具调用 ID、外部结果标识和处理结论。拿一条真实失败任务试着复原路径；十分钟内仍找不到第一处偏差，就说明关联标识或事件记录还有缺口。

GitHub：https://github.com/zgiai/zgi

Gitee：https://gitee.com/zgiai/zgi