feat(observability): identify agent spans

[Ankcorn]

Why

Users need to compare Agent token usage, cost, model preferences, latency, and errors without stitching together different identity fields.

Closes #1975

What

Add a consistent identity block to SDK-created Agent spans:

• instrumentation_scope.name
• instrumentation_scope.version
• cloudflare.agents.session.id
• cloudflare.agents.session.name
• gen_ai.agent.name

Usage (AI SDK v7)

Set agent identity in runtimeContext on each generateText/streamText call. The wrapper propagates it to the invoke_agent, chat, and execute_tool spans, so the Agents dashboard can aggregate sessions, runs, and tokens.

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

const { generateText } = wrapAISDK(ai);

await generateText({
  model,
  prompt,
  runtimeContext: {
    agentName: "support-agent",   // → gen_ai.agent.name
    conversationId: "conv-456",   // → gen_ai.conversation.id
    agentId: "agent-123",         // → gen_ai.agent.id (optional)
    agentVersion: "1.0.0",        // → gen_ai.agent.version (optional)
  },
});

agentName and conversationId are the minimum the dashboard needs; agentId/agentVersion are enrichment. experimental_telemetry.functionId also works as a fallback for agentName.

---

[changeset-bot]

🦋 Changeset detected

Latest commit: dc09000

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

This PR includes changesets to release 2 packages

Name	Type
agents	Patch
@cloudflare/agent-think	Patch

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@1978

@cloudflare/ai-chat

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

@cloudflare/codemode

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

hono-agents

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

@cloudflare/shell

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

@cloudflare/think

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

@cloudflare/voice

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

@cloudflare/worker-bundler

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

commit: dc09000

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 1 additional finding in Devin Review.

[devin-ai-integration]

🟡 Existing agent trace searches stop matching because two identity fields were renamed without notice

The identity labels that every agent trace used to carry are replaced with differently-named ones (agentSpanAttributes(...) at packages/agents/src/index.ts:1926-1930) while the published documentation and the release note still promise the old labels, so dashboards and saved searches built on them silently return nothing.
Impact: Users' existing observability queries and dashboards for agent traces quietly stop finding data after upgrading, with no changelog warning.

Renamed span attributes vs. documented contract

Before this PR _withAgentSpan emitted cloudflare.agents.agent.id (instance name) and cloudflare.agents.agent.name (agent class) on every SDK-created agent span (agent_initialization, initialize_agent_storage, agent_start, schedule_agent_alarm, etc.). The new code drops both and emits cloudflare.agents.session.id (the DO id), cloudflare.agents.session.name (the instance name) and gen_ai.agent.name (the class) instead.

docs/agents/observability.md:269-271 still documents cloudflare.agents.agent.name / cloudflare.agents.agent.id as the attributes on these spans, and the changeset (.changeset/curly-agents-trace.md) describes the change as purely additive ("Add ... attributes"), giving no signal that two attributes were removed/renamed. Note also that cloudflare.agents.session.id is the Durable Object id, not the previous agent.id value (the instance name), so it is not a drop-in replacement.

Prompt for agents

The agent span identity attributes were renamed: cloudflare.agents.agent.id and cloudflare.agents.agent.name are no longer emitted by Agent._withAgentSpan in packages/agents/src/index.ts; they are replaced by cloudflare.agents.session.id (the Durable Object id), cloudflare.agents.session.name (the instance name) and gen_ai.agent.name (the class name). docs/agents/observability.md around lines 267-272 still documents the old attribute names on the agent_initialization span, and .changeset/curly-agents-trace.md describes the change as additive only. Decide whether to keep emitting the old attributes for one release for backward compatibility, and in any case update the docs and the changeset text to call out the removal/rename so downstream dashboards and queries can be migrated.

---

Was this helpful? React with 👍 or 👎 to provide feedback.