agents 0.16.2 → 0.17.0

package/docs/mcp-transports.md

@@ -0,0 +1,308 @@
+# MCP Transports
+
+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).
+
+## Streamable HTTP Transport (Recommended)
+
+The **Streamable HTTP** transport is the recommended way to connect to MCP servers.
+
+### How it works
+
+When a client connects to your MCP server:
+
+1. The client makes an HTTP request to your Worker with a JSON-RPC message in the body
+2. Your Worker upgrades the connection to a WebSocket
+3. The WebSocket connects to your `McpAgent` Durable Object which manages connection state
+4. JSON-RPC messages flow bidirectionally over the WebSocket
+5. Your Worker streams responses back to the client using Server-Sent Events (SSE)
+
+This is all handled automatically by the `McpAgent.serve()` method:
+
+```typescript
+import { McpAgent } from "agents/mcp";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export class MyMCP extends McpAgent {
+  server = new McpServer({ name: "Demo", version: "1.0.0" });
+
+  async init() {
+    // Define your tools, resources, prompts
+  }
+}
+
+// Serve with Streamable HTTP transport
+export default MyMCP.serve("/mcp");
+```
+
+The `serve()` method returns a Worker with a `fetch` handler that:
+
+- Handles CORS preflight requests
+- Manages WebSocket upgrades
+- Routes messages to your Durable Object
+
+### Connection from clients
+
+Clients connect using the `streamable-http` transport:
+
+```typescript
+await agent.addMcpServer("my-server", "https://your-worker.workers.dev/mcp");
+```
+
+## 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.
+
+```typescript
+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)
+
+We also support the legacy **SSE (Server-Sent Events)** transport, but it is deprecated in favor of Streamable HTTP.
+
+If you need SSE transport for compatibility:
+
+```typescript
+// Server
+export default MyMCP.serveSSE("/sse");
+
+// Client
+await agent.addMcpServer("my-server", url);
+```
+
+## RPC Transport (Experimental)
+
+The **RPC transport** is a custom transport designed for internal applications where your MCP server and agent are both running on Cloudflare. They can even run in the same Worker! It sends JSON-RPC messages directly over Cloudflare's RPC bindings without going over the public internet.
+
+### Why use RPC transport?
+
+- **Faster**: No network overhead - direct function calls
+- **Simpler**: No HTTP endpoints, no connection management
+- **Internal only**: Perfect for agents calling MCP servers within the same Worker
+
+**Note**: RPC transport does not support authentication. Use HTTP/SSE for external connections that require OAuth.
+
+### Connecting an Agent to an McpAgent via RPC
+
+The RPC transport uses Durable Object bindings to connect your `Agent` (MCP client) directly to your `McpAgent` (MCP server).
+
+#### Step 1: Define your MCP server
+
+Create your `McpAgent` with the tools you want to expose:
+
+```typescript
+import { McpAgent } from "agents/mcp";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+type State = { counter: number };
+
+export class MyMCP extends McpAgent<Env, State> {
+  server = new McpServer({ name: "MyMCP", version: "1.0.0" });
+  initialState: State = { counter: 0 };
+
+  async init() {
+    this.server.tool(
+      "add",
+      "Add to the counter",
+      { amount: z.number() },
+      async ({ amount }) => {
+        this.setState({ counter: this.state.counter + amount });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Added ${amount}, total is now ${this.state.counter}`
+            }
+          ]
+        };
+      }
+    );
+  }
+}
+```
+
+#### Step 2: Connect your Agent to the MCP server
+
+In your `Agent`, call `addMcpServer()` with the Durable Object binding in `onStart()`:
+
+```typescript
+import { AIChatAgent } from "agents/ai-chat-agent";
+
+export class Chat extends AIChatAgent<Env> {
+  async onStart(): Promise<void> {
+    // Pass the DO namespace binding directly
+    await this.addMcpServer("my-mcp", this.env.MyMCP);
+  }
+
+  async onChatMessage(onFinish) {
+    const allTools = this.mcp.getAITools();
+
+    const result = streamText({
+      model,
+      tools: allTools
+      // ...
+    });
+
+    return createUIMessageStreamResponse({ stream: result });
+  }
+}
+```
+
+RPC connections are automatically restored after Durable Object hibernation, just like HTTP connections. The binding name and props are persisted to storage so the connection can be re-established without any extra code.
+
+**Deduplication:** For RPC transport, if `addMcpServer` is called with a name that already has an active connection, the existing connection is returned instead of creating a duplicate. For HTTP transport, deduplication matches on both server name and URL (see [MCP Client API](./mcp-client.md) for details). This makes it safe to call `addMcpServer` in `onStart()` without worrying about creating multiple connections on restart.
+
+#### Step 3: Configure Durable Object bindings
+
+In your `wrangler.jsonc`, define bindings for both Durable Objects:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      { "name": "Chat", "class_name": "Chat" },
+      { "name": "MyMCP", "class_name": "MyMCP" }
+    ]
+  },
+  "migrations": [
+    {
+      "new_sqlite_classes": ["MyMCP", "Chat"],
+      "tag": "v1"
+    }
+  ]
+}
+```
+
+#### Step 4: Set up your Worker fetch handler
+
+Route requests to your Chat agent:
+
+```typescript
+import { routeAgentRequest } from "agents";
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const url = new URL(request.url);
+
+    // Optionally expose the MCP server via HTTP as well
+    if (url.pathname.startsWith("/mcp")) {
+      return MyMCP.serve("/mcp").fetch(request, env, ctx);
+    }
+
+    const response = await routeAgentRequest(request, env);
+    if (response) return response;
+
+    return new Response("Not found", { status: 404 });
+  }
+};
+```
+
+### Passing props from client to server
+
+Since RPC transport does not have an OAuth flow, you can pass user context (like userId, role, etc.) directly as props:
+
+```typescript
+await this.addMcpServer("my-mcp", this.env.MyMCP, {
+  props: { userId: "user-123", role: "admin" }
+});
+```
+
+Your `McpAgent` can then access these props:
+
+```typescript
+export class MyMCP extends McpAgent<
+  Env,
+  State,
+  { userId?: string; role?: string }
+> {
+  async init() {
+    this.server.tool("whoami", "Get current user info", {}, async () => {
+      const userId = this.props?.userId || "anonymous";
+      const role = this.props?.role || "guest";
+
+      return {
+        content: [{ type: "text", text: `User ID: ${userId}, Role: ${role}` }]
+      };
+    });
+  }
+}
+```
+
+The props are:
+
+- **Type-safe**: TypeScript extracts the Props type from your McpAgent generic
+- **Persistent**: Stored in Durable Object storage via `updateProps()`
+- **Available immediately**: Set before any tool calls are made
+
+This is useful for:
+
+- User authentication context
+- Tenant/organization IDs
+- Feature flags or permissions
+- Any per-connection configuration
+
+### How RPC transport works under the hood
+
+When you call `addMcpServer()` with a Durable Object binding, the SDK:
+
+1. Creates an `RPCClientTransport` that wraps the DO stub
+2. Calls `handleMcpMessage()` on the `McpAgent` for each JSON-RPC message
+3. The `McpAgent` routes messages through its `RPCServerTransport` to the MCP server
+4. Responses flow back synchronously through the RPC call
+
+This happens entirely within your Worker's execution context using Cloudflare's RPC mechanism - no HTTP, no WebSockets, no public internet.
+
+The RPC transport fully supports:
+
+- JSON-RPC 2.0 validation (via the MCP SDK's schema)
+- Batch requests
+- Notifications (messages without `id` field)
+- Automatic reconnection after Durable Object hibernation (when called from `onStart()`)
+
+### Configuring RPC Transport Server Timeout
+
+The RPC transport has a configurable timeout for waiting for tool responses. By default, the server will wait **60 seconds** for a tool handler to respond. You can customize this by overriding `getRpcTransportOptions()` in your `McpAgent`:
+
+```typescript
+export class MyMCP extends McpAgent<Env, State> {
+  server = new McpServer({ name: "MyMCP", version: "1.0.0" });
+
+  protected getRpcTransportOptions() {
+    return { timeout: 120000 }; // 2 minutes
+  }
+
+  async init() {
+    this.server.tool(
+      "long-running-task",
+      "A tool that takes a while",
+      { input: z.string() },
+      async ({ input }) => {
+        await longRunningOperation(input);
+        return {
+          content: [{ type: "text", text: "Task completed" }]
+        };
+      }
+    );
+  }
+}
+```
+
+## 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 |
+
+## Examples
+
+- **Streamable HTTP**: See [`examples/mcp`](https://github.com/cloudflare/agents/tree/main/examples/mcp)
+- **RPC Transport**: See [`examples/mcp-rpc-transport`](https://github.com/cloudflare/agents/tree/main/examples/mcp-rpc-transport)
+- **MCP Client**: See [`examples/mcp-client`](https://github.com/cloudflare/agents/tree/main/examples/mcp-client)

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

@@ -0,0 +1,96 @@
+# Migrating from AI SDK v4 to v5
+
+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.
+
+## Message format: `content` to `parts`
+
+The biggest change. Messages now use a `parts` array instead of a `content` string:
+
+```typescript
+// v4
+const message = { id: "1", role: "user", content: "Hello" };
+
+// v5
+const message = {
+  id: "1",
+  role: "user",
+  parts: [{ type: "text", text: "Hello" }]
+};
+```
+
+**You do not need to migrate stored messages manually.** `AIChatAgent` automatically transforms legacy messages on load via `autoTransformMessages()`. This handles v4 `content` strings, tool invocations, reasoning parts, file data, and malformed formats.
+
+## Import changes
+
+```typescript
+// v4
+import type { Message } from "ai";
+import { useChat } from "ai/react";
+
+// v5
+import type { UIMessage } from "ai";
+import { useChat } from "@ai-sdk/react";
+```
+
+## Tool definitions: `parameters` to `inputSchema`
+
+```typescript
+// v4
+const tools = {
+  weather: {
+    description: "Get weather",
+    parameters: z.object({ city: z.string() }),
+    execute: async ({ city }) => fetchWeather(city)
+  }
+};
+
+// v5
+const tools = {
+  weather: {
+    description: "Get weather",
+    inputSchema: z.object({ city: z.string() }),
+    execute: async ({ city }) => fetchWeather(city)
+  }
+};
+```
+
+## Streaming events
+
+v5 adds `text-start` and `text-end` events around text deltas, and renames `textDelta` to `delta`:
+
+```typescript
+// v4
+chunk.type === "text-delta" && chunk.textDelta;
+
+// v5
+chunk.type === "text-delta" && chunk.delta;
+// Plus new: "text-start" and "text-end" events
+```
+
+## Migration checklist
+
+1. Update dependencies: `npm update agents ai`
+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
+5. Run `npm run typecheck` and fix any remaining type errors
+6. Test your application -- legacy stored messages are migrated automatically
+
+## Migration utilities (deprecated)
+
+These are available but rarely needed since migration is automatic:
+
+```typescript
+import {
+  autoTransformMessages, // Used internally by AIChatAgent
+  migrateMessagesToUIFormat, // Deprecated -- use autoTransformMessages
+  analyzeCorruption // Deprecated -- debugging only
+} from "@cloudflare/ai-chat/ai-chat-v5-migration";
+```
+
+## Further reading
+
+- [Official AI SDK v5 migration guide](https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0)
+- [v6 migration guide](./migration-to-ai-sdk-v6.md) (if upgrading further)

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

@@ -0,0 +1,163 @@
+# Migrating from AI SDK v5 to v6
+
+This guide covers the changes needed when upgrading from AI SDK v5 to v6 with `@cloudflare/ai-chat`.
+
+## Installation
+
+```bash
+npm install ai@latest @ai-sdk/react@latest @ai-sdk/openai@latest
+```
+
+## Breaking changes
+
+### 1. `convertToModelMessages()` is now async
+
+Add `await` to all calls:
+
+```typescript
+// v5
+const result = streamText({
+  messages: convertToModelMessages(this.messages),
+  model: openai("gpt-4o")
+});
+
+// v6
+const result = streamText({
+  messages: await convertToModelMessages(this.messages),
+  model: openai("gpt-4o")
+});
+```
+
+### 2. `CoreMessage` removed
+
+Replace `CoreMessage` with `ModelMessage` and `convertToCoreMessages()` with `convertToModelMessages()`:
+
+```typescript
+// v5
+import { convertToCoreMessages, type CoreMessage } from "ai";
+
+// v6
+import { convertToModelMessages, type ModelMessage } from "ai";
+```
+
+### 3. Tool pattern: server-side tools (recommended)
+
+v6 introduces `needsApproval` and the `onToolCall` callback. For most apps, define tools on the server with `tool()` from `"ai"` for full Zod type safety:
+
+**Before (v5):**
+
+```typescript
+// Client defined tools with AITool type
+useAgentChat({
+  agent,
+  tools: clientTools,
+  experimental_automaticToolResolution: true,
+  toolsRequiringConfirmation: ["askConfirmation"]
+});
+```
+
+**After (v6):**
+
+```typescript
+// Server: all tools defined here
+const tools = {
+  getWeather: tool({
+    description: "Get weather",
+    inputSchema: z.object({ city: z.string() }),
+    execute: async ({ city }) => fetchWeather(city)
+  }),
+  getLocation: tool({
+    description: "Get user location",
+    inputSchema: z.object({})
+    // No execute -- client handles via onToolCall
+  }),
+  processPayment: tool({
+    description: "Process payment",
+    inputSchema: z.object({ amount: z.number() }),
+    needsApproval: async ({ amount }) => amount > 100,
+    execute: async ({ amount }) => charge(amount)
+  })
+};
+
+// Client: handle tools via callbacks
+useAgentChat({
+  agent,
+  onToolCall: async ({ toolCall, addToolOutput }) => {
+    if (toolCall.toolName === "getLocation") {
+      const pos = await getPosition();
+      addToolOutput({
+        toolCallId: toolCall.toolCallId,
+        output: { lat: pos.coords.latitude, lng: pos.coords.longitude }
+      });
+    }
+  }
+});
+```
+
+**Dynamic client tools (SDK/platform pattern):**
+
+If you are building an SDK or platform where tools are defined dynamically by the embedding application at runtime, the `tools` option on `useAgentChat` and `createToolsFromClientSchemas()` on the server are still fully supported:
+
+```typescript
+// Server: accept whatever tools the client sends
+const tools = {
+  ...createToolsFromClientSchemas(options.clientTools),
+  ...serverTools
+};
+
+// Client: register tools dynamically
+useAgentChat({
+  agent,
+  tools: dynamicTools,
+  onToolCall: async ({ toolCall, addToolOutput }) => {
+    const tool = dynamicTools[toolCall.toolName];
+    if (tool?.execute) {
+      const output = await tool.execute(toolCall.input);
+      addToolOutput({ toolCallId: toolCall.toolCallId, output });
+    }
+  }
+});
+```
+
+### 4. `generateObject` mode option removed
+
+Remove `mode: "json"` or similar from `generateObject` calls.
+
+### 5. `isToolUIPart` and `getToolName` now include dynamic tools
+
+In v6, these check both static and dynamic tool parts. For the old behavior, use `isStaticToolUIPart` and `getStaticToolName`. Most users do not need to change anything.
+
+## Deprecated APIs
+
+| Deprecated                             | Replacement                                               |
+| -------------------------------------- | --------------------------------------------------------- |
+| `toolsRequiringConfirmation`           | [`needsApproval`](./human-in-the-loop.md) on server tools |
+| `experimental_automaticToolResolution` | [`onToolCall`](./client-tools-continuation.md) callback   |
+| `addToolResult()`                      | `addToolOutput()` or `addToolApprovalResponse()`          |
+
+**Not deprecated:** `AITool`, `createToolsFromClientSchemas()`, `extractClientToolSchemas()`, and the `tools` option on `useAgentChat` are supported for SDK/platform use cases where tools are defined dynamically at runtime.
+
+## Migration checklist
+
+**Packages:**
+
+- `ai` to `^6.0.0`
+- `@ai-sdk/react` to `^3.0.0`
+- `@ai-sdk/openai` (and other providers) to `^3.0.0`
+
+**Code changes:**
+
+- Add `await` to all `convertToModelMessages()` calls
+- Replace `CoreMessage` with `ModelMessage`
+- Replace `convertToCoreMessages()` with `convertToModelMessages()`
+- Remove `mode` from `generateObject` calls
+- Move static tool definitions to server using `tool()` (recommended for most apps)
+- Use `onToolCall` in `useAgentChat` for client-side tool execution
+- Replace `toolsRequiringConfirmation` with `needsApproval`
+- Replace `addToolResult()` with `addToolOutput()` or `addToolApprovalResponse()`
+
+## Further reading
+
+- [Official AI SDK v6 migration guide](https://ai-sdk.dev/docs/migration-guides/migration-guide-6-0)
+- [Human in the Loop](./human-in-the-loop.md) -- `needsApproval` and `addToolApprovalResponse`
+- [Client Tools](./client-tools-continuation.md) -- `onToolCall` and auto-continuation