AI Agent 排障：trace 与 tool span 的 12 个最小字段

AI Agent 出现慢、贵、答错或工具失败时如果第一反应还是“再改一版 Prompt”通常会把真正的问题继续藏起来。只看最终回复你看不见哪次工具只返回部分结果、权限闸门有没有生效也分不清超时发生在模型、网络还是业务系统。当 Agent 会调用多个工具、写业务状态或失败后自动重试它就需要一条能从任务入口回放到最终结果的最小证据链。trace 负责串起来span 负责拆开看OpenTelemetry 把 span 定义为一个工作单元。多个 span 共享trace_id再通过父子关系组成一条端到端 trace。放到 Agent 里可以先拆成三层run span这次业务任务从哪里开始最后停在哪个状态model span模型这一步负责规划、抽取、判断还是生成tool span调用了哪个工具返回完整、部分、被拦还是失败。W3C Trace Context 解决的是跨服务传播和关联。它不是业务审计表也不该承载客户原文、手机号、订单详情等敏感载荷。所以Agent trace 要做到跨服务可关联、业务后果可解释。先统一 12 个最小字段下面这 12 个字段不是某个厂商的固定 schema而是一份适合第一轮排障的通用结构字段解决的问题推荐落点trace_id多个服务和步骤是不是同一次运行所有 spanrun_id能否回到一个业务任务run spantask_type这次任务属于哪类流程run spanspan_type当前是 run、model 还是 tool所有 spanspan_name当前步骤具体做什么所有 spanparent_span_id这一步由谁触发子 spanstarted_at什么时候开始所有 spanduration_ms慢在哪一步所有 spaninput_ref能否回到脱敏后的输入引用run / tool spanresult_state完整、部分、被拦还是失败model / tool spanerror_code失败类型能否稳定聚合model / tool spanrecovery_action下一步是重试、转人工还是停止tool / run spaninput_ref应是稳定引用或脱敏摘要不要把原始输入、工具参数和返回复制成第二份敏感数据仓库。上线前可对照 trace 与审计 10 项清单核对关联、脱敏、失败状态和人工接管。一份最小配置要先写脱敏和失败状态不要等到接入观测平台以后再决定哪些字段能记录。配置里先把必填项和敏感载荷规则写死agent_trace:propagate:-trace_id-parent_span_idrequired_fields:-run_id-task_type-span_type-span_name-started_at-duration_ms-input_ref-result_state-error_code-recovery_actionresult_states:-success-partial-blocked-failedpayload_policy:store_raw_input:falsestore_raw_tool_output:falseredact_before_export:true这里最容易漏的是partial和blocked。工具返回 HTTP 200不代表业务结果完整权限闸门拦住写操作也不该被记成普通失败。把它们压进 success / failed告警和重试都会选错动作。model span 和 tool span 不要混成一条日志模型调用与工具调用的责任不同最好分开记录。model span 记录调用目的、模型标识、token、结构化输出校验和回退。tool span 记录工具名、脱敏参数摘要、返回状态、错误码、重试、权限闸门和恢复动作。下面是通用结构示例没有使用真实客户数据、真实成本或私有系统名称{trace_id:opaque-trace-id,run_id:opaque-run-id,task_type:ticket_summary,spans:[{span_type:model,span_name:plan_next_step,result_state:success,schema_valid:true},{span_type:tool,span_name:fetch_ticket_context,input_ref:redacted-input-ref,result_state:partial,error_code:MISSING_REQUIRED_FIELD,recovery_action:handoff}]}这条记录能回答Agent 完成了规划但工具只返回部分结果因此没有继续写状态而是转入人工接管。若日志只能显示“工具调用结束”它对生产排障仍然不够。上线前跑 5 条反向验证有字段不等于字段可靠。最少跑下面五条反向用例model span 和 tool span 的trace_id不一致时整次运行应被判为证据链断裂tool span 缺少result_state时不允许进入成功统计partial结果仍触发写操作时权限或流程测试必须失败trace 属性出现手机号、邮箱、订单原文等敏感模式时导出前必须阻断或脱敏blocked/failed没有recovery_action时不能关闭事故记录。这些测试要在事故前确认证据能串起来敏感数据不会扩散失败后也确实有人接。先用证据缩小问题再决定改什么trace 补齐以后很多“模型不稳定”会被重新分类工具返回不完整、schema 校验反复修复、错误重试放大副作用或权限闸门本就应该拦住动作。再改 Prompt、模型路由、工具契约或恢复策略时团队才知道正在修哪一层也能用同一批 trace 复测。如果生产 Agent 还回答不了“哪一步失真、哪个工具只返回部分结果、为什么被拦、失败后由谁接”先补证据链。官方文档核对OpenTelemetry TracesW3C Trace Context。