OpenTelemetry GenAI 语义约定：Agent span 还在 Development，但生产系统已经等不起了

OpenTelemetry 的 GenAI 语义约定在 2026 年处于一个尴尬但真实的状态：规范本身仍在 Development 稳定级，Agent、工具、MCP 的 span 定义还没有 stable，但已经有大量生产系统在依赖它做可观测性。语义约定 v1.42.0 在 2026 年 6 月把 GenAI、OpenAI 和 MCP 的定义从核心仓库移到了独立的 GenAI 仓库，旧链接仍然可用但指向“Moved”提示。这意味着规范在活跃演进，但没有 stable 的承诺。

这个状态对生产团队的含义很具体：你可以用，但不能假设字段名和语义不会变；你需要 pin 版本，并且在升级 SDK 或语义约定版本时显式验证后端解析逻辑。一个常见的故障模式是：SDK 升级了，语义约定版本变了，后端仍在按旧字段名解析，指标看起来还在，但某个关键属性的含义已经漂移，直到某次排障时才发现 trace 里缺了一整类信息。

规范的覆盖范围已经超出了“模型调用”本身。一个模型调用是一个名为 {gen_ai.operation.name} {gen_ai.request.model} 的 span，携带 provider 名称、token 用量、响应模型和结束原因；Agent 有 invoke_agent、invoke_workflow、plan 和 execute_tool 等 span 类型；工具调用如果执行 shell 命令或 agent skill，有专门的细化属性。跨 MCP 跳转时，trace context 放在每个 JSON-RPC 消息的 params._meta 里，而不只是 HTTP header 里。这些设计的意图是让不同框架、不同供应商的 GenAI 调用可以在同一套查询语言下被分析，而不是每个 SDK 发明一套字段。

但规范里最重要的一个设计决策是默认不采集内容。指令、输入消息、输出消息、工具定义、工具参数和工具结果都是 Opt-In 属性，默认关闭。这是整个规范里最被低估的安全控制：一旦内容采集打开，trace 存储里就会包含 Prompt、个人数据和粘贴的密钥；脱敏要在 SDK 层先做、Collector 层再做，保留期要短，租户要隔离。很多团队在初期为了方便排障把内容采集打开，之后忘了关，等到安全审计时才发现 trace 存储变成了一个未经治理的 PII 仓库。

一个务实的落地顺序是：先只采集结构化元数据——span 名称、模型名、token 用量、延迟、状态——确认查询和仪表盘能工作；再对特定环境、特定租户打开内容采集，并同时配置 SDK 层和 Collector 层的脱敏；把语义约定版本和 SDK 版本一起 pin 住，在升级时跑一个验证用例，确认关键字段仍然能被正确解析。Agent span 还在 Development 不意味着不能用，它意味着你需要把“规范会变”当作一个已知的运维条件来设计，而不是假设它和 HTTP 语义约定一样稳定。