[Agents] Document AI SDK tracing

src/content/changelog/agents/2026-03-02-agents-sdk-v0.7.0.mdx

@@ -72,7 +72,7 @@ export default {
 
 The custom `Observability` override interface is still supported for users who need to filter or forward events to external services.
 
-For the full event reference, refer to the [Observability documentation](/agents/runtime/operations/observability/).
+For the full event reference, refer to the [Diagnostics channels documentation](/agents/runtime/operations/observability/diagnostics-channels/).
 
 ## `keepAlive()` and `keepAliveWhile()`
 

src/content/changelog/agents/2026-08-04-agent-tracing.mdx

@@ -0,0 +1,67 @@
+---
+title: Agent traces for Think, Flue, and AI SDK instrumented by Agents SDK
+description: Agent traces show model calls, tool runs, approvals, token usage, and runtime operations for each turn.
+products:
+  - agents
+  - workers
+date: 2026-08-04
+---
+
+import { TypeScriptExample, WranglerConfig } from "~/components";
+
+Agent tracing is now available for applications built with the Agents SDK. Traces show each agent turn alongside model calls, tool runs, approvals, token usage, and Workers runtime operations.
+
+Turn on Workers tracing in your Wrangler configuration:
+
+<WranglerConfig>
+
+```toml
+[observability.traces]
+enabled = true
+```
+
+</WranglerConfig>
+
+Think and Flue applications emit agent traces automatically. For direct AI SDK calls, wrap the AI SDK namespace once. `wrapAISDK()` supports AI SDK v6 and v7. This AI SDK v7 example also supplies the agent identity:
+
+<TypeScriptExample>
+
+```ts
+import * as ai from "ai";
+import { wrapAISDK } from "agents/observability/ai";
+
+const tracedAI = wrapAISDK(ai);
+
+await tracedAI.generateText({
+	model,
+	prompt: "Find an available appointment",
+	runtimeContext: {
+		agentId: "booking-agent-production",
+		conversationId: "conversation-123",
+	},
+	telemetry: {
+		functionId: "booking-agent",
+		includeRuntimeContext: {
+			agentId: true,
+			conversationId: true,
+		},
+	},
+});
+```
+
+</TypeScriptExample>
+
+Message and tool payload recording is off by default. Turn it on only when the payloads are safe to store:
+
+<TypeScriptExample>
+
+```ts
+const tracedAI = wrapAISDK(ai, {
+	storeMessages: true,
+	storeTools: true,
+});
+```
+
+</TypeScriptExample>
+
+Open the [**Agents** tab](https://dash.cloudflare.com/?to=/:account/agents) in the Cloudflare dashboard to inspect sessions, replay conversations, and view trace waterfalls. For advanced setup, privacy controls, and trace structure, refer to [Agent tracing](/agents/runtime/operations/observability/tracing/).

src/content/docs/agents/harnesses/think/index.mdx

@@ -132,6 +132,23 @@ tag = "v1"
 
 </WranglerConfig>
 
+### Tracing
+
+Think uses `wrapAISDK()` internally to instrument model turns, tool calls, and approval lifecycle segments. You do not need to wrap the AI SDK or configure an adapter. To send `invoke_agent`, `chat`, `execute_tool`, and `tool_approval` spans to Workers Observability, turn on Workers traces:
+
+<WranglerConfig>
+
+```toml
+[observability.traces]
+enabled = true
+```
+
+</WranglerConfig>
+
+Traces appear in the Agents view in the Cloudflare Dashboard. You can inspect conversations and trace timelines. To turn tracing off, set `observability.traces.enabled` to `false`. You do not need to change the Think agent class.
+
+For span attributes, payload controls, exporting traces, and direct AI SDK v6 or v7 setup, refer to [Tracing](/agents/runtime/operations/observability/tracing/).
+
 ## Think vs AIChatAgent
 
 Both Think and [`AIChatAgent`](/agents/communication-channels/chat/chat-agents/) extend `Agent` and speak the same `cf_agent_chat_*` WebSocket protocol. They serve different goals.

src/content/docs/agents/harnesses/think/recovery.mdx

@@ -45,7 +45,7 @@ export class MyAgent extends Think<Env> {
 
 </TypeScriptExample>
 
-The same recovery events are available through `agents/observability` on the `chat` channel; transcript repairs are emitted on the `transcript` channel. Refer to [Observability](/agents/runtime/operations/observability/#chat-recovery-events).
+The same recovery events are available through `agents/observability` on the `chat` channel; transcript repairs are emitted on the `transcript` channel. Refer to [Diagnostics channels](/agents/runtime/operations/observability/diagnostics-channels/#chat-recovery-events).
 
 ## onChatRecovery
 
@@ -232,7 +232,7 @@ export class MyAgent extends Think<Env> {
 
 </TypeScriptExample>
 
-Use either layer alone, or both together: the proactive guard avoids most overflows, and the reactive backstop catches any that still slip through (for example, a turn that starts already over budget, or a single tool result so large that compaction cannot help — in which case it terminalizes cleanly). Both apply to every turn entry path (WebSocket, sub-agent `chat()`, and programmatic `saveMessages()` / `submitMessages()`), and both emit a `chat:context:compacted` [observability event](/agents/runtime/operations/observability/#chat-context-events).
+Use either layer alone, or both together: the proactive guard avoids most overflows, and the reactive backstop catches any that still slip through (for example, a turn that starts already over budget, or a single tool result so large that compaction cannot help — in which case it terminalizes cleanly). Both apply to every turn entry path (WebSocket, sub-agent `chat()`, and programmatic `saveMessages()` / `submitMessages()`), and both emit a `chat:context:compacted` [diagnostics channel event](/agents/runtime/operations/observability/diagnostics-channels/#chat-context-events).
 
 :::note
 A no-op compaction cannot rescue an over-budget turn, so recovery is only as effective as your compaction configuration. For tool-heavy histories, configure a `tokenCounter` on `compactAfter()` (refer to [Sessions](/agents/runtime/lifecycle/sessions/#auto-compaction)).

src/content/docs/agents/runtime/agents-api.mdx

@@ -85,28 +85,29 @@ flowchart TD
 
 ## Server-side API reference
 
-| Feature               | Methods                                                                                          | Documentation                                                         |
-| --------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
-| **State**             | `setState()`, `onStateChanged()`, `initialState`                                                 | [Store and sync state](/agents/runtime/lifecycle/state/)              |
-| **Callable methods**  | `@callable()` decorator                                                                          | [Callable methods](/agents/runtime/lifecycle/callable-methods/)       |
-| **Scheduling**        | `schedule()`, `scheduleEvery()`, `getScheduleById()`, `listSchedules()`                          | [Schedule tasks](/agents/runtime/execution/schedule-tasks/)           |
-| **Durable execution** | `runFiber()`, `startFiber()`, `stash()`, `onFiberRecovered()`, `keepAlive()`, `keepAliveWhile()` | [Durable execution](/agents/runtime/execution/durable-execution/)     |
-| **Queue**             | `queue()`, `dequeue()`, `dequeueAll()`, `getQueue()`                                             | [Queue tasks](/agents/runtime/execution/queue-tasks/)                 |
-| **WebSockets**        | `onConnect()`, `onMessage()`, `onClose()`, `broadcast()`                                         | [WebSockets](/agents/runtime/communication/websockets/)               |
-| **HTTP/SSE**          | `onRequest()`                                                                                    | [HTTP and SSE](/agents/runtime/communication/http-sse/)               |
-| **Email**             | `onEmail()`, `replyToEmail()`                                                                    | [Email routing](/agents/communication-channels/email/)                |
-| **Workflows**         | `runWorkflow()`, `waitForApproval()`                                                             | [Run Workflows](/agents/runtime/execution/run-workflows/)             |
-| **MCP Client**        | `addMcpServer()`, `removeMcpServer()`, `getMcpServers()`                                         | [MCP Client API](/agents/model-context-protocol/apis/client-api/)     |
-| **AI Models**         | Workers AI, OpenAI, Anthropic bindings                                                           | [Using AI models](/agents/runtime/operations/using-ai-models/)        |
-| **Protocol messages** | `shouldSendProtocolMessages()`, `isConnectionProtocolEnabled()`                                  | [Protocol messages](/agents/runtime/communication/protocol-messages/) |
-| **Context**           | `getCurrentAgent()`                                                                              | [getCurrentAgent()](/agents/runtime/lifecycle/get-current-agent/)     |
-| **Observability**     | `subscribe()`, diagnostics channels, Tail Workers                                                | [Observability](/agents/runtime/operations/observability/)            |
-| **Sub-agents**        | `subAgent()`, `abortSubAgent()`, `deleteSubAgent()`                                              | [Sub-agents](/agents/runtime/execution/sub-agents/)                   |
-| **Agents as tools**   | `runAgentTool()`, `clearAgentToolRuns()`, `hasAgentToolRun()`                                    | [Agents as tools](/agents/runtime/execution/agent-tools/)             |
-| **Agent Skills**      | `skills` registry, bundled skill sources, script runners                                         | [Agent Skills](/agents/runtime/execution/agent-skills/)               |
-| **Sessions**          | `Session.create()`, context blocks, compaction, search                                           | [Sessions](/agents/runtime/lifecycle/sessions/)                       |
-| **Think**             | `Think` base class, workspace tools, lifecycle hooks, extensions                                 | [Think](/agents/harnesses/think/)                                     |
-| **Chat SDK**          | `createChatSdkState()`, `ChatSdkStateAgent`                                                      | [Chat SDK](/agents/runtime/communication/chat-sdk/)                   |
+| Feature                  | Methods                                                                                          | Documentation                                                                          |
+| ------------------------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| **State**                | `setState()`, `onStateChanged()`, `initialState`                                                 | [Store and sync state](/agents/runtime/lifecycle/state/)                               |
+| **Callable methods**     | `@callable()` decorator                                                                          | [Callable methods](/agents/runtime/lifecycle/callable-methods/)                        |
+| **Scheduling**           | `schedule()`, `scheduleEvery()`, `getScheduleById()`, `listSchedules()`                          | [Schedule tasks](/agents/runtime/execution/schedule-tasks/)                            |
+| **Durable execution**    | `runFiber()`, `startFiber()`, `stash()`, `onFiberRecovered()`, `keepAlive()`, `keepAliveWhile()` | [Durable execution](/agents/runtime/execution/durable-execution/)                      |
+| **Queue**                | `queue()`, `dequeue()`, `dequeueAll()`, `getQueue()`                                             | [Queue tasks](/agents/runtime/execution/queue-tasks/)                                  |
+| **WebSockets**           | `onConnect()`, `onMessage()`, `onClose()`, `broadcast()`                                         | [WebSockets](/agents/runtime/communication/websockets/)                                |
+| **HTTP/SSE**             | `onRequest()`                                                                                    | [HTTP and SSE](/agents/runtime/communication/http-sse/)                                |
+| **Email**                | `onEmail()`, `replyToEmail()`                                                                    | [Email routing](/agents/communication-channels/email/)                                 |
+| **Workflows**            | `runWorkflow()`, `waitForApproval()`                                                             | [Run Workflows](/agents/runtime/execution/run-workflows/)                              |
+| **MCP Client**           | `addMcpServer()`, `removeMcpServer()`, `getMcpServers()`                                         | [MCP Client API](/agents/model-context-protocol/apis/client-api/)                      |
+| **AI Models**            | Workers AI, OpenAI, Anthropic bindings                                                           | [Using AI models](/agents/runtime/operations/using-ai-models/)                         |
+| **Protocol messages**    | `shouldSendProtocolMessages()`, `isConnectionProtocolEnabled()`                                  | [Protocol messages](/agents/runtime/communication/protocol-messages/)                  |
+| **Context**              | `getCurrentAgent()`                                                                              | [getCurrentAgent()](/agents/runtime/lifecycle/get-current-agent/)                      |
+| **Tracing**              | `wrapAISDK()`                                                                                    | [Tracing](/agents/runtime/operations/observability/tracing/)                           |
+| **Diagnostics channels** | `subscribe()`, diagnostics channels                                                              | [Diagnostics channels](/agents/runtime/operations/observability/diagnostics-channels/) |
+| **Sub-agents**           | `subAgent()`, `abortSubAgent()`, `deleteSubAgent()`                                              | [Sub-agents](/agents/runtime/execution/sub-agents/)                                    |
+| **Agents as tools**      | `runAgentTool()`, `clearAgentToolRuns()`, `hasAgentToolRun()`                                    | [Agents as tools](/agents/runtime/execution/agent-tools/)                              |
+| **Agent Skills**         | `skills` registry, bundled skill sources, script runners                                         | [Agent Skills](/agents/runtime/execution/agent-skills/)                                |
+| **Sessions**             | `Session.create()`, context blocks, compaction, search                                           | [Sessions](/agents/runtime/lifecycle/sessions/)                                        |
+| **Think**                | `Think` base class, workspace tools, lifecycle hooks, extensions                                 | [Think](/agents/harnesses/think/)                                                      |
+| **Chat SDK**             | `createChatSdkState()`, `ChatSdkStateAgent`                                                      | [Chat SDK](/agents/runtime/communication/chat-sdk/)                                    |
 
 ## SQL API
 

src/content/docs/agents/runtime/operations/observability.mdx → src/content/docs/agents/runtime/operations/observability/diagnostics-channels.mdx

@@ -1,16 +1,16 @@
 ---
-title: Observability
-description: Subscribe to structured Agent events for RPC calls, state changes, schedules, workflows, and MCP connections via diagnostics channels.
-pcx_content_type: concept
+title: Diagnostics channels
+description: Subscribe to structured agent events for RPC calls, state changes, schedules, workflows, and MCP connections.
+pcx_content_type: reference
 sidebar:
-  order: 30
+  order: 2
 products:
   - agents
 ---
 
 import { TypeScriptExample, LinkCard } from "~/components";
 
-Agents emit structured events for every significant operation — RPC calls, state changes, schedule execution, workflow transitions, MCP connections, and more. These events are published to [diagnostics channels](/workers/runtime-apis/nodejs/diagnostics-channel/) and are silent by default (zero overhead when nobody is listening).
+Agents publish structured events to [diagnostics channels](/workers/runtime-apis/nodejs/diagnostics-channel/) for every significant operation -- RPC calls, state changes, schedule execution, workflow transitions, MCP connections, and more. Publishing has zero overhead when nobody is listening.
 
 ## Event structure
 
@@ -297,6 +297,12 @@ These events track chat message lifecycle, client-side tool interactions, and Th
 
 ## Next steps
 
+<LinkCard
+	title="Tracing"
+	href="/agents/runtime/operations/observability/tracing/"
+	description="Trace model calls, tool runs, and approvals with Workers traces."
+/>
+
 <LinkCard
 	title="Configuration"
 	href="/agents/runtime/operations/configuration/"
@@ -308,9 +314,3 @@ These events track chat message lifecycle, client-side tool interactions, and Th
 	href="/workers/observability/logs/tail-workers/"
 	description="Forward diagnostics channel events to a Tail Worker for production monitoring."
 />
-
-<LinkCard
-	title="Agents API"
-	href="/agents/runtime/agents-api/"
-	description="Complete API reference for the Agents SDK."
-/>

src/content/docs/agents/runtime/operations/observability/index.mdx

@@ -0,0 +1,12 @@
+---
+title: Observability
+pcx_content_type: navigation
+sidebar:
+  order: 30
+  group:
+    hideIndex: true
+---
+
+import { DirectoryListing } from "~/components";
+
+<DirectoryListing />