很多团队已经给多智能体系统接上了日志、报错监控和模型调用记录，却依然回答不了三个最关键的问题：为什么这次运行会在这里退化、到底是哪个步骤开始偏离、以及问题是发生在单个执行动作里，还是发生在角色交接时。根因通常不是数据太少，而是 trace 的粒度太粗。所有事件被铺平成一串日志后，团队只能看见“发生过什么”，却看不见“这一串动作属于哪次运行、哪一步决策、哪次交接”。
对生产级多 Agent 系统来说，更稳的做法是把 trace 至少拆成三层：run 代表一条完整任务，step 代表一次关键决策或执行步骤，handoff 代表上下文和责任从一个角色转到另一个角色的边界。Weights & Biases Weave、Braintrust 和 Arize Phoenix 虽然实现细节不同，但都强调 trace、评估和线上诊断要能相互映射。对 TaskPilots 这样的链路追踪与评估治理系统来说，run、step、handoff 三层 span 的价值，就在于把故障定位、失败分类、评估回归和业务复盘真正串成一条证据链。
为什么这个问题重要
真实运行代价
如果 trace 只有模型调用或工具调用层，团队最先失去的不是监控能力，而是解释能力。一次路由错误、一次工具误用、一次人工升级前的信息丢失，在日志里可能都显示“调用成功、接口正常、延迟可接受”，但业务结果已经明显变差。此时问题不在基础设施，而在链路里缺少可以定位决策边界的 span 层次。
Weave 和 Braintrust 的共同思路是把运行记录和评估样本直接挂在同一条 trace 上，而 Phoenix 更强调对实际 trace 的排查与诊断。把这三类能力放在一起看，会发现生产团队真正需要的并不是更多原始日志，而是更清楚的归属关系：某个失败属于哪次 run，发生在哪个 step，是不是在 handoff 后才开始恶化。没有这层结构，团队就很难把技术症状和业务后果对应起来。
如果不处理会怎样
最常见的后果有四个。第一，只能看到平铺日志，无法判断问题究竟出在决策、执行还是交接。第二，回归无感知，新版上线后虽然没有报错，但某一类 handoff 开始频繁丢信息，团队却很晚才发现。第三，线上质量漂移时只能靠人工读长日志补课，故障定位时间越来越长。第四，评估系统和生产 trace 脱节，离线看起来通过的样本，在线上却因为 step 边界不同而表现失真。
适用场景
谁最需要这套方法
最适合引入 run、step、handoff 三层 span 的，是那些已经能跑起来，但团队很难稳定解释故障和退化来源的系统。比如控制器把任务分派给多个专家角色，再做汇总；比如一个客服或运营流程要先自动处理、再在风险节点升级给人工；又比如同一个任务会跨队列、跨时间片恢复。只要系统里存在多个责任边界，这三层 span 就会比单纯的 API 日志更有价值。
对于负责发布治理与评估的团队，这种结构尤其重要。因为你要回答的不只是“模型有没有出错”，而是“这次版本改动到底改善了哪个步骤、恶化了哪个交接、对业务结果产生了什么影响”。没有 run、step、handoff 的区分，版本比较就只能停留在总体成功率，难以形成可操作的回归判断。
什么时候先不要这么做
如果当前流程仍然是单模型、单工具、单次同步执行，而且没有明显的角色交接和恢复需求，那么一开始就铺满三层 span 未必划算。这时更优先的是先把基础日志、错误监控和关键输出保存好，确认系统本身有稳定的输入输出边界。
另一类不适用边界，是产品还处在强探索阶段，任务结构本身经常变化，团队还没对“什么算一个 step”“什么算一次 handoff”达成共识。此时应该先固化最小工作流，再为真正稳定的节点打层次化 span，否则观测体系会跟着原型一起失控。
推荐系统结构
核心角色与状态
比较稳的结构，是让 run 成为任务级容器，step 成为节点级工作单元，handoff 成为角色边界事件。run 负责串起入口、最终结果、用户上下文和业务 outcome；step 负责记录本地输入、选择原因、工具调用、产出和失败类型；handoff 则负责保存交接前后的角色身份、最小上下文包、回传契约版本和接手结果。这样做的重点，不是把每个 token 都记下来，而是把真正影响后续判断的边界记录清楚。
在字段设计上，run 层至少应有任务 ID、版本、起止时间、最终状态；step 层至少应有 step 类型、输入摘要、选择原因、结果摘要和错误分类；handoff 层至少应有发送方、接收方、交接原因、上下文包大小、返回状态和是否升级人工。只要这些字段稳定下来，后续不论是复盘、评估还是发布门槛，都会更容易挂靠到同一套 trace 上。
与 TaskPilots 的映射
映射到 TaskPilots，可以把 run 看成一条任务运行链，把 step 看成控制器、执行器、审查器等节点的关键动作，把 handoff 看成角色切换与责任转移的可审计事件。链路追踪层负责把三者串起来，运营审查层负责对关键 step 和 handoff 做失败分类或人工标注，持续评估层则把这些真实案例抽回离线数据集和发布门槛。
这也意味着，TaskPilots 不该只记录“调了哪个工具”，还应该记录“为什么进入这个 step、为什么把任务交给这个角色、handoff 之后是否出现信息衰减”。和站内的 不要只追工具调用，还要追决策本身 一起看，run、step、handoff 三层 span 本质上是在把决策链路做成真正可诊断、可对比、可治理的结构。
风险与失效点
常见失控方式
第一类失控，是只有 run 没有 step，导致一条任务看似完整，却无法知道具体在哪个判断点开始偏离。第二类失控，是只有 step 没有 handoff，团队能看到本地动作，却看不到跨角色交接时是否发生了上下文缩减、字段缺失或责任漂移。第三类失控，是 span 数量很多但语义很弱，名字像是追踪，实际上还是一串不好比较的碎片日志。
第四类失控，是 trace 和评估系统分离。团队能在 Phoenix 或日志平台里看到问题 run，却无法把这类失败自动沉淀到 Braintrust 或 Weave 的回归样本里。第五类失控，则是只看技术指标，不看业务结果，最后系统优化了延迟和成本，却没优化升级率、转化率或复审通过率。
需要人工兜底的地方
涉及高风险发布、关键路由规则、人工审批节点和客户影响较大的自动化动作时，仍然需要人工兜底。因为即使 trace 分层足够细，系统也未必能自动判断某种新型退化是否值得立即回滚。人工的价值在于基于三层 span 快速看到“问题出在某次 run 的哪个 step、是否集中发生在某类 handoff”，再决定是继续观察、热修复还是回退版本。
另外，当失败分类本身出现分歧时，也应该保留人工复核。否则团队会在自动标签之上继续堆自动判断，最后看似观测越来越强，实际分类标准越来越漂。
验证指标
上线前怎么验证
上线前三类验证最关键。第一，故障回放验证：拿历史故障样本重放，确认团队是否能仅凭 run、step、handoff 三层 span 还原关键问题。第二，评估映射验证：检查离线评估样本是否能追溯到真实 trace，反过来真实 trace 的高频失败是否能进入回归集。第三，灰度发布验证：在小流量下观察新的 span 结构能否帮助团队更快定位问题，而不是仅仅增加日志量。
如果要更严格一些，可以专门做 handoff 退化测试。比如故意缩减交接包、修改角色回传字段，再检查 trace 是否能清楚暴露问题发生在 handoff 层而不是工具层。只要这一点做不到，就说明 span 结构还没有真正覆盖协作边界。
上线后怎么持续判断
上线后建议长期跟踪至少四个指标：故障定位时间、评估通过率、线上回滚率和业务转化指标。前两项衡量可解释性和发布质量，第三项衡量是否能更早发现退化，第四项则保证 tracing 体系没有脱离业务结果。除此之外，再补两个更贴近 span 设计的指标会很有帮助：step 归因成功率，以及 handoff 失败识别率。
如果团队发现大部分问题仍然只能归到“某次运行有问题”，却说不清具体 step 或 handoff，那么说明 span 结构还不够细；如果 step 已经很清楚，但 handoff 相关故障仍然经常漏掉，则说明交接事件记录还不够完整。
下一步 / FAQ
下一步建议
最实际的第一步，不是一次性重构整套观测平台，而是先挑一条高价值、多角色、容易退化的链路，把它拆成 run、step、handoff 三层。先为三个最关键的 step 打 span，再把角色交接事件单独打出来，最后把这些 trace 接回评估样本与发布检查。只要这一条链路跑通，团队很快就能感受到排障速度和回归判断的差别。
第二步再统一失败分类词表。因为没有统一标签，再细的 span 也很难沉淀成稳定评估资产。第三步才是扩大到更多链路，把运营标注、线上回归和发布门槛逐步挂回这套三层结构。
FAQ
是不是所有 step 都要单独打 span？ 不一定。优先记录真正影响分支选择、工具调用和结果解释的关键 step，而不是把每个细节都膨胀成 span。
handoff span 和普通事件有什么区别？ handoff 代表责任和上下文的正式转移，它需要记录发送方、接收方、交接原因和结果状态，不只是一个普通日志点。
已经有 APM 和调用链，还需要这套吗？ 往往仍然需要。APM 擅长看服务和性能，run、step、handoff 更擅长看协作决策和质量退化。
组织协作最容易卡在哪里？ 最常卡在失败分类和 step 边界没有统一口径。没有共同语义，trace 很快又会退化成数量更多但更难用的日志。