agents 0.20.0 → 0.21.0

package/docs/mcp-transports.md

@@ -2,13 +2,18 @@
 
 This guide explains the different transport options for connecting to MCP servers with the Agents SDK.
 
-For a primer on MCP servers and how they are implemented in the Agents SDK with `McpAgent`, see [Creating MCP Servers](./mcp-servers.md).
+For a primer on MCP servers, see [Creating MCP Servers](./mcp-servers.md).
 
 ## Streamable HTTP Transport (Recommended)
 
-The **Streamable HTTP** transport is the recommended way to connect to MCP servers.
+The Agents SDK has two server paths:
 
-### How it works
+- Current SDK v2 servers use `createMcpHandler`, a per-request stateless Worker handler with no Durable Object or WebSocket bridge.
+- Retained SDK v1 servers use the deprecated, feature-frozen `McpAgent`, which provides sessionful transports through a Durable Object and internal WebSocket bridge.
+
+The current stateless handler also accepts stateless 2025-era Streamable HTTP requests by default. It does not expose standalone legacy SSE.
+
+### Legacy `McpAgent` architecture
 
 When a client connects to your MCP server:
 
@@ -44,13 +49,13 @@ The `serve()` method returns a Worker with a `fetch` handler that:
 
 ### Connection from clients
 
-Clients connect using the `streamable-http` transport:
+The Agents MCP client uses `"auto"` by default. It tries Streamable HTTP first and falls back to legacy SSE only when the endpoint reports that Streamable HTTP is unsupported:
 
 ```typescript
 await agent.addMcpServer("my-server", "https://your-worker.workers.dev/mcp");
 ```
 
-## Auto Transport
+## Legacy `McpAgent` Server Auto Transport
 
 The **auto** transport serves both Streamable HTTP and legacy SSE on the same endpoint. Capable clients use Streamable HTTP automatically, while older SSE-only clients continue to work.
 
@@ -60,7 +65,7 @@ export default MyMCP.serve("/mcp", { transport: "auto" });
 
 The handler distinguishes between the two protocols based on the request shape — no configuration or content negotiation is required from clients. This is useful when migrating from SSE to Streamable HTTP without breaking existing clients.
 
-## SSE Transport (Deprecated)
+## Legacy `McpAgent` SSE Transport (Deprecated)
 
 We also support the legacy **SSE (Server-Sent Events)** transport, but it is deprecated in favor of Streamable HTTP.
 
@@ -294,12 +299,13 @@ export class MyMCP extends McpAgent<Env, State> {
 
 ## Choosing a transport
 
-| Transport           | Use when                                 | Pros                                     | Cons                            |
-| ------------------- | ---------------------------------------- | ---------------------------------------- | ------------------------------- |
-| **Streamable HTTP** | External MCP servers, production apps    | Standard protocol, secure, supports auth | Slight network overhead         |
-| **Auto**            | Migrating from SSE, mixed client support | Serves both protocols on one endpoint    | Reserves `{path}/message` route |
-| **RPC**             | Internal agents                          | Fastest, simplest setup                  | No auth, Service Bindings only  |
-| **SSE**             | Legacy compatibility                     | Backwards compatible                     | Deprecated, use Streamable HTTP |
+| Transport                         | Use when                                            | Pros                                       | Cons                                   |
+| --------------------------------- | --------------------------------------------------- | ------------------------------------------ | -------------------------------------- |
+| **Streamable HTTP**               | New servers and external MCP connections            | Current standard transport; supports OAuth | Slight network overhead                |
+| **Client `auto`**                 | The remote server's HTTP transport is not known     | Tries Streamable HTTP, then legacy SSE     | May make a fallback connection attempt |
+| **Legacy `McpAgent` server auto** | An existing server must accept both HTTP transports | Serves both protocols on one endpoint      | Uses the deprecated server path        |
+| **RPC**                           | Internal agents                                     | Fastest, simplest setup                    | No auth, Service Bindings only         |
+| **SSE**                           | Legacy compatibility                                | Backwards compatible                       | Deprecated, use Streamable HTTP        |
 
 ## Examples
 

package/docs/migration-to-ai-sdk-v5.md

@@ -2,7 +2,7 @@
 
 This guide covers the changes needed when upgrading from AI SDK v4 to v5 with `@cloudflare/ai-chat`.
 
-> If you are on AI SDK v5 and upgrading to v6, see the [v6 migration guide](./migration-to-ai-sdk-v6.md) instead.
+> The current `agents` and `@cloudflare/ai-chat` packages support AI SDK v6 and v7, not v5. If an application is still on v4, apply the intermediate changes on this page and then continue through the [v6 migration guide](./migration-to-ai-sdk-v6.md). Do not install AI SDK v5 alongside the current Cloudflare packages.
 
 ## Message format: `content` to `parts`
 
@@ -71,7 +71,7 @@ chunk.type === "text-delta" && chunk.delta;
 
 ## Migration checklist
 
-1. Update dependencies: `npm update agents ai`
+1. Apply this intermediate checklist without installing v5, then continue through the [v6 migration guide](./migration-to-ai-sdk-v6.md) and install the supported package majors shown there
 2. Replace `import type { Message }` with `import type { UIMessage }`
 3. Replace `"ai/react"` imports with `"@ai-sdk/react"`
 4. Rename `parameters` to `inputSchema` in tool definitions

package/docs/migration-to-ai-sdk-v6.md

@@ -4,10 +4,14 @@ This guide covers the changes needed when upgrading from AI SDK v5 to v6 with `@
 
 ## Installation
 
+Pin the v6-compatible majors so this migration does not also install AI SDK v7:
+
 ```bash
-npm install ai@latest @ai-sdk/react@latest @ai-sdk/openai@latest
+npm install ai@^6 @ai-sdk/react@^3 @ai-sdk/openai@^3
 ```
 
+The current `agents` and `@cloudflare/ai-chat` releases support both AI SDK v6 and v7. This guide covers v6 only.
+
 ## Breaking changes
 
 ### 1. `convertToModelMessages()` is now async

package/docs/observability.md

@@ -292,9 +292,9 @@ metadata fields for applications with a different identity model. Payload
 storage is off by default. Set `storeMessages` and/or `storeTools` on the Think
 agent to opt in; these are wrapper settings, not span attributes.
 
-### AI SDK v6
+### AI SDK v6 and v7
 
-Wrap the SDK namespace:
+Wrap the SDK namespace and call the wrapped functions:
 
 ```ts
 import * as ai from "ai";
@@ -303,14 +303,17 @@ import { wrapAISDK } from "agents/observability/ai";
 const { generateText, streamText } = wrapAISDK(ai);
 ```
 
-`wrapAISDK` instruments `generateText`, `streamText`, `generateObject`, and
-`streamObject`. Span names use `{operation} {target}` and fall back to the bare
-operation past 64 UTF-8 bytes; the full target remains on its semantic
-attribute. A model object is wrapped with the SDK's `wrapLanguageModel` helper,
-so provider work is a `chat {model}` child of the operation span. Tool
-execution is wrapped as `execute_tool {tool}`. AI SDK v6 approval lifecycle
-segments appear as bounded `tool_approval {tool}` children of an
-`execute_tool {tool}` span, correlated by `gen_ai.tool.call.id` and carrying
+`wrapAISDK` supports AI SDK v6 and v7. It instruments `generateText`,
+`streamText`, `generateObject`, and `streamObject`. You do not need to register a
+telemetry integration for Agents tracing on AI SDK v7.
+
+Span names use `{operation} {target}` and fall back to the bare operation past
+64 UTF-8 bytes; the full target remains on its semantic attribute. A model
+object is wrapped with the SDK's `wrapLanguageModel` helper, so provider work is
+a `chat {model}` child of the `invoke_agent {agent}` operation span. Tool
+execution is wrapped as `execute_tool {tool}`. Approval lifecycle segments
+appear as bounded `tool_approval {tool}` children of an `execute_tool {tool}`
+span, correlated by `gen_ai.tool.call.id` and carrying
 `cloudflare.agents.tool.approval.state` (`requested`, `approved`, or `denied`).
 They never remain open while waiting for a human across invocations. Stream
 spans close on completion, cancellation, an in-band error, or early consumer
@@ -329,46 +332,10 @@ const traced = wrapAISDK(ai, {
 });
 ```
 
-### AI SDK v7
-
-AI SDK v7 ships a first-class telemetry lifecycle. Register the adapter once and
-every `generateText`, `streamText`, `generateObject`, and `streamObject` call is
-instrumented:
-
-```ts
-import { registerTelemetry } from "ai";
-import { createAISDKTelemetry } from "agents/observability/ai";
-
-registerTelemetry(
-  createAISDKTelemetry({ storeMessages: true, storeTools: true })
-);
-```
-
-Or scope it to a single call through `experimental_telemetry`:
-
-```ts
-import { createAISDKTelemetry } from "agents/observability/ai";
-
-await generateText({
-  model,
-  prompt: "...",
-  experimental_telemetry: {
-    integrations: [createAISDKTelemetry()]
-  }
-});
-```
-
-The v7 adapter uses `cloudflare.agents.call.id` to correlate operation, model,
-and tool spans. Its execution hooks keep provider work under the `chat` span and
-nested work performed by a tool under the `execute_tool` span. It handles both
-`onEnd` and `onAbort` terminal paths. `wrapAISDK` and `createAISDKTelemetry`
-project into the same span schema, so the two SDK versions are dashboard-
-compatible.
-
 When a gateway-backed provider exposes its AI Gateway log ID through response
 headers, provider metadata, or the Workers AI binding, the corresponding
 `chat` span includes `cloudflare.ai_gateway.log.id`. The attribute is omitted
-when no actual response exposes an ID; the adapter does not infer one or make an
+when no actual response exposes an ID; the wrapper does not infer one or make an
 extra request.
 
 ### Identity
@@ -445,13 +412,13 @@ await generateText({
 | `gen_ai.usage.cache_creation.input_tokens`, `gen_ai.usage.cache_read.input_tokens` | Provider cache usage when reported                                                           |
 | `gen_ai.usage.reasoning.output_tokens`                                             | Reasoning output usage when reported                                                         |
 | `gen_ai.tool.name`, `gen_ai.tool.type`, `gen_ai.tool.call.id`                      | Tool identity; call ID also correlates approval lifecycle segments                           |
-| `cloudflare.agents.tool.approval.state`                                            | AI SDK v6 approval lifecycle segment: `requested`, `approved`, or `denied`                   |
+| `cloudflare.agents.tool.approval.state`                                            | Approval lifecycle segment: `requested`, `approved`, or `denied`                             |
 | `gen_ai.input.messages`, `gen_ai.output.messages`                                  | Opt-in OTel-schema model messages on `chat`, including tool parts and output finish reasons  |
 | `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result`                            | Opt-in tool arguments/results on `execute_tool`                                              |
 | `user.id`                                                                          | Explicit v6 metadata key `user.id`                                                           |
 | `error.type`                                                                       | Low-cardinality error class; raw error messages are never recorded                           |
 
-The adapter also emits a small vendor namespace where no standard equivalent
+The wrapper also emits a small vendor namespace where no standard equivalent
 exists:
 
 | Attribute                                                                               | Meaning                                                                 |
@@ -459,28 +426,27 @@ exists:
 | `cloudflare.ai_gateway.log.id`                                                          | AI Gateway log reference on `chat`, when exposed by the actual response |
 | `cloudflare.agents.integration.name`                                                    | Instrumentation source (`ai-sdk`)                                       |
 | `cloudflare.agents.operation.name`                                                      | Original SDK operation (`streamText`, `doStream`, `tool.execute`, etc.) |
-| `cloudflare.agents.call.id`                                                             | AI SDK v7 callback correlation ID                                       |
 | `cloudflare.agents.response.finish_reason`                                              | One finish reason as a scalar                                           |
 | `cloudflare.agents.tool.count`                                                          | Precomputed tool-call count for dashboards                              |
 | `cloudflare.agents.usage.total_tokens`                                                  | Provider total, or input plus output when both are known                |
 | `cloudflare.agents.runtime_context.{key}`                                               | Explicitly included scalar runtime context                              |
-| `cloudflare.agents.tool_context.{tool}.{key}`                                           | Explicitly included scalar context on the executed tool span            |
 | `cloudflare.agents.metadata.{key}`                                                      | Other scalar v6 telemetry metadata                                      |
-| `cloudflare.agents.turn.{request_id,trigger,admission,channel,continuation,generation}` | Think turn context                                                      |
+| `cloudflare.agents.turn.{request_id,trigger,admission,channel,continuation,generation}` | Think turn context, from v6 metadata or v7 runtime context              |
 | `cloudflare.agents.canceled`                                                            | Recognized cancellation, not a failure                                  |
+| `cloudflare.agents.span.truncated`                                                      | Span closed by its invocation ending before the work finished           |
 
 `gen_ai.response.finish_reasons` and `gen_ai.request.stop_sequences` are arrays
 in OTel. Workers' custom `Span.setAttribute` currently accepts only a string,
-number, or boolean, so the adapter omits those attributes rather than placing
+number, or boolean, so the wrapper omits those attributes rather than placing
 JSON text under an array-typed key. Similarly, span status is state rather than
-an attribute: failures emit `error.type`, but the adapter does not invent an
+an attribute: failures emit `error.type`, but the wrapper does not invent an
 `otel.status_code` attribute when Workers exposes no custom-span status setter.
 
 ### Context and safety
 
 Payload storage is explicit and off by default. `storeMessages` writes only
 `gen_ai.input.messages` / `gen_ai.output.messages` on `chat`; when the message
-attribute exceeds its budget, the adapter repeatedly drops the oldest
+attribute exceeds its budget, the wrapper repeatedly drops the oldest
 unprotected message (index 2), preserving the first two messages and newest
 tail. `storeTools` writes only `gen_ai.tool.call.arguments` /
 `gen_ai.tool.call.result` on `execute_tool`. The flags themselves are never
@@ -488,7 +454,7 @@ written to telemetry metadata or spans.
 
 System instructions that the AI SDK presents to the model as a system-role chat
 message remain in `gen_ai.input.messages`, which OTel explicitly permits for
-instructions that are part of chat history. The adapter does not separately
+instructions that are part of chat history. The wrapper does not separately
 copy the raw `system` parameter into `gen_ai.system_instructions`. Schemas,
 request headers, provider options, and raw error messages are never recorded.
 The optional AI Gateway reference is a bounded opaque log ID; response headers
@@ -513,27 +479,18 @@ await traced.generateText({
 });
 ```
 
-For v7, the AI SDK filters runtime and per-tool context before the adapter sees
-it. Its allowlists are boolean maps, not arrays:
+For v7, put application context in `runtimeContext` and select telemetry-visible
+keys with the AI SDK's boolean-map allowlist:
 
 ```ts
 await generateText({
   model,
   prompt: "Will I need an umbrella?",
   runtimeContext: { requestId: "req-123", tenantId: "tenant-42" },
-  toolsContext: {
-    weather: { defaultUnit: "celsius", cacheHit: true }
-  },
   telemetry: {
     includeRuntimeContext: {
       requestId: true,
       tenantId: true
-    },
-    includeToolsContext: {
-      weather: {
-        defaultUnit: true,
-        cacheHit: true
-      }
     }
   }
 });

package/docs/routing.md

@@ -96,6 +96,33 @@ export default {
 
 ---
 
+## Building Agent URLs
+
+Use `buildAgentPath()` when a server, external provider, or client needs the canonical pathname for a known root-first Agent identity. It handles the top-level route and every nested `/sub/...` hop:
+
+```typescript
+import { buildAgentPath, buildAgentUrl } from "agents";
+
+const address = [
+  { className: "Inbox", name: userId },
+  { className: "Chat", name: chatId }
+];
+
+buildAgentPath(address, { leafPath: "/callbacks/job" });
+// /agents/inbox/{userId}/sub/chat/{chatId}/callbacks/job
+
+buildAgentUrl("https://app.example.com", address, {
+  leafPath: "/callbacks/job"
+});
+// URL("https://app.example.com/agents/inbox/...")
+```
+
+Inside an Agent, `this.selfPath` has the required root-first shape. If the root Durable Object binding name differs from its class name, pass that binding name as `rootBinding`. The pathname works for both HTTP and WebSocket traffic. For a custom top-level prefix, pass the same `prefix` to `buildAgentPath()` and `routeAgentRequest()`.
+
+See [Sub-agents](./sub-agents.md#direct-http-and-websocket-urls) for callbacks, webhooks, custom routing, and name-encoding details.
+
+---
+
 ## Instance Naming Patterns
 
 The instance name (the last part of the URL) determines which agent instance handles the request. Each unique name gets its own isolated agent with its own state.

package/docs/sub-agents.md

@@ -273,7 +273,52 @@ const chat = useAgent({
 
 Every other `useAgent` feature works as usual: `state` sync, `stub.method()` calls, `@callable` RPCs, `useAgentChat` on top of the returned socket.
 
-### Direct HTTP / custom routing
+### Direct HTTP and WebSocket URLs
+
+Use `buildAgentPath()` to turn a root-first Agent identity into the canonical URL pathname used by both HTTP requests and WebSocket connections:
+
+```typescript
+import { buildAgentPath } from "agents";
+
+const path = buildAgentPath(
+  [
+    { className: "Inbox", name: userId },
+    { className: "Chat", name: chatId }
+  ],
+  { leafPath: "/callbacks/job" }
+);
+
+// /agents/inbox/{userId}/sub/chat/{chatId}/callbacks/job
+```
+
+Inside an Agent, pass `this.selfPath` directly. If the root Durable Object binding name differs from its class name, also pass `rootBinding` in the options. `buildAgentUrl()` adds a public origin, which is useful when registering callbacks, webhooks, approval URLs, or asynchronous job-completion URLs with an external system:
+
+```typescript
+import { buildAgentUrl } from "agents";
+
+export class Chat extends Agent<Env> {
+  callbackUrl() {
+    return buildAgentUrl(this.env.PUBLIC_ORIGIN, this.selfPath, {
+      leafPath: "/callbacks/job"
+    });
+  }
+
+  override async onRequest(request: Request) {
+    if (new URL(request.url).pathname === "/callbacks/job") {
+      return this.handleJobCallback(request);
+    }
+    return new Response("Not found", { status: 404 });
+  }
+}
+```
+
+The Worker must pass the incoming request to `routeAgentRequest()`. Each ancestor's `onBeforeSubAgent` hook runs before the destination receives the request. For a sub-agent destination, the nested `/sub/...` routing segments are removed during forwarding, so its pathname is the `leafPath` suffix.
+
+`buildAgentUrl()` accepts an HTTP(S) or WS(S) origin without a pathname, query, fragment, or credentials. Set callback query parameters through the returned URL's `searchParams`. If you use a custom routing prefix, pass the same value to both `buildAgentPath()` and `routeAgentRequest()`.
+
+Root Agent names follow PartyServer's existing raw pathname-segment behavior and must already be externally routable. The `sub` segment is reserved in routing prefixes, class and binding names, and root Agent names. Descendant names are URL-encoded by the helper, so names containing spaces, Unicode, `/`, or URL-reserved characters round-trip safely.
+
+### Custom routing
 
 For fetch handlers that do their own top-level URL parsing, use `routeSubAgentRequest` to dispatch a request into a sub-agent from an already-resolved parent stub:
 
@@ -293,7 +338,7 @@ export default {
 };
 ```
 
-`fromPath` takes the sub-agent tail (something like `/sub/chat/chat-abc/...`). The helper parses it, runs the parent's `onBeforeSubAgent` hook, and forwards into the facet.
+`fromPath` takes any pathname containing the sub-agent tail (something like `/sub/chat/chat-abc/...`). When the destination is already represented as a root-first Agent path, pass the result of `buildAgentPath()` directly. The helper parses the first child hop, runs the parent's `onBeforeSubAgent` hook, and forwards into the facet.
 
 ### External typed RPC