@ai-sdk/workflow 2.0.94 更新：WorkflowAgent 遥测全面升级

一次"低调"的补丁，解决了持久化 Agent 的可观测性难题

@ai-sdk/workflow@2.0.94 在版本号上只是一个补丁版本，但从变更内容看，它触及的是 AI Agent 工程化里最容易被忽视、也最影响生产落地的一环——持久化运行的遥测（telemetry）。这个版本为 durable（可持久化）的 WorkflowAgent 运行引入了单次 telemetry operation 支持，把 prompt、最终输出、执行步骤和工具调用统一纳入同一条追踪链路。

对于把 Agent 跑在长时间任务、断点续跑场景里的团队来说，这个改动值得关注。

核心变更：一次操作覆盖整段 Agent 运行

从"碎片化追踪"到"单条操作"

此前，durable WorkflowAgent 的执行过程更容易被拆散成多条互相独立的追踪记录。而这次补丁版本支持为一次 durable 运行生成单个 telemetry operation，覆盖范围包括：

• prompt（提示词）
• final output（最终输出）
• steps（执行步骤）
• tools（工具调用）

更关键的是对时序还原的处理：工作流中记录的事件会在运行完成或挂起（suspension）时上报，并携带其原始时间戳。这解决了一个实际痛点——持久化 Agent 可能在数小时甚至跨天之后才完成，如果按上报时间打点，事件顺序和耗时分析就全乱了。

持久化（durable）Agent 与普通同步 Agent 的关键区别在于执行生命周期。普通 Agent 的调用通常在一次进程内完成，追踪数据可以实时上报。而持久化 Agent 可能在执行到一半时被挂起（例如等待外部事件、人工审批或定时触发），进程可能退出，数小时甚至数天后才从持久化存储中恢复继续执行。如果按实时上报的方式打点，恢复后的 span 会以新的时间基准出现在追踪系统中，导致事件顺序错乱、耗时统计失真。保留原始时间戳意味着每个事件在生成时就记录其真实发生时刻，上报时再携带该时间戳写入追踪后端，这样无论上报延迟多久，追踪系统都能还原出正确的因果顺序和实际耗时分布。

OpenTelemetry 的显式桥接

原文特别说明了与 OpenTelemetry 配合使用的方式：需要把一个相同的 OpenTelemetryIdGenerator 实例同时传给 tracer provider 的 idGenerator 和 sampler，以及传给 new OpenTelemetry({ durable })。

这个显式桥接承担了几件实事：

• 在步骤之间传递 parent trace context 与采样决策
• 模型 span 实时上报，provider 请求嵌套在其下
• 运行完成时重建完整的 invoke_agent 调用树

如果不用这个桥接，行为会回退到原有的逐模型实时追踪模式。也就是说，升级不会破坏现有接入方式，新能力是可选增强而非强制迁移。

OpenTelemetry 中的 IdGenerator 负责为每个 span 生成 Trace ID 和 Span ID，而 Sampler 决定某个 trace 是否被采样以及采样率。在分布式追踪中，为了让一次请求链路中的多个服务或步骤能够被关联到同一个 trace 下，各个组件必须对 Trace ID 的生成和采样决策保持一致。OpenTelemetryIdGenerator 是 AI SDK 提供的一个自定义 ID 生成器实现，它允许在持久化 Agent 的不同执行阶段（包括挂起后恢复）复用同一个 Trace ID 生成逻辑，从而确保跨步骤、跨时间的 span 能正确归属到同一条 trace。将同一个实例同时注入 idGenerator 和 sampler，本质上是在保证 ID 生成与采样决策共享同一份状态，避免因实例不同导致 trace 断裂或采样不一致。

移除对进程级 ID 生成器检测的依赖

补丁同时新增了带类型的实验性 durable context hooks 供遥测集成使用，并移除了对进程全局 ID-generator 检测的依赖。后者属于工程质量层面的改进：进程级全局状态的隐式检测在多实例、多租户环境下容易产生难以复现的问题，改为显式传递后，链路行为更可预期。

进程级全局状态检测是指库在运行时通过检查全局变量或模块级单例来自动发现可用的 ID 生成器或追踪配置。这种方式在单进程、单租户的开发环境中通常工作良好，但在生产环境的多实例部署、多租户隔离或同一进程内运行多个独立 Agent 的场景下，全局状态可能被多个逻辑单元共享或覆盖，导致不同租户或不同 Agent 的 trace 相互污染，且问题往往难以稳定复现。改为显式传递（通过参数或 context hooks 注入）后，每个 Agent 运行都能明确绑定自己的遥测上下文，行为更加可预测，也便于测试和隔离。

连带依赖更新

该版本一并更新了依赖：@ai-sdk/provider-utils@5.0.74 和 ai@7.0.162。发布记录显示这是一次包含单个提交的补丁发布。

依赖版本的同步更新意味着遥测相关的能力改进很可能分散在 SDK 的多个包中，单独升级 workflow 包而不同步底层依赖，可能拿不到完整效果。

对开发者意味着什么

第一，可观测性从"能看"走向"能对上"。 单条 operation 加原始时间戳的组合，让 durable Agent 的成本归因、延迟分析和失败回溯有了可靠的数据基础。

第二，接入是渐进的。 不配置桥接就退回旧的实时追踪，这对已经在生产中运行的系统比较友好。

第三，显式优于隐式。 去掉对全局 ID 生成器检测的依赖，虽然对使用者的改动量可能不大，但这类设计倾向值得肯定——尤其当 Agent 需要跨步骤、跨执行环境维持 trace 一致性时，隐式约定往往是故障的来源。

需要提醒的是，这个版本的能力主要面向已经使用 OpenTelemetry 并需要 durable Agent 追踪的场景。如果只是短时同步调用 Agent，本次更新的直接影响有限。

背景补充

相关概念：工作流中的挂起与恢复

持久化工作流引擎通常支持挂起（suspension）语义：当某个步骤需要等待外部条件时，引擎将当前执行状态序列化保存，释放计算资源，待条件满足后再从断点恢复。对于 Agent 工作流而言，挂起点可能出现在工具调用等待 API 响应、等待人工确认或等待定时任务触发等场景。这种机制使得一次逻辑上的 Agent 运行可能跨越多个进程生命周期，因此遥测系统不能假设所有 span 都在同一进程内连续产生。单次 telemetry operation 的设计正是为了在这种非连续执行模型下，仍然产出一条逻辑上完整的追踪记录。