从扁平日志到执行树:调试现代 AI 智能体 笔记

从扁平日志到执行树:调试现代 AI 智能体

Agent 追踪本质上是一系列事件序列,但开发者需要将其因果结构可视化为执行树。构建这些树不仅需要按时间戳排序,因为事件可能乱序到达、兄弟节点可能并发运行,且跨度(spans)可能不完整或被重试。一个最小事件契约可确保追踪和跨度的身份稳定,其中开始事件确立父子关系,结束事件定义结果。仅靠时间戳不足以正确确定父子关系,因此必须显式地将开始和结束事件组装为跨度。跨度组装器管理状态,缓冲结束事件直至其对应的开始事件到达,并对缺失开始或重复事件等问题报告诊断信息。它显式表示已组装的跨度,并通过建议大小限制和过期策略来处理无界流可能带来的未来问题。构建执行树森林可优雅地处理多个根节点和孤立跨度,防止崩溃并确保所有信息均被呈现。在渲染前验证父链接是否存在循环至关重要,以避免无限递归。孤立跨度(即没有明确父节点的跨度)应单独显示,以免掩盖仪器化间隙。兄弟节点按开始时间排序以实现稳定显示,但这并不暗示因果关系,因为并行子节点可能存在显著重叠。有用的用户界面应结合树视图(展示父子关系和重试情况)与时间线视图(展示重叠和延迟)。由于跨度持续时间包含了子跨度持续时间及并行工作的重叠部分,因此对跨度持续时间求和会高估追踪时间。相反,追踪墙钟时间、跨度持续时间、自身时间和关键路径是更准确的指标。重试和回退应建模为操作的子节点,使得即使子节点失败,父节点仍可视为成功。部分追踪必须被保留,不完整的跨度应以独特方式渲染,并说明其不完整的原因,避免虚构持续时间或状态。比较树应基于不变属性(如跨度类型、父子关系和终端状态),而非精确快照。事件存储应保持易于追加的特性,事件按追踪 ID 索引,且默认排除敏感数据。验证可确保追踪的完整性,将验证错误与实际代理错误区分开来。核心转变在于:不再将事件到达顺序视为执行顺序,而是将生命周期事件组装为可信的结构化树,以便更好地进行检查。