feat: Cloudflare-native AI tracing (agents/observability + agents/observability/ai)

[mattzcarey]

Cloudflare-native tracing for AI agents: spans built on the Workers runtime's tracing API (cloudflare:workers), named and attributed to the OpenTelemetry GenAI semantic conventions, flowing to Workers Observability with zero dependencies. No OTel SDK, no exporter, no collector — traces show up in the dash next to your fetch/DO/KV spans.

Instrumenting the AI SDK

Enable traces on the Worker:

// wrangler.jsonc
{
  "observability": { "traces": { "enabled": true } }
}

AI SDK v6 — wrap the namespace once, use it as normal:

import * as ai from "ai";
import { wrapAISDK } from "agents/observability/ai";

const { generateText, streamText } = wrapAISDK(ai);

await streamText({
  model,
  prompt: "book a table for two",
  tools: { searchRestaurants, reserve },
  experimental_telemetry: {
    functionId: "booking-agent", // becomes gen_ai.agent.name
    metadata: { conversationId: "conv-42" }
  }
});

Every call produces one semconv-shaped trace:

invoke_agent booking-agent            gen_ai.operation.name=invoke_agent, tokens, finish reason
├── chat gpt-4o                       per doGenerate/doStream: model, params, usage, time_to_first_chunk
├── execute_tool searchRestaurants    gen_ai.tool.name, gen_ai.tool.call.id, real duration
└── chat gpt-4o

AI SDK v7 — register the telemetry lifecycle adapter instead of wrapping:

import { registerTelemetry } from "ai";
import { createAISDKTelemetry } from "agents/observability/ai";

registerTelemetry(createAISDKTelemetry());

Same spans, driven by the SDK's telemetry callbacks, correlated by cloudflare.agents.call.id / gen_ai.tool.call.id.

Stream spans stay open until the stream is consumed, cancelled, errors, or is returned early — an aborted stream closes as canceled, not as a false success. Streaming tools (async-generator execute) keep their span open until the iterable is drained (bodies run inside the tool span's async context; early termination still runs the generator's own cleanup), so tool durations are real. Untraced invocations take a pristine fast path: the original operation gets the original params — no tool wrapping, no model middleware, no stream patching.

Think: traced out of the box

Think agents emit this exact trace tree per turn with zero configuration and zero new API surface. The turn's streamText call is the invoke_agent root span — named after the agent class, carrying agent/conversation identity plus turn attributes (cloudflare.agents.turn.request_id, .trigger, .admission, .channel, .continuation, .generation) — with inference and tool calls as its only children. No opt-in flag, no setup, nothing exported; on runtimes without the tracing API the tracer is a no-op.

invoke_agent SupportAgent              turn identity + request params + aggregated usage
├── chat gpt-4o                        per inference step
├── execute_tool lookupOrder           gen_ai.tool.call.id, real duration
└── chat gpt-4o

How it works internally: Think merges its identity and current-turn metadata into experimental_telemetry.metadata at the call site (caller-provided metadata wins, and still flows to the AI SDK's own telemetry when enabled), and the wrapper projects those onto root-span attributes — reserved keys to cloudflare.agents.turn.*, userId to semconv user.id, any other scalar to cloudflare.agents.metadata.{key}. Drain loops also finalize the underlying model stream on early exit (in-stream error, stall abort, user abort) so operation spans close instead of leaking — the SDK tees its base stream, and an abandoned tee branch would otherwise leave the span open forever.

Schema

Span names follow the semconv formula with a bare-operation fallback past 64 UTF-8 bytes. Query on gen_ai.operation.name, never the span name.

Span	gen_ai.operation.name	Carries
invoke_agent {agent}	invoke_agent	agent/conversation identity, request params, aggregated usage (incl. cache + reasoning tokens), finish reasons
chat {model}	chat	per-model-call params, usage, gen_ai.response.id/model, gen_ai.response.time_to_first_chunk
execute_tool {tool}	execute_tool	gen_ai.tool.name, gen_ai.tool.call.id, real execution duration

• Semconv keys (gen_ai.*) wherever a home exists; vendor extensions under cloudflare.agents.* — never bare keys, never ai.* (that's the Vercel AI SDK's namespace; squatting it would fake compatibility we don't have).
• Failures: otel.status_code: "ERROR" + error.type (the spec-defined status encoding for status-less backends). Cancellations: cloudflare.agents.canceled: true, status untouched — aborts are not errors.
• Scalar-only, content-free: no prompts, messages, tool inputs/outputs, schemas, or raw error messages, ever. Semconv content capture is opt-in and stays permanently off here.

Public surface (kept deliberately small)

agents/observability: tracer + types AgentTracer / AgentSpan / TraceAttributes / TraceAttributeValue. agents/observability/ai: wrapAISDK, createAISDKTelemetry. Everything else — span builders, attribute constants, the SpanRuntime seam — is private, so when the runtime gains native OTel support we can converge behind the facade without a breaking change (names were chosen to avoid @opentelemetry/api collisions; our openSpan is not OTel's startSpan, which creates without activating).

Provenance

Ported from @msmps's feat/ai-tracing branch — commits carry Co-authored-by credit — then folded into the agents package and aligned with the GenAI semantic conventions.

Testing

• 54 observability tests (tracer, v6 wrapper, v7 adapter): span names + fallback, abort-chunk cancellation, streaming-tool span lifetime, tool call ids, time-to-first-chunk, metadata→attribute passthrough (reserved keys, user.id, scalar passthrough, object dropping, identity consumption)
• agents workers project: 78 files / 1539 tests green
• think: workers project 42 files / 894 tests green with instrumentation live, plus generated-entry/vite/cli/react projects green
• npm run check green across all 114 projects

[changeset-bot]

🦋 Changeset detected

Latest commit: 2fcf743

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
agents	Minor
@cloudflare/think	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1860

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1860

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1860

create-think

npm i https://pkg.pr.new/create-think@1860

hono-agents

npm i https://pkg.pr.new/hono-agents@1860

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1860

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1860

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1860

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1860

commit: 2fcf743