Maple agent tracing: Cloudflare Agents SDK

Goal

One chat (one agent instance) = one Maple Agent Session, one turn per user message, with the transcript, every model call (model, tokens), every tool call (name, args, result, failures), and a lane per sub-agent.

Known gaps (tell the user, don't try to fix): cost shows as "unpriced" (the AI SDK emits no cost). These traces are separate from Cloudflare's native Workers traces (different trace ids); that's expected.

Step 0: Detect

• agents in package.json; chat agents extend AIChatAgent from @cloudflare/ai-chat (or the older agents/ai-chat-agent), others extend Agent from agents. Find every class and every AI SDK call site in them: streamText(, generateText(, generateObject(, streamObject(, new ToolLoopAgent(, .generate(, .stream(.
• ai version: >= 7.0.106 required. On 5.x/6.x ask the user to upgrade (npx @ai-sdk/codemod v7). ai@7 also forces agents >= 0.23, @cloudflare/ai-chat >= 0.11, @ai-sdk/react@^4, workers-ai-provider@^4 (and @ai-sdk/openai|anthropic@^4): upgrade them in the same install. On ERESOLVE, regenerate the lockfile. The upgrade can break unrelated agent code (e.g. chatRecovery = true now needs as const); typecheck and tell the user. Don't use experimental_telemetry / metadata (v6 API).
• Models via workers-ai-provider (createWorkersAI({ binding: env.AI })), @ai-sdk/openai, @ai-sdk/anthropic, AI Gateway: fine at the ^4 majors above; the spans come from the AI SDK, not the provider.
• Agents that call a model without the AI SDK (raw env.AI.run(...), fetch to a provider, @tanstack/ai): this skill doesn't cover them. Use the maple-agent-tracing-opentelemetry skill to write the spans by hand with the same tracer provider from Step 2.
• wrangler.jsonc/wrangler.toml must have compatibility_flags: ["nodejs_compat"] (Agents SDK projects always do; the context manager needs AsyncLocalStorage).
• Existing OpenTelemetry in the Worker: search for @microlabs/otel-cf-workers (instrument(, instrumentDO(), BasicTracerProvider, WebTracerProvider, registerTelemetry(, @sentry/cloudflare, @langfuse/otel, braintrust.
  • registerTelemetry(...) already exists: extend that call; never call it twice.
  • An existing tracer provider (including otel-cf-workers): add one Maple span processor/exporter to it and pass tracer: provider.getTracer("gen_ai") to OpenTelemetry; don't build a second provider. Still add the per-turn flush from Step 4 (untested whether otel-cf-workers' own flush covers AIChatAgent turns, which run over WebSocket messages and finish after the handler returns). Don't add otel-cf-workers to a project that doesn't have it: this setup doesn't need it (last release May 2025).
  • Cloudflare's native observability.traces destinations (Workers Observability) can stay; they export runtime spans (fetch, bindings, DO calls, and the Agents SDK's own cloudflare.agents.* spans) but never AI SDK spans, because @ai-sdk/otel uses @opentelemetry/api, which the native tracer doesn't back.