Changelog

New updates and improvements at Cloudflare.

Subscribe to RSS View RSS feeds

Agents

Mar 23, 2026

1. Agents SDK v0.8.0: readable state, idempotent schedules, typed AgentClient, and Zod 4

   Agents Workers

   The latest release of the Agents SDK ↗ exposes agent state as a readable property, prevents duplicate schedule rows across Durable Object restarts, brings full TypeScript inference to AgentClient, and migrates to Zod 4.

   Readable state on useAgent and AgentClient

   Both useAgent (React) and AgentClient (vanilla JS) now expose a state property that reflects the current agent state. Previously, reading state required manually tracking it through the onStateUpdate callback.

   React (useAgent)

   JavaScript

   JavaScript

   const agent = useAgent({
     agent: "game-agent",
     name: "room-123",
   });
   
   // Read state directly — no separate useState + onStateUpdate needed
   return <div>Score: {agent.state?.score}</div>;
   
   // Spread for partial updates
   agent.setState({ ...agent.state, score: (agent.state?.score ?? 0) + 10 });

   TypeScript

   TypeScript

   const agent = useAgent<GameAgent, GameState>({
     agent: "game-agent",
     name: "room-123",
   });
   
   // Read state directly — no separate useState + onStateUpdate needed
   return <div>Score: {agent.state?.score}</div>;
   
   // Spread for partial updates
   agent.setState({ ...agent.state, score: (agent.state?.score ?? 0) + 10 });

   agent.state is reactive — the component re-renders when state changes from either the server or a client-side setState() call.

   Vanilla JS (AgentClient)

   JavaScript

   JavaScript

   const client = new AgentClient({
     agent: "game-agent",
     name: "room-123",
     host: "your-worker.workers.dev",
   });
   
   client.setState({ score: 100 });
   console.log(client.state); // { score: 100 }

   TypeScript

   TypeScript

   const client = new AgentClient<GameAgent>({
     agent: "game-agent",
     name: "room-123",
     host: "your-worker.workers.dev",
   });
   
   client.setState({ score: 100 });
   console.log(client.state); // { score: 100 }

   State starts as undefined and is populated when the server sends the initial state on connect (from initialState) or when setState() is called. Use optional chaining (agent.state?.field) for safe access. The onStateUpdate callback continues to work as before — the new state property is additive.

   Idempotent schedule()

   schedule() now supports an idempotent option that deduplicates by (type, callback, payload), preventing duplicate rows from accumulating when called in places that run on every Durable Object restart such as onStart().

   Cron schedules are idempotent by default. Calling schedule("0 * * * *", "tick") multiple times with the same callback, expression, and payload returns the existing schedule row instead of creating a new one. Pass { idempotent: false } to override.

   Delayed and date-scheduled types support opt-in idempotency:

   JavaScript

   JavaScript

   import { Agent } from "agents";
   
   class MyAgent extends Agent {
     async onStart() {
       // Safe across restarts — only one row is created
       await this.schedule(60, "maintenance", undefined, { idempotent: true });
     }
   }

   TypeScript

   TypeScript

   import { Agent } from "agents";
   
   class MyAgent extends Agent {
     async onStart() {
       // Safe across restarts — only one row is created
       await this.schedule(60, "maintenance", undefined, { idempotent: true });
     }
   }

   Two new warnings help catch common foot-guns:

   • Calling schedule() inside onStart() without { idempotent: true } emits a console.warn with actionable guidance (once per callback; skipped for cron and when idempotent is set explicitly).
   • If an alarm cycle processes 10 or more stale one-shot rows for the same callback, the SDK emits a console.warn and a schedule:duplicate_warning diagnostics channel event.

   Typed AgentClient with call inference and stub proxy

   AgentClient now accepts an optional agent type parameter for full type inference on RPC calls, matching the typed experience already available with useAgent.

   JavaScript

   JavaScript

   const client = new AgentClient({
     agent: "my-agent",
     host: window.location.host,
   });
   
   // Typed call — method name autocompletes, args and return type inferred
   const value = await client.call("getValue");
   
   // Typed stub — direct RPC-style proxy
   await client.stub.getValue();
   await client.stub.add(1, 2);

   TypeScript

   TypeScript

   const client = new AgentClient<MyAgent>({
     agent: "my-agent",
     host: window.location.host,
   });
   
   // Typed call — method name autocompletes, args and return type inferred
   const value = await client.call("getValue");
   
   // Typed stub — direct RPC-style proxy
   await client.stub.getValue();
   await client.stub.add(1, 2);

   State is automatically inferred from the agent type, so onStateUpdate is also typed:

   JavaScript

   JavaScript

   const client = new AgentClient({
     agent: "my-agent",
     host: window.location.host,
     onStateUpdate: (state) => {
       // state is typed as MyAgent's state type
     },
   });

   TypeScript

   TypeScript

   const client = new AgentClient<MyAgent>({
     agent: "my-agent",
     host: window.location.host,
     onStateUpdate: (state) => {
       // state is typed as MyAgent's state type
     },
   });

   Existing untyped usage continues to work without changes. The RPC type utilities (AgentMethods, AgentStub, RPCMethods) are now exported from agents/client for advanced typing scenarios. agents, @cloudflare/ai-chat, and @cloudflare/codemode now require zod ^4.0.0. Zod v3 is no longer supported.

   @cloudflare/ai-chat fixes

   • Turn serialization — onChatMessage() and _reply() work is now queued so user requests, tool continuations, and saveMessages() never stream concurrently.
   • Duplicate messages on stop — Clicking stop during an active stream no longer splits the assistant message into two entries.
   • Duplicate messages after tool calls — Orphaned client IDs no longer leak into persistent storage.

   keepAlive() and keepAliveWhile() are no longer experimental

   keepAlive() now uses a lightweight in-memory ref count instead of schedule rows. Multiple concurrent callers share a single alarm cycle. The @experimental tag has been removed from both keepAlive() and keepAliveWhile().

   @cloudflare/codemode: TanStack AI integration

   A new entry point @cloudflare/codemode/tanstack-ai adds support for TanStack AI's ↗ chat() as an alternative to the Vercel AI SDK's streamText():

   JavaScript

   JavaScript

   import {
     createCodeTool,
     tanstackTools,
   } from "@cloudflare/codemode/tanstack-ai";
   import { chat } from "@tanstack/ai";
   
   const codeTool = createCodeTool({
     tools: [tanstackTools(myServerTools)],
     executor,
   });
   
   const stream = chat({ adapter, tools: [codeTool], messages });

   TypeScript

   TypeScript

   import { createCodeTool, tanstackTools } from "@cloudflare/codemode/tanstack-ai";
   import { chat } from "@tanstack/ai";
   
   const codeTool = createCodeTool({
     tools: [tanstackTools(myServerTools)],
     executor,
   });
   
   const stream = chat({ adapter, tools: [codeTool], messages });

   Upgrade

   To update to the latest version:

   npm i agents@latest @cloudflare/ai-chat@latest

Mar 17, 2026

1. @cloudflare/codemode v0.2.1: MCP barrel export, zero-dependency main entry point, and custom sandbox modules

   Agents Workers

   The latest releases of @cloudflare/codemode ↗ add a new MCP barrel export, remove ai and zod as required peer dependencies from the main entry point, and give you more control over the sandbox.

   New @cloudflare/codemode/mcp export

   A new @cloudflare/codemode/mcp entry point provides two functions that wrap MCP servers with Code Mode:

   • codeMcpServer({ server, executor }) — wraps an existing MCP server with a single code tool where each upstream tool becomes a typed codemode.* method.
   • openApiMcpServer({ spec, executor, request }) — creates search and execute MCP tools from an OpenAPI spec with host-side request proxying and automatic $ref resolution.
   JavaScript

   JavaScript

   import { codeMcpServer } from "@cloudflare/codemode/mcp";
   import { DynamicWorkerExecutor } from "@cloudflare/codemode";
   
   const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
   
   // Wrap an existing MCP server — all its tools become
   // typed methods the LLM can call from generated code
   const server = await codeMcpServer({ server: upstreamMcp, executor });

   TypeScript

   TypeScript

   import { codeMcpServer } from "@cloudflare/codemode/mcp";
   import { DynamicWorkerExecutor } from "@cloudflare/codemode";
   
   const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
   
   // Wrap an existing MCP server — all its tools become
   // typed methods the LLM can call from generated code
   const server = await codeMcpServer({ server: upstreamMcp, executor });

   Zero-dependency main entry point

   Breaking change in v0.2.0: generateTypes and the ToolDescriptor / ToolDescriptors types have moved to @cloudflare/codemode/ai:

   JavaScript

   JavaScript

   // Before
   import { generateTypes } from "@cloudflare/codemode";
   
   // After
   import { generateTypes } from "@cloudflare/codemode/ai";

   TypeScript

   TypeScript

   // Before
   import { generateTypes } from "@cloudflare/codemode";
   
   // After
   import { generateTypes } from "@cloudflare/codemode/ai";

   The main entry point (@cloudflare/codemode) no longer requires the ai or zod peer dependencies. It now exports:

   Export	Description
   sanitizeToolName	Sanitize tool names into valid JS identifiers
   normalizeCode	Normalize LLM-generated code into async arrow functions
   generateTypesFromJsonSchema	Generate TypeScript type definitions from plain JSON Schema
   jsonSchemaToType	Convert a single JSON Schema to a TypeScript type string
   DynamicWorkerExecutor	Sandboxed code execution via Dynamic Worker Loader
   ToolDispatcher	RPC target for dispatching tool calls from sandbox to host

   The ai and zod peer dependencies are now optional — only required when importing from @cloudflare/codemode/ai.

   Custom sandbox modules

   DynamicWorkerExecutor now accepts an optional modules option to inject custom ES modules into the sandbox:

   JavaScript

   JavaScript

   const executor = new DynamicWorkerExecutor({
     loader: env.LOADER,
     modules: {
       "utils.js": `export function add(a, b) { return a + b; }`,
     },
   });
   
   // Sandbox code can then: import { add } from "utils.js"

   TypeScript

   TypeScript

   const executor = new DynamicWorkerExecutor({
     loader: env.LOADER,
     modules: {
       "utils.js": `export function add(a, b) { return a + b; }`,
     },
   });
   
   // Sandbox code can then: import { add } from "utils.js"

   Internal normalization and sanitization

   DynamicWorkerExecutor now normalizes code and sanitizes tool names internally. You no longer need to call normalizeCode() or sanitizeToolName() before passing code and functions to execute().

   Upgrade

   npm i @cloudflare/codemode@latest

   See the Code Mode documentation for the full API reference.

Mar 03, 2026

1. Real-time file watching in Sandboxes

   Agents

   Sandboxes now support real-time filesystem watching via sandbox.watch(). The method returns a Server-Sent Events ↗ stream backed by native inotify, so your Worker receives create, modify, delete, and move events as they happen inside the container.

   sandbox.watch(path, options)

   Pass a directory path and optional filters. The returned stream is a standard ReadableStream you can proxy directly to a browser client or consume server-side.

   JavaScript

   JavaScript

   // Stream events to a browser client
   const stream = await sandbox.watch("/workspace/src", {
     recursive: true,
     include: ["*.ts", "*.js"],
   });
   
   return new Response(stream, {
     headers: { "Content-Type": "text/event-stream" },
   });

   TypeScript

   TypeScript

   // Stream events to a browser client
   const stream = await sandbox.watch("/workspace/src", {
     recursive: true,
     include: ["*.ts", "*.js"],
   });
   
   return new Response(stream, {
     headers: { "Content-Type": "text/event-stream" },
   });

   Server-side consumption with parseSSEStream

   Use parseSSEStream to iterate over events inside a Worker without forwarding them to a client.

   JavaScript

   JavaScript

   import { parseSSEStream } from "@cloudflare/sandbox";
   const stream = await sandbox.watch("/workspace/src", { recursive: true });
   
   for await (const event of parseSSEStream(stream)) {
     console.log(event.type, event.path);
   }

   TypeScript

   TypeScript

   import { parseSSEStream } from "@cloudflare/sandbox";
   import type { FileWatchSSEEvent } from "@cloudflare/sandbox";
   
   const stream = await sandbox.watch("/workspace/src", { recursive: true });
   
   for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
     console.log(event.type, event.path);
   }

   Each event includes a type field (create, modify, delete, or move) and the affected path. Move events also include a from field with the original path.

   Options

   Option	Type	Description
   recursive	boolean	Watch subdirectories. Defaults to false.
   include	string[]	Glob patterns to filter events. Omit to receive all events.

   Upgrade

   To update to the latest version:

   npm i @cloudflare/sandbox@latest

   For full API details, refer to the Sandbox file watching reference.

Mar 02, 2026

1. Agents SDK v0.7.0: Observability rewrite, keepAlive, and waitForMcpConnections

   Agents Workers

   The latest release of the Agents SDK ↗ rewrites observability from scratch with diagnostics_channel, adds keepAlive() to prevent Durable Object eviction during long-running work, and introduces waitForMcpConnections so MCP tools are always available when onChatMessage runs.

   Observability rewrite

   The previous observability system used console.log() with a custom Observability.emit() interface. v0.7.0 replaces it with structured events published to diagnostics channels — silent by default, zero overhead when nobody is listening.

   Every event has a type, payload, and timestamp. Events are routed to seven named channels:

   Channel	Event types
   agents:state	state:update
   agents:rpc	rpc, rpc:error
   agents:message	message:request, message:response, message:clear, message:cancel, message:error, tool:result, tool:approval
   agents:schedule	schedule:create, schedule:execute, schedule:cancel, schedule:retry, schedule:error, queue:retry, queue:error
   agents:lifecycle	connect, destroy
   agents:workflow	workflow:start, workflow:event, workflow:approved, workflow:rejected, workflow:terminated, workflow:paused, workflow:resumed, workflow:restarted
   agents:mcp	mcp:client:preconnect, mcp:client:connect, mcp:client:authorize, mcp:client:discover

   Use the typed subscribe() helper from agents/observability for type-safe access:

   JavaScript

   JavaScript

   import { subscribe } from "agents/observability";
   
   const unsub = subscribe("rpc", (event) => {
     if (event.type === "rpc") {
       console.log(`RPC call: ${event.payload.method}`);
     }
     if (event.type === "rpc:error") {
       console.error(
         `RPC failed: ${event.payload.method} — ${event.payload.error}`,
       );
     }
   });
   
   // Clean up when done
   unsub();

   TypeScript

   TypeScript

   import { subscribe } from "agents/observability";
   
   const unsub = subscribe("rpc", (event) => {
     if (event.type === "rpc") {
       console.log(`RPC call: ${event.payload.method}`);
     }
     if (event.type === "rpc:error") {
       console.error(
         `RPC failed: ${event.payload.method} — ${event.payload.error}`,
       );
     }
   });
   
   // Clean up when done
   unsub();

   In production, all diagnostics channel messages are automatically forwarded to Tail Workers — no subscription code needed in the agent itself:

   JavaScript

   JavaScript

   export default {
     async tail(events) {
       for (const event of events) {
         for (const msg of event.diagnosticsChannelEvents) {
           // msg.channel is "agents:rpc", "agents:workflow", etc.
           console.log(msg.timestamp, msg.channel, msg.message);
         }
       }
     },
   };

   TypeScript

   TypeScript

   export default {
     async tail(events) {
       for (const event of events) {
         for (const msg of event.diagnosticsChannelEvents) {
           // msg.channel is "agents:rpc", "agents:workflow", etc.
           console.log(msg.timestamp, msg.channel, msg.message);
         }
       }
     },
   };

   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.

   keepAlive() and keepAliveWhile()

   Durable Objects are evicted after a period of inactivity (typically 70-140 seconds with no incoming requests, WebSocket messages, or alarms). During long-running operations — streaming LLM responses, waiting on external APIs, running multi-step computations — the agent can be evicted mid-flight.

   keepAlive() prevents this by creating a 30-second heartbeat schedule. The alarm firing resets the inactivity timer. Returns a disposer function that cancels the heartbeat when called.

   JavaScript

   JavaScript

   const dispose = await this.keepAlive();
   try {
     const result = await longRunningComputation();
     await sendResults(result);
   } finally {
     dispose();
   }

   TypeScript

   TypeScript

   const dispose = await this.keepAlive();
   try {
     const result = await longRunningComputation();
     await sendResults(result);
   } finally {
     dispose();
   }

   keepAliveWhile() wraps an async function with automatic cleanup — the heartbeat starts before the function runs and stops when it completes:

   JavaScript

   JavaScript

   const result = await this.keepAliveWhile(async () => {
     const data = await longRunningComputation();
     return data;
   });

   TypeScript

   TypeScript

   const result = await this.keepAliveWhile(async () => {
     const data = await longRunningComputation();
     return data;
   });

   Key details:

   • Multiple concurrent callers — Each keepAlive() call returns an independent disposer. Disposing one does not affect others.
   • AIChatAgent built-in — AIChatAgent automatically calls keepAlive() during streaming responses. You do not need to add it yourself.
   • Uses the scheduling system — The heartbeat does not conflict with your own schedules. It shows up in getSchedules() if you need to inspect it.

   Note

   keepAlive() is marked @experimental and may change between releases.

   For the full API reference and when-to-use guidance, refer to Schedule tasks — Keeping the agent alive.

   waitForMcpConnections

   AIChatAgent now waits for MCP server connections to settle before calling onChatMessage. This ensures this.mcp.getAITools() returns the full set of tools, especially after Durable Object hibernation when connections are being restored in the background.

   JavaScript

   JavaScript

   export class ChatAgent extends AIChatAgent {
     // Default — waits up to 10 seconds
     // waitForMcpConnections = { timeout: 10_000 };
   
     // Wait forever
     waitForMcpConnections = true;
   
     // Disable waiting
     waitForMcpConnections = false;
   }

   TypeScript

   TypeScript

   export class ChatAgent extends AIChatAgent {
     // Default — waits up to 10 seconds
     // waitForMcpConnections = { timeout: 10_000 };
   
     // Wait forever
     waitForMcpConnections = true;
   
     // Disable waiting
     waitForMcpConnections = false;
   }

   Value	Behavior
   { timeout: 10_000 }	Wait up to 10 seconds (default)
   { timeout: N }	Wait up to N milliseconds
   true	Wait indefinitely until all connections ready
   false	Do not wait (old behavior before 0.2.0)

   For lower-level control, call this.mcp.waitForConnections() directly inside onChatMessage instead.

   Other improvements

   • MCP deduplication by name and URL — addMcpServer with HTTP transport now deduplicates on both server name and URL. Calling it with the same name but a different URL creates a new connection. URLs are normalized before comparison (trailing slashes, default ports, hostname case).
   • callbackHost optional for non-OAuth servers — addMcpServer no longer requires callbackHost when connecting to MCP servers that do not use OAuth.
   • MCP URL security — Server URLs are validated before connection to prevent SSRF. Private IP ranges, loopback addresses, link-local addresses, and cloud metadata endpoints are blocked.
   • Custom denial messages — addToolOutput now supports state: "output-error" with errorText for custom denial messages in human-in-the-loop tool approval flows.
   • requestId in chat options — onChatMessage options now include a requestId for logging and correlating events.

   Upgrade

   To update to the latest version:

   npm i agents@latest @cloudflare/ai-chat@latest

Feb 25, 2026

1. Agents SDK v0.6.0: RPC transport for MCP, optional OAuth, hardened schema conversion, and @cloudflare/ai-chat fixes

   Agents Workers

   The latest release of the Agents SDK ↗ lets you define an Agent and an McpAgent in the same Worker and connect them over RPC — no HTTP, no network overhead. It also makes OAuth opt-in for simple MCP connections, hardens the schema converter for production workloads, and ships a batch of @cloudflare/ai-chat reliability fixes.

   RPC transport for MCP

   You can now connect an Agent to an McpAgent in the same Worker using a Durable Object binding instead of an HTTP URL. The connection stays entirely within the Cloudflare runtime — no network round-trips, no serialization overhead.

   Pass the Durable Object namespace directly to addMcpServer:

   JavaScript

   JavaScript

   import { Agent } from "agents";
   
   export class MyAgent extends Agent {
     async onStart() {
       // Connect via DO binding — no HTTP, no network overhead
       await this.addMcpServer("counter", env.MY_MCP);
   
       // With props for per-user context
       await this.addMcpServer("counter", env.MY_MCP, {
         props: { userId: "user-123", role: "admin" },
       });
     }
   }

   TypeScript

   TypeScript

   import { Agent } from "agents";
   
   export class MyAgent extends Agent {
     async onStart() {
       // Connect via DO binding — no HTTP, no network overhead
       await this.addMcpServer("counter", env.MY_MCP);
   
       // With props for per-user context
       await this.addMcpServer("counter", env.MY_MCP, {
         props: { userId: "user-123", role: "admin" },
       });
     }
   }

   The addMcpServer method now accepts string | DurableObjectNamespace as the second parameter with full TypeScript overloads, so HTTP and RPC paths are type-safe and cannot be mixed.

   Key capabilities:

   • Hibernation support — RPC connections survive Durable Object hibernation automatically. The binding name and props are persisted to storage and restored on wake-up, matching the behavior of HTTP MCP connections.
   • Deduplication — Calling addMcpServer with the same server name returns the existing connection instead of creating duplicates. Connection IDs are stable across hibernation restore.
   • Smaller surface area — The RPC transport internals have been rewritten and reduced from 609 lines to 245 lines. RPCServerTransport now uses JSONRPCMessageSchema from the MCP SDK for validation instead of hand-written checks.

   Note

   RPC transport is experimental. The API may change based on feedback. Refer to the tracking issue ↗ for updates.

   Optional OAuth for MCP connections

   addMcpServer() no longer eagerly creates an OAuth provider for every connection. For servers that do not require authentication, a simple call is all you need:

   JavaScript

   JavaScript

   // No callbackHost, no OAuth config — just works
   await this.addMcpServer("my-server", "https://mcp.example.com");

   TypeScript

   TypeScript

   // No callbackHost, no OAuth config — just works
   await this.addMcpServer("my-server", "https://mcp.example.com");

   If the server responds with a 401, the SDK throws a clear error: "This MCP server requires OAuth authentication. Provide callbackHost in addMcpServer options to enable the OAuth flow." The restore-from-storage flow also handles missing callback URLs gracefully, skipping auth provider creation for non-OAuth servers.

   Hardened JSON Schema to TypeScript converter

   The schema converter used by generateTypes() and getAITools() now handles edge cases that previously caused crashes in production:

   • Depth and circular reference guards — Prevents stack overflows on recursive or deeply nested schemas
   • $ref resolution — Supports internal JSON Pointers (#/definitions/..., #/$defs/..., #)
   • Tuple support — prefixItems (JSON Schema 2020-12) and array items (draft-07)
   • OpenAPI 3.0 nullable: true — Supported across all schema branches
   • Per-tool error isolation — One malformed schema cannot crash the full pipeline in generateTypes() or getAITools()
   • Missing inputSchema fallback — getAITools() falls back to { type: "object" } instead of throwing

   @cloudflare/ai-chat fixes

   • Tool denial flow — Denied tool approvals (approved: false) now transition to output-denied with a tool_result, fixing Anthropic provider compatibility. Custom denial messages are supported via state: "output-error" and errorText.
   • Abort/cancel support — Streaming responses now properly cancel the reader loop when the abort signal fires and send a done signal to the client.
   • Duplicate message persistence — persistMessages() now reconciles assistant messages by content and order, preventing duplicate rows when clients resend full history.
   • requestId in OnChatMessageOptions — Handlers can now send properly-tagged error responses for pre-stream failures.
   • redacted_thinking preservation — The message sanitizer no longer strips Anthropic redacted_thinking blocks.
   • /get-messages reliability — Endpoint handling moved from a prototype onRequest() override to a constructor wrapper, so it works even when users override onRequest without calling super.onRequest().
   • Client tool APIs undeprecated — createToolsFromClientSchemas, clientTools, AITool, extractClientToolSchemas, and the tools option on useAgentChat are restored for SDK use cases where tools are defined dynamically at runtime.
   • jsonSchema initialization — Fixed jsonSchema not initialized error when calling getAITools() in onChatMessage.

   Upgrade

   To update to the latest version:

   npm i agents@latest @cloudflare/ai-chat@latest

Feb 23, 2026

1. Backup and restore API for Sandbox SDK

   Agents R2 Containers

   Sandboxes now support createBackup() and restoreBackup() methods for creating and restoring point-in-time snapshots of directories.

   This allows you to restore environments quickly. For instance, in order to develop in a sandbox, you may need to include a user's codebase and run a build step. Unfortunately git clone and npm install can take minutes, and you don't want to run these steps every time the user starts their sandbox.

   Now, after the initial setup, you can just call createBackup(), then restoreBackup() the next time this environment is needed. This makes it practical to pick up exactly where a user left off, even after days of inactivity, without repeating expensive setup steps.

   TypeScript

   const sandbox = getSandbox(env.Sandbox, "my-sandbox");
   
   // Make non-trivial changes to the file system
   await sandbox.gitCheckout(endUserRepo, { targetDir: "/workspace" });
   await sandbox.exec("npm install", { cwd: "/workspace" });
   
   // Create a point-in-time backup of the directory
   const backup = await sandbox.createBackup({ dir: "/workspace" });
   
   // Store the handle for later use
   await env.KV.put(`backup:${userId}`, JSON.stringify(backup));
   
   // ... in a future session...
   
   // Restore instead of re-cloning and reinstalling
   await sandbox.restoreBackup(backup);

   Backups are stored in R2 and can take advantage of R2 object lifecycle rules to ensure they do not persist forever.

   Key capabilities:

   • Persist and reuse across sandbox sessions — Easily store backup handles in KV, D1, or Durable Object storage for use in subsequent sessions
   • Usable across multiple instances — Fork a backup across many sandboxes for parallel work
   • Named backups — Provide optional human-readable labels for easier management
   • TTLs — Set time-to-live durations so backups are automatically removed from storage once they are no longer neeeded

   Note

   Backup and restore currently uses a FUSE overlay. Soon, native snapshotting at a lower level will be added to Containers and Sandboxes, improving speed and ergonomics. The current backup functionality provides a significant speed improvement over manually recreating a file system, but it will be further optimized in the future. The new snapshotting system will use a similar API, so changing to this system will be simple once it is available.

   To get started, refer to the backup and restore guide for setup instructions and usage patterns, or the Backups API reference for full method documentation.

Feb 20, 2026

1. @cloudflare/codemode v0.1.0: a new runtime agnostic modular architecture

   Agents Workers

   The @cloudflare/codemode ↗ package has been rewritten into a modular, runtime-agnostic SDK.

   Code Mode ↗ enables LLMs to write and execute code that orchestrates your tools, instead of calling them one at a time. This can (and does) yield significant token savings, reduces context window pressure and improves overall model performance on a task.

   The new Executor interface is runtime agnostic and comes with a prebuilt DynamicWorkerExecutor to run generated code in a Dynamic Worker Loader.

   Breaking changes

   • Removed experimental_codemode() and CodeModeProxy — the package no longer owns an LLM call or model choice
   • New import path: createCodeTool() is now exported from @cloudflare/codemode/ai

   New features

   • createCodeTool() — Returns a standard AI SDK Tool to use in your AI agents.
   • Executor interface — Minimal execute(code, fns) contract. Implement for any code sandboxing primitive or runtime.

   DynamicWorkerExecutor

   Runs code in a Dynamic Worker. It comes with the following features:

   • Network isolation — fetch() and connect() blocked by default (globalOutbound: null) when using DynamicWorkerExecutor
   • Console capture — console.log/warn/error captured and returned in ExecuteResult.logs
   • Execution timeout — Configurable via timeout option (default 30s)

   Usage

   JavaScript

   JavaScript

   import { createCodeTool } from "@cloudflare/codemode/ai";
   import { DynamicWorkerExecutor } from "@cloudflare/codemode";
   import { streamText } from "ai";
   
   const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
   const codemode = createCodeTool({ tools: myTools, executor });
   
   const result = streamText({
     model,
     tools: { codemode },
     messages,
   });

   TypeScript

   TypeScript

   import { createCodeTool } from "@cloudflare/codemode/ai";
   import { DynamicWorkerExecutor } from "@cloudflare/codemode";
   import { streamText } from "ai";
   
   const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
   const codemode = createCodeTool({ tools: myTools, executor });
   
   const result = streamText({
     model,
     tools: { codemode },
     messages,
   });

   Wrangler configuration

   wrangler.jsonc

   JSONC

   {
     "worker_loaders": [{ "binding": "LOADER" }],
   }

   wrangler.toml

   TOML

   [[worker_loaders]]
   binding = "LOADER"

   See the Code Mode documentation for full API reference and examples.

   Upgrade

   npm i @cloudflare/codemode@latest

Feb 17, 2026

1. Agents SDK v0.5.0: Protocol message control, retry utilities, data parts, and @cloudflare/ai-chat v0.1.0

   Agents Workers

   The latest release of the Agents SDK ↗ adds built-in retry utilities, per-connection protocol message control, and a fully rewritten @cloudflare/ai-chat with data parts, tool approval persistence, and zero breaking changes.

   Retry utilities

   A new this.retry() method lets you retry any async operation with exponential backoff and jitter. You can pass an optional shouldRetry predicate to bail early on non-retryable errors.

   JavaScript

   JavaScript

   class MyAgent extends Agent {
     async onRequest(request) {
       const data = await this.retry(() => callUnreliableService(), {
         maxAttempts: 4,
         shouldRetry: (err) => !(err instanceof PermanentError),
       });
       return Response.json(data);
     }
   }

   TypeScript

   TypeScript

   class MyAgent extends Agent {
     async onRequest(request: Request) {
       const data = await this.retry(() => callUnreliableService(), {
         maxAttempts: 4,
         shouldRetry: (err) => !(err instanceof PermanentError),
       });
       return Response.json(data);
     }
   }

   Retry options are also available per-task on queue(), schedule(), scheduleEvery(), and addMcpServer():

   JavaScript

   JavaScript

   // Per-task retry configuration, persisted in SQLite alongside the task
   await this.schedule(
     Date.now() + 60_000,
     "sendReport",
     { userId: "abc" },
     {
       retry: { maxAttempts: 5 },
     },
   );
   
   // Class-level retry defaults
   class MyAgent extends Agent {
     static options = {
       retry: { maxAttempts: 3 },
     };
   }

   TypeScript

   TypeScript

   // Per-task retry configuration, persisted in SQLite alongside the task
   await this.schedule(Date.now() + 60_000, "sendReport", { userId: "abc" }, {
     retry: { maxAttempts: 5 },
   });
   
   // Class-level retry defaults
   class MyAgent extends Agent {
     static options = {
       retry: { maxAttempts: 3 },
     };
   }

   Retry options are validated eagerly at enqueue/schedule time, and invalid values throw immediately. Internal retries have also been added for workflow operations (terminateWorkflow, pauseWorkflow, and others) with Durable Object-aware error detection.

   Per-connection protocol message control

   Agents automatically send JSON text frames (identity, state, MCP server lists) to every WebSocket connection. You can now suppress these per-connection for clients that cannot handle them — binary-only devices, MQTT clients, or lightweight embedded systems.

   JavaScript

   JavaScript

   class MyAgent extends Agent {
     shouldSendProtocolMessages(connection, ctx) {
       // Suppress protocol messages for MQTT clients
       const subprotocol = ctx.request.headers.get("Sec-WebSocket-Protocol");
       return subprotocol !== "mqtt";
     }
   }

   TypeScript

   TypeScript

   class MyAgent extends Agent {
     shouldSendProtocolMessages(connection: Connection, ctx: ConnectionContext) {
       // Suppress protocol messages for MQTT clients
       const subprotocol = ctx.request.headers.get("Sec-WebSocket-Protocol");
       return subprotocol !== "mqtt";
     }
   }

   Connections with protocol messages disabled still fully participate in RPC and regular messaging. Use isConnectionProtocolEnabled(connection) to check a connection's status at any time. The flag persists across Durable Object hibernation.

   See Protocol messages for full documentation.

   @cloudflare/ai-chat v0.1.0

   The first stable release of @cloudflare/ai-chat ships alongside this release with a major refactor of AIChatAgent internals — new ResumableStream class, WebSocket ChatTransport, and simplified SSE parsing — with zero breaking changes. Existing code using AIChatAgent and useAgentChat works as-is.

   Key new features:

   • Data parts — Attach typed JSON blobs (data-*) to messages alongside text. Supports reconciliation (type+id updates in-place), append, and transient parts (ephemeral via onData callback). See Data parts.
   • Tool approval persistence — The needsApproval approval UI now survives page refresh and DO hibernation. The streaming message is persisted to SQLite when a tool enters approval-requested state.
   • maxPersistedMessages — Cap SQLite message storage with automatic oldest-message deletion.
   • body option on useAgentChat — Send custom data with every request (static or dynamic).
   • Incremental persistence — Hash-based cache to skip redundant SQL writes.
   • Row size guard — Automatic two-pass compaction when messages approach the SQLite 2 MB limit.
   • autoContinueAfterToolResult defaults to true — Client-side tool results and tool approvals now automatically trigger a server continuation, matching server-executed tool behavior. Set autoContinueAfterToolResult: false in useAgentChat to restore the previous behavior.

   Notable bug fixes:

   • Resolved stream resumption race conditions
   • Resolved an issue where setMessages functional updater sent empty arrays
   • Resolved an issue where client tool schemas were lost after DO hibernation
   • Resolved InvalidPromptError after tool approval (approval.id was dropped)
   • Resolved an issue where message metadata was not propagated on broadcast/resume paths
   • Resolved an issue where clearAll() did not clear in-memory chunk buffers
   • Resolved an issue where reasoning-delta silently dropped data when reasoning-start was missed during stream resumption

   Synchronous queue and schedule getters

   getQueue(), getQueues(), getSchedule(), dequeue(), dequeueAll(), and dequeueAllByCallback() were unnecessarily async despite only performing synchronous SQL operations. They now return values directly instead of wrapping them in Promises. This is backward compatible — existing code using await on these methods will continue to work.

   Other improvements

   • Fix TypeScript "excessively deep" error — A depth counter on CanSerialize and IsSerializableParam types bails out to true after 10 levels of recursion, preventing the "Type instantiation is excessively deep" error with deeply nested types like AI SDK CoreMessage[].
   • POST SSE keepalive — The POST SSE handler now sends event: ping every 30 seconds to keep the connection alive, matching the existing GET SSE handler behavior. This prevents POST response streams from being silently dropped by proxies during long-running tool calls.
   • Widened peer dependency ranges — Peer dependency ranges across packages have been widened to prevent cascading major bumps during 0.x minor releases. @cloudflare/ai-chat and @cloudflare/codemode are now marked as optional peer dependencies.

   Upgrade

   To update to the latest version:

   npm i agents@latest @cloudflare/ai-chat@latest

Feb 13, 2026

1. Introducing GLM-4.7-Flash on Workers AI, @cloudflare/tanstack-ai, and workers-ai-provider v3.1.1

   Workers Agents Workers AI

   We're excited to announce GLM-4.7-Flash on Workers AI, a fast and efficient text generation model optimized for multilingual dialogue and instruction-following tasks, along with the brand-new @cloudflare/tanstack-ai ↗ package and workers-ai-provider v3.1.1 ↗.

   You can now run AI agents entirely on Cloudflare. With GLM-4.7-Flash's multi-turn tool calling support, plus full compatibility with TanStack AI and the Vercel AI SDK, you have everything you need to build agentic applications that run completely at the edge.

   GLM-4.7-Flash — Multilingual Text Generation Model

   @cf/zai-org/glm-4.7-flash is a multilingual model with a 131,072 token context window, making it ideal for long-form content generation, complex reasoning tasks, and multilingual applications.

   Key Features and Use Cases:

   • Multi-turn Tool Calling for Agents: Build AI agents that can call functions and tools across multiple conversation turns
   • Multilingual Support: Built to handle content generation in multiple languages effectively
   • Large Context Window: 131,072 tokens for long-form writing, complex reasoning, and processing long documents
   • Fast Inference: Optimized for low-latency responses in chatbots and virtual assistants
   • Instruction Following: Excellent at following complex instructions for code generation and structured tasks

   Use GLM-4.7-Flash through the Workers AI binding (env.AI.run()), the REST API at /run or /v1/chat/completions, AI Gateway, or via workers-ai-provider for the Vercel AI SDK.

   Pricing is available on the model page or pricing page.

   @cloudflare/tanstack-ai v0.1.1 — TanStack AI adapters for Workers AI and AI Gateway

   We've released @cloudflare/tanstack-ai, a new package that brings Workers AI and AI Gateway support to TanStack AI ↗. This provides a framework-agnostic alternative for developers who prefer TanStack's approach to building AI applications.

   Workers AI adapters support four configuration modes — plain binding (env.AI), plain REST, AI Gateway binding (env.AI.gateway(id)), and AI Gateway REST — across all capabilities:

   • Chat (createWorkersAiChat) — Streaming chat completions with tool calling, structured output, and reasoning text streaming.
   • Image generation (createWorkersAiImage) — Text-to-image models.
   • Transcription (createWorkersAiTranscription) — Speech-to-text.
   • Text-to-speech (createWorkersAiTts) — Audio generation.
   • Summarization (createWorkersAiSummarize) — Text summarization.

   AI Gateway adapters route requests from third-party providers — OpenAI, Anthropic, Gemini, Grok, and OpenRouter — through Cloudflare AI Gateway for caching, rate limiting, and unified billing.

   To get started:

   npm install @cloudflare/tanstack-ai @tanstack/ai

   workers-ai-provider v3.1.1 — transcription, speech, reranking, and reliability

   The Workers AI provider for the Vercel AI SDK ↗ now supports three new capabilities beyond chat and image generation:

   • Transcription (provider.transcription(model)) — Speech-to-text with automatic handling of model-specific input formats across binding and REST paths.
   • Text-to-speech (provider.speech(model)) — Audio generation with support for voice and speed options.
   • Reranking (provider.reranking(model)) — Document reranking for RAG pipelines and search result ordering.

   TypeScript

   import { createWorkersAI } from "workers-ai-provider";
   import {
     experimental_transcribe,
     experimental_generateSpeech,
     rerank,
   } from "ai";
   
   const workersai = createWorkersAI({ binding: env.AI });
   
   const transcript = await experimental_transcribe({
     model: workersai.transcription("@cf/openai/whisper-large-v3-turbo"),
     audio: audioData,
     mediaType: "audio/wav",
   });
   
   const speech = await experimental_generateSpeech({
     model: workersai.speech("@cf/deepgram/aura-1"),
     text: "Hello world",
     voice: "asteria",
   });
   
   const ranked = await rerank({
     model: workersai.reranking("@cf/baai/bge-reranker-base"),
     query: "What is machine learning?",
     documents: ["ML is a branch of AI.", "The weather is sunny."],
   });

   This release also includes a comprehensive reliability overhaul (v3.0.5):

   • Fixed streaming — Responses now stream token-by-token instead of buffering all chunks, using a proper TransformStream pipeline with backpressure.
   • Fixed tool calling — Resolved issues with tool call ID sanitization, conversation history preservation, and a heuristic that silently fell back to non-streaming mode when tools were defined.
   • Premature stream termination detection — Streams that end unexpectedly now report finishReason: "error" instead of silently reporting "stop".
   • AI Search support — Added createAISearch as the canonical export (renamed from AutoRAG). createAutoRAG still works with a deprecation warning.

   To upgrade:

   npm install workers-ai-provider@latest ai

   Resources

   • @cloudflare/tanstack-ai on npm ↗
   • workers-ai-provider on npm ↗
   • GitHub repository ↗

Feb 09, 2026

1. Agents SDK v0.4.0: Readonly connections, MCP security improvements, x402 v2 migration, and custom MCP OAuth providers

   Agents Workers

   The latest release of the Agents SDK ↗ brings readonly connections, MCP protocol and security improvements, x402 payment protocol v2 migration, and the ability to customize OAuth for MCP server connections.

   Readonly connections

   Agents can now restrict WebSocket clients to read-only access, preventing them from modifying agent state. This is useful for dashboards, spectator views, or any scenario where clients should observe but not mutate.

   New hooks: shouldConnectionBeReadonly, setConnectionReadonly, isConnectionReadonly. Readonly connections block both client-side setState() and mutating @callable() methods, and the readonly flag survives hibernation.

   JavaScript

   JavaScript

   class MyAgent extends Agent {
     shouldConnectionBeReadonly(connection) {
       // Make spectators readonly
       return connection.url.includes("spectator");
     }
   }

   TypeScript

   TypeScript

   class MyAgent extends Agent {
     shouldConnectionBeReadonly(connection) {
       // Make spectators readonly
       return connection.url.includes("spectator");
     }
   }

   Custom MCP OAuth providers

   The new createMcpOAuthProvider method on the Agent class allows subclasses to override the default OAuth provider used when connecting to MCP servers. This enables custom authentication strategies such as pre-registered client credentials or mTLS, beyond the built-in dynamic client registration.

   JavaScript

   JavaScript

   class MyAgent extends Agent {
     createMcpOAuthProvider(callbackUrl) {
       return new MyCustomOAuthProvider(this.ctx.storage, this.name, callbackUrl);
     }
   }

   TypeScript

   TypeScript

   class MyAgent extends Agent {
     createMcpOAuthProvider(callbackUrl: string): AgentMcpOAuthProvider {
       return new MyCustomOAuthProvider(this.ctx.storage, this.name, callbackUrl);
     }
   }

   MCP SDK upgrade to 1.26.0

   Upgraded the MCP SDK to 1.26.0 to prevent cross-client response leakage. Stateless MCP Servers should now create a new McpServer instance per request instead of sharing a single instance. A guard is added in this version of the MCP SDK which will prevent connection to a Server instance that has already been connected to a transport. Developers will need to modify their code if they declare their McpServer instance as a global variable.

   MCP OAuth callback URL security fix

   Added callbackPath option to addMcpServer to prevent instance name leakage in MCP OAuth callback URLs. When sendIdentityOnConnect is false, callbackPath is now required — the default callback URL would expose the instance name, undermining the security intent. Also fixes callback request detection to match via the state parameter instead of a loose /callback URL substring check, enabling custom callback paths.

   Deprecate onStateUpdate in favor of onStateChanged

   onStateChanged is a drop-in rename of onStateUpdate (same signature, same behavior). onStateUpdate still works but emits a one-time console warning per class. validateStateChange rejections now propagate a CF_AGENT_STATE_ERROR message back to the client.

   x402 v2 migration

   Migrated the x402 MCP payment integration from the legacy x402 package to @x402/core and @x402/evm v2.

   Breaking changes for x402 users:

   • Peer dependencies changed: replace x402 with @x402/core and @x402/evm
   • PaymentRequirements type now uses v2 fields (e.g. amount instead of maxAmountRequired)
   • X402ClientConfig.account type changed from viem.Account to ClientEvmSigner (structurally compatible with privateKeyToAccount())

   npm uninstall x402
   npm install @x402/core @x402/evm

   Network identifiers now accept both legacy names and CAIP-2 format:

   TypeScript

   // Legacy name (auto-converted)
   {
     network: "base-sepolia",
   }
   
   // CAIP-2 format (preferred)
   {
     network: "eip155:84532",
   }

   Other x402 changes:

   • X402ClientConfig.network is now optional — the client auto-selects from available payment requirements
   • Server-side lazy initialization: facilitator connection is deferred until the first paid tool invocation
   • Payment tokens support both v2 (PAYMENT-SIGNATURE) and v1 (X-PAYMENT) HTTP headers
   • Added normalizeNetwork export for converting legacy network names to CAIP-2 format
   • Re-exports PaymentRequirements, PaymentRequired, Network, FacilitatorConfig, and ClientEvmSigner from agents/x402

   Other improvements

   • Fix useAgent and AgentClient crashing when using basePath routing
   • CORS handling delegated to partyserver's native support (simpler, more reliable)
   • Client-side onStateUpdateError callback for handling rejected state updates

   Upgrade

   To update to the latest version:

   npm i agents@latest

Feb 09, 2026

1. Interactive browser terminals in Sandboxes

   Agents

   The Sandbox SDK ↗ now supports PTY (pseudo-terminal) passthrough, enabling browser-based terminal UIs to connect to sandbox shells via WebSocket.

   sandbox.terminal(request)

   The new terminal() method proxies a WebSocket upgrade to the container's PTY endpoint, with output buffering for replay on reconnect.

   JavaScript

   JavaScript

   // Worker: proxy WebSocket to container terminal
   return sandbox.terminal(request, { cols: 80, rows: 24 });

   TypeScript

   TypeScript

   // Worker: proxy WebSocket to container terminal
   return sandbox.terminal(request, { cols: 80, rows: 24 });

   Multiple terminals per sandbox

   Each session can have its own terminal with an isolated working directory and environment, so users can run separate shells side-by-side in the same container.

   JavaScript

   JavaScript

   // Multiple isolated terminals in the same sandbox
   const dev = await sandbox.getSession("dev");
   return dev.terminal(request);

   TypeScript

   TypeScript

   // Multiple isolated terminals in the same sandbox
   const dev = await sandbox.getSession("dev");
   return dev.terminal(request);

   xterm.js addon

   The new @cloudflare/sandbox/xterm export provides a SandboxAddon for xterm.js ↗ with automatic reconnection (exponential backoff + jitter), buffered output replay, and resize forwarding.

   JavaScript

   JavaScript

   import { SandboxAddon } from "@cloudflare/sandbox/xterm";
   
   const addon = new SandboxAddon({
     getWebSocketUrl: ({ sandboxId, origin }) =>
       `${origin}/ws/terminal?id=${sandboxId}`,
     onStateChange: (state, error) => updateUI(state),
   });
   terminal.loadAddon(addon);
   addon.connect({ sandboxId: "my-sandbox" });

   TypeScript

   TypeScript

   import { SandboxAddon } from "@cloudflare/sandbox/xterm";
   
   const addon = new SandboxAddon({
     getWebSocketUrl: ({ sandboxId, origin }) =>
       `${origin}/ws/terminal?id=${sandboxId}`,
     onStateChange: (state, error) => updateUI(state),
   });
   terminal.loadAddon(addon);
   addon.connect({ sandboxId: "my-sandbox" });

   Upgrade

   To update to the latest version:

   npm i @cloudflare/sandbox@latest

Feb 03, 2026

1. Agents SDK v0.3.7: Workflows integration, synchronous state, and scheduleEvery()

   Agents Workflows

   The latest release of the Agents SDK ↗ brings first-class support for Cloudflare Workflows, synchronous state management, and new scheduling capabilities.

   Cloudflare Workflows integration

   Agents excel at real-time communication and state management. Workflows excel at durable execution. Together, they enable powerful patterns where Agents handle WebSocket connections while Workflows handle long-running tasks, retries, and human-in-the-loop flows.

   Use the new AgentWorkflow class to define workflows with typed access to your Agent:

   JavaScript

   JavaScript

   import { AgentWorkflow } from "agents/workflows";
   export class ProcessingWorkflow extends AgentWorkflow {
     async run(event, step) {
       // Call Agent methods via RPC
       await this.agent.updateStatus(event.payload.taskId, "processing");
   
       // Non-durable: progress reporting to clients
       await this.reportProgress({ step: "process", percent: 0.5 });
       this.broadcastToClients({ type: "update", taskId: event.payload.taskId });
   
       // Durable via step: idempotent, won't repeat on retry
       await step.mergeAgentState({ taskProgress: 0.5 });
   
       const result = await step.do("process", async () => {
         return processData(event.payload.data);
       });
   
       await step.reportComplete(result);
       return result;
     }
   }

   TypeScript

   TypeScript

   import { AgentWorkflow } from "agents/workflows";
   import type { AgentWorkflowEvent, AgentWorkflowStep } from "agents/workflows";
   
   export class ProcessingWorkflow extends AgentWorkflow<MyAgent, TaskParams> {
     async run(event: AgentWorkflowEvent<TaskParams>, step: AgentWorkflowStep) {
       // Call Agent methods via RPC
       await this.agent.updateStatus(event.payload.taskId, "processing");
   
       // Non-durable: progress reporting to clients
       await this.reportProgress({ step: "process", percent: 0.5 });
       this.broadcastToClients({ type: "update", taskId: event.payload.taskId });
   
       // Durable via step: idempotent, won't repeat on retry
       await step.mergeAgentState({ taskProgress: 0.5 });
   
       const result = await step.do("process", async () => {
         return processData(event.payload.data);
       });
   
       await step.reportComplete(result);
       return result;
     }
   }

   Start workflows from your Agent with runWorkflow() and handle lifecycle events:

   JavaScript

   JavaScript

   export class MyAgent extends Agent {
     async startTask(taskId, data) {
       const instanceId = await this.runWorkflow("PROCESSING_WORKFLOW", {
         taskId,
         data,
       });
       return { instanceId };
     }
   
     async onWorkflowProgress(workflowName, instanceId, progress) {
       this.broadcast(JSON.stringify({ type: "progress", progress }));
     }
   
     async onWorkflowComplete(workflowName, instanceId, result) {
       console.log(`Workflow ${instanceId} completed`);
     }
   
     async onWorkflowError(workflowName, instanceId, error) {
       console.error(`Workflow ${instanceId} failed:`, error);
     }
   }

   TypeScript

   TypeScript

   export class MyAgent extends Agent {
     async startTask(taskId: string, data: string) {
       const instanceId = await this.runWorkflow("PROCESSING_WORKFLOW", {
         taskId,
         data,
       });
       return { instanceId };
     }
   
     async onWorkflowProgress(
       workflowName: string,
       instanceId: string,
       progress: unknown,
     ) {
       this.broadcast(JSON.stringify({ type: "progress", progress }));
     }
   
     async onWorkflowComplete(
       workflowName: string,
       instanceId: string,
       result?: unknown,
     ) {
       console.log(`Workflow ${instanceId} completed`);
     }
   
     async onWorkflowError(
       workflowName: string,
       instanceId: string,
       error: unknown,
     ) {
       console.error(`Workflow ${instanceId} failed:`, error);
     }
   }

   Key workflow methods on your Agent:

   • runWorkflow(workflowName, params, options?) — Start a workflow with optional metadata
   • getWorkflow(workflowId) / getWorkflows(criteria?) — Query workflows with cursor-based pagination
   • approveWorkflow(workflowId) / rejectWorkflow(workflowId) — Human-in-the-loop approval flows
   • pauseWorkflow(), resumeWorkflow(), terminateWorkflow() — Workflow control

   Synchronous setState()

   State updates are now synchronous with a new validateStateChange() validation hook:

   JavaScript

   JavaScript

   export class MyAgent extends Agent {
     validateStateChange(oldState, newState) {
       // Return false to reject the change
       if (newState.count < 0) return false;
       // Return modified state to transform
       return { ...newState, lastUpdated: Date.now() };
     }
   }

   TypeScript

   TypeScript

   export class MyAgent extends Agent<Env, State> {
     validateStateChange(oldState: State, newState: State): State | false {
       // Return false to reject the change
       if (newState.count < 0) return false;
       // Return modified state to transform
       return { ...newState, lastUpdated: Date.now() };
     }
   }

   scheduleEvery() for recurring tasks

   The new scheduleEvery() method enables fixed-interval recurring tasks with built-in overlap prevention:

   JavaScript

   JavaScript

   // Run every 5 minutes
   await this.scheduleEvery("syncData", 5 * 60 * 1000, { source: "api" });

   TypeScript

   TypeScript

   // Run every 5 minutes
   await this.scheduleEvery("syncData", 5 * 60 * 1000, { source: "api" });

   Callable system improvements

   • Client-side RPC timeout — Set timeouts on callable method invocations
   • StreamingResponse.error(message) — Graceful stream error signaling
   • getCallableMethods() — Introspection API for discovering callable methods
   • Connection close handling — Pending calls are automatically rejected on disconnect
   JavaScript

   JavaScript

   await agent.call("method", [args], {
     timeout: 5000,
     stream: { onChunk, onDone, onError },
   });

   TypeScript

   TypeScript

   await agent.call("method", [args], {
     timeout: 5000,
     stream: { onChunk, onDone, onError },
   });

   Email and routing enhancements

   Secure email reply routing — Email replies are now secured with HMAC-SHA256 signed headers, preventing unauthorized routing of emails to agent instances.

   Routing improvements:

   • basePath option to bypass default URL construction for custom routing
   • Server-sent identity — Agents send name and agent type on connect
   • New onIdentity and onIdentityChange callbacks on the client
   JavaScript

   JavaScript

   const agent = useAgent({
     basePath: "user",
     onIdentity: (name, agentType) => console.log(`Connected to ${name}`),
   });

   TypeScript

   TypeScript

   const agent = useAgent({
     basePath: "user",
     onIdentity: (name, agentType) => console.log(`Connected to ${name}`),
   });

   Upgrade

   To update to the latest version:

   npm i agents@latest

   For the complete Workflows API reference and patterns, see Run Workflows.

Dec 22, 2025

1. Agents SDK v0.3.0, workers-ai-provider v3.0.0, and ai-gateway-provider v3.0.0 with AI SDK v6 support

   Agents Workers

   We've shipped a new release for the Agents SDK ↗ v0.3.0 bringing full compatibility with AI SDK v6 ↗ and introducing the unified tool pattern, dynamic tool approval, and enhanced React hooks with improved tool handling.

   This release includes improved streaming and tool support, dynamic tool approval (for "human in the loop" systems), enhanced React hooks with onToolCall callback, improved error handling for streaming responses, and seamless migration from v5 patterns.

   This makes it ideal for building production AI chat interfaces with Cloudflare Workers AI models, agent workflows, human-in-the-loop systems, or any application requiring reliable tool execution and approval workflows.

   Additionally, we've updated workers-ai-provider v3.0.0, the official provider for Cloudflare Workers AI models, and ai-gateway-provider v3.0.0, the provider for Cloudflare AI Gateway, to be compatible with AI SDK v6.

   Agents SDK v0.3.0

   Unified Tool Pattern

   AI SDK v6 introduces a unified tool pattern where all tools are defined on the server using the tool() function. This replaces the previous client-side AITool pattern.

   Server-Side Tool Definition

   TypeScript

   import { tool } from "ai";
   import { z } from "zod";
   
   // Server: Define ALL tools on the server
   const tools = {
     // Server-executed tool
     getWeather: tool({
       description: "Get weather for a city",
       inputSchema: z.object({ city: z.string() }),
       execute: async ({ city }) => fetchWeather(city)
     }),
   
     // Client-executed tool (no execute = client handles via onToolCall)
     getLocation: tool({
       description: "Get user location from browser",
       inputSchema: z.object({})
       // No execute function
     }),
   
     // Tool requiring approval (dynamic based on input)
     processPayment: tool({
       description: "Process a payment",
       inputSchema: z.object({ amount: z.number() }),
       needsApproval: async ({ amount }) => amount > 100,
       execute: async ({ amount }) => charge(amount)
     })
   };

   Client-Side Tool Handling

   TypeScript

   // Client: Handle client-side tools via onToolCall callback
   import { useAgentChat } from "agents/ai-react";
   
   const { messages, sendMessage, addToolOutput } = useAgentChat({
     agent,
     onToolCall: async ({ toolCall, addToolOutput }) => {
       if (toolCall.toolName === "getLocation") {
         const position = await new Promise((resolve, reject) => {
           navigator.geolocation.getCurrentPosition(resolve, reject);
         });
         addToolOutput({
           toolCallId: toolCall.toolCallId,
           output: {
             lat: position.coords.latitude,
             lng: position.coords.longitude
           }
         });
       }
     }
   });

   Key benefits of the unified tool pattern:

   • Server-defined tools: All tools are defined in one place on the server
   • Dynamic approval: Use needsApproval to conditionally require user confirmation
   • Cleaner client code: Use onToolCall callback instead of managing tool configs
   • Type safety: Full TypeScript support with proper tool typing

   useAgentChat(options)

   Creates a new chat interface with enhanced v6 capabilities.

   TypeScript

   // Basic chat setup with onToolCall
   const { messages, sendMessage, addToolOutput } = useAgentChat({
     agent,
     onToolCall: async ({ toolCall, addToolOutput }) => {
       // Handle client-side tool execution
       await addToolOutput({
         toolCallId: toolCall.toolCallId,
         output: { result: "success" }
       });
     }
   });

   Dynamic Tool Approval

   Use needsApproval on server tools to conditionally require user confirmation:

   TypeScript

   const paymentTool = tool({
     description: "Process a payment",
     inputSchema: z.object({
       amount: z.number(),
       recipient: z.string()
     }),
     needsApproval: async ({ amount }) => amount > 1000,
     execute: async ({ amount, recipient }) => {
       return await processPayment(amount, recipient);
     }
   });

   Tool Confirmation Detection

   The isToolUIPart and getToolName functions now check both static and dynamic tool parts:

   TypeScript

   import { isToolUIPart, getToolName } from "ai";
   
   const pendingToolCallConfirmation = messages.some((m) =>
     m.parts?.some(
       (part) => isToolUIPart(part) && part.state === "input-available",
     ),
   );
   
   // Handle tool confirmation
   if (pendingToolCallConfirmation) {
     await addToolOutput({
       toolCallId: part.toolCallId,
       output: "User approved the action"
     });
   }

   If you need the v5 behavior (static-only checks), use the new functions:

   TypeScript

   import { isStaticToolUIPart, getStaticToolName } from "ai";

   convertToModelMessages() is now async

   The convertToModelMessages() function is now asynchronous. Update all calls to await the result:

   TypeScript

   import { convertToModelMessages } from "ai";
   
   const result = streamText({
     messages: await convertToModelMessages(this.messages),
     model: openai("gpt-4o")
   });

   ModelMessage type

   The CoreMessage type has been removed. Use ModelMessage instead:

   TypeScript

   import { convertToModelMessages, type ModelMessage } from "ai";
   
   const modelMessages: ModelMessage[] = await convertToModelMessages(messages);

   generateObject mode option removed

   The mode option for generateObject has been removed:

   TypeScript

   // Before (v5)
   const result = await generateObject({
     mode: "json",
     model,
     schema,
     prompt
   });
   
   // After (v6)
   const result = await generateObject({
     model,
     schema,
     prompt
   });

   Structured Output with generateText

   While generateObject and streamObject are still functional, the recommended approach is to use generateText/streamText with the Output.object() helper:

   TypeScript

   import { generateText, Output, stepCountIs } from "ai";
   
   const { output } = await generateText({
     model: openai("gpt-4"),
     output: Output.object({
       schema: z.object({ name: z.string() })
     }),
     stopWhen: stepCountIs(2),
     prompt: "Generate a name"
   });

   Note: When using structured output with generateText, you must configure multiple steps with stopWhen because generating the structured output is itself a step.

   workers-ai-provider v3.0.0

   Seamless integration with Cloudflare Workers AI models through the updated workers-ai-provider v3.0.0 with AI SDK v6 support.

   Model Setup with Workers AI

   Use Cloudflare Workers AI models directly in your agent workflows:

   TypeScript

   import { createWorkersAI } from "workers-ai-provider";
   import { useAgentChat } from "agents/ai-react";
   
   // Create Workers AI model (v3.0.0 - enhanced v6 internals)
   const model = createWorkersAI({
     binding: env.AI,
   })("@cf/meta/llama-3.2-3b-instruct");

   Enhanced File and Image Support

   Workers AI models now support v6 file handling with automatic conversion:

   TypeScript

   // Send images and files to Workers AI models
   sendMessage({
     role: "user",
     parts: [
       { type: "text", text: "Analyze this image:" },
       {
         type: "file",
         data: imageBuffer,
         mediaType: "image/jpeg",
       },
     ],
   });
   
   // Workers AI provider automatically converts to proper format

   Streaming with Workers AI

   Enhanced streaming support with automatic warning detection:

   TypeScript

   // Streaming with Workers AI models
   const result = await streamText({
     model: createWorkersAI({ binding: env.AI })("@cf/meta/llama-3.2-3b-instruct"),
     messages: await convertToModelMessages(messages),
     onChunk: (chunk) => {
       // Enhanced streaming with warning handling
       console.log(chunk);
     },
   });

   ai-gateway-provider v3.0.0

   The ai-gateway-provider v3.0.0 now supports AI SDK v6, enabling you to use Cloudflare AI Gateway with multiple AI providers including Anthropic, Azure, AWS Bedrock, Google Vertex, and Perplexity.

   AI Gateway Setup

   Use Cloudflare AI Gateway to add analytics, caching, and rate limiting to your AI applications:

   TypeScript

   import { createAIGateway } from "ai-gateway-provider";
   
   // Create AI Gateway provider (v3.0.0 - enhanced v6 internals)
   const model = createAIGateway({
     gatewayUrl: "https://gateway.ai.cloudflare.com/v1/your-account-id/gateway",
     headers: {
       "Authorization": `Bearer ${env.AI_GATEWAY_TOKEN}`
     }
   })({
     provider: "openai",
     model: "gpt-4o"
   });

   Migration from v5

   Deprecated APIs

   The following APIs are deprecated in favor of the unified tool pattern:

   Deprecated	Replacement
   AITool type	Use AI SDK's tool() function on server
   extractClientToolSchemas()	Define tools on server, no client schemas needed
   createToolsFromClientSchemas()	Define tools on server with tool()
   toolsRequiringConfirmation option	Use needsApproval on server tools
   experimental_automaticToolResolution	Use onToolCall callback
   tools option in useAgentChat	Use onToolCall for client-side execution
   addToolResult()	Use addToolOutput()

   Breaking Changes Summary

   1. Unified Tool Pattern: All tools must be defined on the server using tool()
   2. convertToModelMessages() is async: Add await to all calls
   3. CoreMessage removed: Use ModelMessage instead
   4. generateObject mode removed: Remove mode option
   5. isToolUIPart behavior changed: Now checks both static and dynamic tool parts

   Installation

   Update your dependencies to use the latest versions:

   npm install agents@^0.3.0 workers-ai-provider@^3.0.0 ai-gateway-provider@^3.0.0 ai@^6.0.0 @ai-sdk/react@^3.0.0 @ai-sdk/openai@^3.0.0

   Resources

   • Migration Guide ↗ - Comprehensive migration documentation from v5 to v6
   • AI SDK v6 Documentation ↗ - Official AI SDK migration guide
   • AI SDK v6 Announcement ↗ - Learn about new features in v6
   • AI SDK Documentation ↗ - Complete AI SDK reference
   • GitHub Issues ↗ - Report bugs or request features

   Feedback Welcome

   We'd love your feedback! We're particularly interested in feedback on:

   • Migration experience - How smooth was the upgrade from v5 to v6?
   • Unified tool pattern - How does the new server-defined tool pattern work for you?
   • Dynamic tool approval - Does the needsApproval feature meet your needs?
   • AI Gateway integration - How well does the new provider work with your setup?

Nov 26, 2025

1. Agents SDK v0.2.24 with resumable streaming, MCP improvements, and schedule fixes

   Agents Workers

   The latest release of @cloudflare/agents ↗ brings resumable streaming, significant MCP client improvements, and critical fixes for schedules and Durable Object lifecycle management.

   Resumable streaming

   AIChatAgent now supports resumable streaming, allowing clients to reconnect and continue receiving streamed responses without losing data. This is useful for:

   • Long-running AI responses
   • Users on unreliable networks
   • Users switching between devices mid-conversation
   • Background tasks where users navigate away and return
   • Real-time collaboration where multiple clients need to stay in sync

   Streams are maintained across page refreshes, broken connections, and syncing across open tabs and devices.

   Other improvements

   • Default JSON schema validator added to MCP client
   • Schedules ↗ can now safely destroy the agent

   MCP client API improvements

   The MCPClientManager API has been redesigned for better clarity and control:

   • New registerServer() method: Register MCP servers without immediately connecting
   • New connectToServer() method: Establish connections to registered servers
   • Improved reconnect logic: restoreConnectionsFromStorage() now properly handles failed connections

   TypeScript

   // Register a server to Agent
   const { id } = await this.mcp.registerServer({
     name: "my-server",
     url: "https://my-mcp-server.example.com",
   });
   
   // Connect when ready
   await this.mcp.connectToServer(id);
   
   // Discover tools, prompts and resources
   await this.mcp.discoverIfConnected(id);

   The SDK now includes a formalized MCPConnectionState enum with states: idle, connecting, authenticating, connected, discovering, and ready.

   Enhanced MCP discovery

   MCP discovery fetches the available tools, prompts, and resources from an MCP server so your agent knows what capabilities are available. The MCPClientConnection class now includes a dedicated discover() method with improved reliability:

   • Supports cancellation via AbortController
   • Configurable timeout (default 15s)
   • Discovery failures now throw errors immediately instead of silently continuing

   Bug fixes

   • Fixed a bug where schedules ↗ meant to fire immediately with this.schedule(0, ...) or this.schedule(new Date(), ...) would not fire
   • Fixed an issue where schedules that took longer than 30 seconds would occasionally time out
   • Fixed SSE transport now properly forwards session IDs and request headers
   • Fixed AI SDK stream events convertion to UIMessageStreamPart

   Upgrade

   To update to the latest version:

   npm i agents@latest

Sep 10, 2025

1. Agents SDK v0.1.0 and workers-ai-provider v2.0.0 with AI SDK v5 support

   Agents Workers

   We've shipped a new release for the Agents SDK ↗ bringing full compatibility with AI SDK v5 ↗ and introducing automatic message migration that handles all legacy formats transparently.

   This release includes improved streaming and tool support, tool confirmation detection (for "human in the loop" systems), enhanced React hooks with automatic tool resolution, improved error handling for streaming responses, and seamless migration utilities that work behind the scenes.

   This makes it ideal for building production AI chat interfaces with Cloudflare Workers AI models, agent workflows, human-in-the-loop systems, or any application requiring reliable message handling across SDK versions — all while maintaining backward compatibility.

   Additionally, we've updated workers-ai-provider v2.0.0, the official provider for Cloudflare Workers AI models, to be compatible with AI SDK v5.

   useAgentChat(options)

   Creates a new chat interface with enhanced v5 capabilities.

   TypeScript

   // Basic chat setup
   const { messages, sendMessage, addToolResult } = useAgentChat({
     agent,
     experimental_automaticToolResolution: true,
     tools,
   });
   
   // With custom tool confirmation
   const chat = useAgentChat({
     agent,
     experimental_automaticToolResolution: true,
     toolsRequiringConfirmation: ["dangerousOperation"],
   });

   Automatic Tool Resolution

   Tools are automatically categorized based on their configuration:

   TypeScript

   const tools = {
     // Auto-executes (has execute function)
     getLocalTime: {
       description: "Get current local time",
       inputSchema: z.object({}),
       execute: async () => new Date().toLocaleString(),
     },
   
     // Requires confirmation (no execute function)
     deleteFile: {
       description: "Delete a file from the system",
       inputSchema: z.object({
         filename: z.string(),
       }),
     },
   
     // Server-executed (no client confirmation)
     analyzeData: {
       description: "Analyze dataset on server",
       inputSchema: z.object({ data: z.array(z.number()) }),
       serverExecuted: true,
     },
   } satisfies Record<string, AITool>;

   Message Handling

   Send messages using the new v5 format with parts array:

   TypeScript

   // Text message
   sendMessage({
     role: "user",
     parts: [{ type: "text", text: "Hello, assistant!" }],
   });
   
   // Multi-part message with file
   sendMessage({
     role: "user",
     parts: [
       { type: "text", text: "Analyze this image:" },
       { type: "image", image: imageData },
     ],
   });

   Tool Confirmation Detection

   Simplified logic for detecting pending tool confirmations:

   TypeScript

   const pendingToolCallConfirmation = messages.some((m) =>
     m.parts?.some(
       (part) => isToolUIPart(part) && part.state === "input-available",
     ),
   );
   
   // Handle tool confirmation
   if (pendingToolCallConfirmation) {
     await addToolResult({
       toolCallId: part.toolCallId,
       tool: getToolName(part),
       output: "User approved the action",
     });
   }

   Automatic Message Migration

   Seamlessly handle legacy message formats without code changes.

   TypeScript

   // All these formats are automatically converted:
   
   // Legacy v4 string content
   const legacyMessage = {
     role: "user",
     content: "Hello world",
   };
   
   // Legacy v4 with tool calls
   const legacyWithTools = {
     role: "assistant",
     content: "",
     toolInvocations: [
       {
         toolCallId: "123",
         toolName: "weather",
         args: { city: "SF" },
         state: "result",
         result: "Sunny, 72°F",
       },
     ],
   };
   
   // Automatically becomes v5 format:
   // {
   //   role: "assistant",
   //   parts: [{
   //     type: "tool-call",
   //     toolCallId: "123",
   //     toolName: "weather",
   //     args: { city: "SF" },
   //     state: "result",
   //     result: "Sunny, 72°F"
   //   }]
   // }

   Tool Definition Updates

   Migrate tool definitions to use the new inputSchema property.

   TypeScript

   // Before (AI SDK v4)
   const tools = {
     weather: {
       description: "Get weather information",
       parameters: z.object({
         city: z.string(),
       }),
       execute: async (args) => {
         return await getWeather(args.city);
       },
     },
   };
   
   // After (AI SDK v5)
   const tools = {
     weather: {
       description: "Get weather information",
       inputSchema: z.object({
         city: z.string(),
       }),
       execute: async (args) => {
         return await getWeather(args.city);
       },
     },
   };

   Cloudflare Workers AI Integration

   Seamless integration with Cloudflare Workers AI models through the updated workers-ai-provider v2.0.0.

   Model Setup with Workers AI

   Use Cloudflare Workers AI models directly in your agent workflows:

   TypeScript

   import { createWorkersAI } from "workers-ai-provider";
   import { useAgentChat } from "agents/ai-react";
   
   // Create Workers AI model (v2.0.0 - same API, enhanced v5 internals)
   const model = createWorkersAI({
     binding: env.AI,
   })("@cf/meta/llama-3.2-3b-instruct");

   Enhanced File and Image Support

   Workers AI models now support v5 file handling with automatic conversion:

   TypeScript

   // Send images and files to Workers AI models
   sendMessage({
     role: "user",
     parts: [
       { type: "text", text: "Analyze this image:" },
       {
         type: "file",
         data: imageBuffer,
         mediaType: "image/jpeg",
       },
     ],
   });
   
   // Workers AI provider automatically converts to proper format

   Streaming with Workers AI

   Enhanced streaming support with automatic warning detection:

   TypeScript

   // Streaming with Workers AI models
   const result = await streamText({
     model: createWorkersAI({ binding: env.AI })("@cf/meta/llama-3.2-3b-instruct"),
     messages,
     onChunk: (chunk) => {
       // Enhanced streaming with warning handling
       console.log(chunk);
     },
   });

   Import Updates

   Update your imports to use the new v5 types:

   TypeScript

   // Before (AI SDK v4)
   import type { Message } from "ai";
   import { useChat } from "ai/react";
   
   // After (AI SDK v5)
   import type { UIMessage } from "ai";
   // or alias for compatibility
   import type { UIMessage as Message } from "ai";
   import { useChat } from "@ai-sdk/react";

   Resources

   • Migration Guide ↗ - Comprehensive migration documentation
   • AI SDK v5 Documentation ↗ - Official AI SDK migration guide
   • An Example PR showing the migration from AI SDK v4 to v5 ↗
   • GitHub Issues ↗ - Report bugs or request features

   Feedback Welcome

   We'd love your feedback! We're particularly interested in feedback on:

   • Migration experience - How smooth was the upgrade process?
   • Tool confirmation workflow - Does the new automatic detection work as expected?
   • Message format handling - Any edge cases with legacy message conversion?

Aug 05, 2025

1. Agents SDK adds MCP Elicitation support, http-streamable suppport, task queues, email integration and more

   Agents Workers

   The latest releases of @cloudflare/agents ↗ brings major improvements to MCP transport protocols support and agents connectivity. Key updates include:

   MCP elicitation support

   MCP servers can now request user input during tool execution, enabling interactive workflows like confirmations, forms, and multi-step processes. This feature uses durable storage to preserve elicitation state even during agent hibernation, ensuring seamless user interactions across agent lifecycle events.

   TypeScript

   // Request user confirmation via elicitation
   const confirmation = await this.elicitInput({
     message: `Are you sure you want to increment the counter by ${amount}?`,
     requestedSchema: {
       type: "object",
       properties: {
         confirmed: {
           type: "boolean",
           title: "Confirm increment",
           description: "Check to confirm the increment",
         },
       },
       required: ["confirmed"],
     },
   });

   Check out our demo ↗ to see elicitation in action.

   HTTP streamable transport for MCP

   MCP now supports HTTP streamable transport which is recommended over SSE. This transport type offers:

   • Better performance: More efficient data streaming and reduced overhead
   • Improved reliability: Enhanced connection stability and error recover- Automatic fallback: If streamable transport is not available, it gracefully falls back to SSE

   TypeScript

   export default MyMCP.serve("/mcp", {
     binding: "MyMCP",
   });

   The SDK automatically selects the best available transport method, gracefully falling back from streamable-http to SSE when needed.

   Enhanced MCP connectivity

   Significant improvements to MCP server connections and transport reliability:

   • Auto transport selection: Automatically determines the best transport method, falling back from streamable-http to SSE as needed
   • Improved error handling: Better connection state management and error reporting for MCP servers
   • Reliable prop updates: Centralized agent property updates ensure consistency across different contexts

   Lightweight .queue for fast task deferral

   You can use .queue() to enqueue background work — ideal for tasks like processing user messages, sending notifications etc.

   TypeScript

   class MyAgent extends Agent {
     doSomethingExpensive(payload) {
       // a long running process that you want to run in the background
     }
   
     queueSomething() {
       await this.queue("doSomethingExpensive", somePayload); // this will NOT block further execution, and runs in the background
       await this.queue("doSomethingExpensive", someOtherPayload); // the callback will NOT run until the previous callback is complete
       // ... call as many times as you want
     }
   }

   Want to try it yourself? Just define a method like processMessage in your agent, and you’re ready to scale.

   New email adapter

   Want to build an AI agent that can receive and respond to emails automatically? With the new email adapter and onEmail lifecycle method, now you can.

   TypeScript

   export class EmailAgent extends Agent {
     async onEmail(email: AgentEmail) {
       const raw = await email.getRaw();
       const parsed = await PostalMime.parse(raw);
   
       // create a response based on the email contents
       // and then send a reply
   
       await this.replyToEmail(email, {
         fromName: "Email Agent",
         body: `Thanks for your email! You've sent us "${parsed.subject}". We'll process it shortly.`,
       });
     }
   }

   You route incoming mail like this:

   TypeScript

   export default {
     async email(email, env) {
       await routeAgentEmail(email, env, {
         resolver: createAddressBasedEmailResolver("EmailAgent"),
       });
     },
   };

   You can find a full example here ↗.

   Automatic context wrapping for custom methods

   Custom methods are now automatically wrapped with the agent's context, so calling getCurrentAgent() should work regardless of where in an agent's lifecycle it's called. Previously this would not work on RPC calls, but now just works out of the box.

   TypeScript

   export class MyAgent extends Agent {
     async suggestReply(message) {
       // getCurrentAgent() now correctly works, even when called inside an RPC method
       const { agent } = getCurrentAgent()!;
       return generateText({
         prompt: `Suggest a reply to: "${message}" from "${agent.name}"`,
         tools: [replyWithEmoji],
       });
     }
   }

   Try it out and tell us what you build!

Aug 05, 2025

1. Cloudflare Sandbox SDK adds streaming, code interpreter, Git support, process control and more

   Agents Workers

   We’ve shipped a major release for the @cloudflare/sandbox ↗ SDK, turning it into a full-featured, container-based execution platform that runs securely on Cloudflare Workers.

   This update adds live streaming of output, persistent Python and JavaScript code interpreters with rich output support (charts, tables, HTML, JSON), file system access, Git operations, full background process control, and the ability to expose running services via public URLs.

   This makes it ideal for building AI agents, CI runners, cloud REPLs, data analysis pipelines, or full developer tools — all without managing infrastructure.

   Code interpreter (Python, JS, TS)

   Create persistent code contexts with support for rich visual + structured outputs.

   createCodeContext(options)

   Creates a new code execution context with persistent state.

   TypeScript

   // Create a Python context
   const pythonCtx = await sandbox.createCodeContext({ language: "python" });
   
   // Create a JavaScript context
   const jsCtx = await sandbox.createCodeContext({ language: "javascript" });

   Options:

   • language: Programming language ('python' | 'javascript' | 'typescript')
   • cwd: Working directory (default: /workspace)
   • envVars: Environment variables for the context

   runCode(code, options)

   Executes code with optional streaming callbacks.

   TypeScript

   // Simple execution
   const execution = await sandbox.runCode('print("Hello World")', {
     context: pythonCtx,
   });
   
   // With streaming callbacks
   await sandbox.runCode(
     `
   for i in range(5):
       print(f"Step {i}")
       time.sleep(1)
   `,
     {
       context: pythonCtx,
       onStdout: (output) => console.log("Real-time:", output.text),
       onResult: (result) => console.log("Result:", result),
     },
   );

   Options:

   • language: Programming language ('python' | 'javascript' | 'typescript')
   • cwd: Working directory (default: /workspace)
   • envVars: Environment variables for the context

   Real-time streaming output

   Returns a streaming response for real-time processing.

   TypeScript

   const stream = await sandbox.runCodeStream(
     "import time; [print(i) for i in range(10)]",
   );
   // Process the stream as needed

   Rich output handling

   Interpreter outputs are auto-formatted and returned in multiple formats:

   • text
   • html (e.g., Pandas tables)
   • png, svg (e.g., Matplotlib charts)
   • json (structured data)
   • chart (parsed visualizations)

   TypeScript

   const result = await sandbox.runCode(
     `
   import seaborn as sns
   import matplotlib.pyplot as plt
   
   data = sns.load_dataset("flights")
   pivot = data.pivot("month", "year", "passengers")
   sns.heatmap(pivot, annot=True, fmt="d")
   plt.title("Flight Passengers")
   plt.show()
   
   pivot.to_dict()
   `,
     { context: pythonCtx },
   );
   
   if (result.png) {
     console.log("Chart output:", result.png);
   }

   Preview URLs from Exposed Ports

   Start background processes and expose them with live URLs.

   TypeScript

   await sandbox.startProcess("python -m http.server 8000");
   const preview = await sandbox.exposePort(8000);
   
   console.log("Live preview at:", preview.url);

   Full process lifecycle control

   Start, inspect, and terminate long-running background processes.

   TypeScript

   const process = await sandbox.startProcess("node server.js");
   console.log(`Started process ${process.id} with PID ${process.pid}`);
   
   // Monitor the process
   const logStream = await sandbox.streamProcessLogs(process.id);
   for await (const log of parseSSEStream<LogEvent>(logStream)) {
     console.log(`Server: ${log.data}`);
   }

   • listProcesses() - List all running processes
   • getProcess(id) - Get detailed process status
   • killProcess(id, signal) - Terminate specific processes
   • killAllProcesses() - Kill all processes
   • streamProcessLogs(id, options) - Stream logs from running processes
   • getProcessLogs(id) - Get accumulated process output

   Git integration

   Clone Git repositories directly into the sandbox.

   TypeScript

   await sandbox.gitCheckout("https://github.com/user/repo", {
     branch: "main",
     targetDir: "my-project",
   });

   Sandboxes are still experimental. We're using them to explore how isolated, container-like workloads might scale on Cloudflare — and to help define the developer experience around them.

Aug 05, 2025

1. OpenAI open models now available on Workers AI

   Agents Workers AI

   We're thrilled to be a Day 0 partner with OpenAI ↗ to bring their latest open models ↗ to Workers AI, including support for Responses API, Code Interpreter, and Web Search (coming soon).

   Get started with the new models at @cf/openai/gpt-oss-120b and @cf/openai/gpt-oss-20b. Check out the blog ↗ for more details about the new models, and the gpt-oss-120b and gpt-oss-20b model pages for more information about pricing and context windows.

   Responses API

   If you call the model through:

   • Workers Binding, it will accept/return Responses API – env.AI.run(“@cf/openai/gpt-oss-120b”)
   • REST API on /run endpoint, it will accept/return Responses API – https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/run/@cf/openai/gpt-oss-120b
   • REST API on new /responses endpoint, it will accept/return Responses API – https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/v1/responses
   • REST API for OpenAI Compatible endpoint, it will return Chat Completions (coming soon) – https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/v1/chat/completions

   curl https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/v1/responses \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $CLOUDFLARE_API_KEY" \
     -d '{
       "model": "@cf/openai/gpt-oss-120b",
       "reasoning": {"effort": "medium"},
       "input": [
         {
           "role": "user",
           "content": "What are the benefits of open-source models?"
         }
       ]
     }'

   Code Interpreter

   The model is natively trained to support stateful code execution, and we've implemented support for this feature using our Sandbox SDK ↗ and Containers ↗. Cloudflare's Developer Platform is uniquely positioned to support this feature, so we're very excited to bring our products together to support this new use case.

   Web Search (coming soon)

   We are working to implement Web Search for the model, where users can bring their own Exa API Key so the model can browse the Internet.

Jun 25, 2025

1. Run AI-generated code on-demand with Code Sandboxes (new)

   Agents Workers Workflows

   AI is supercharging app development for everyone, but we need a safe way to run untrusted, LLM-written code. We’re introducing Sandboxes ↗, which let your Worker run actual processes in a secure, container-based environment.

   TypeScript

   import { getSandbox } from "@cloudflare/sandbox";
   export { Sandbox } from "@cloudflare/sandbox";
   
   export default {
     async fetch(request: Request, env: Env) {
       const sandbox = getSandbox(env.Sandbox, "my-sandbox");
       return sandbox.exec("ls", ["-la"]);
     },
   };

   Methods

   • exec(command: string, args: string[], options?: { stream?: boolean }):Execute a command in the sandbox.
   • gitCheckout(repoUrl: string, options: { branch?: string; targetDir?: string; stream?: boolean }): Checkout a git repository in the sandbox.
   • mkdir(path: string, options: { recursive?: boolean; stream?: boolean }): Create a directory in the sandbox.
   • writeFile(path: string, content: string, options: { encoding?: string; stream?: boolean }): Write content to a file in the sandbox.
   • readFile(path: string, options: { encoding?: string; stream?: boolean }): Read content from a file in the sandbox.
   • deleteFile(path: string, options?: { stream?: boolean }): Delete a file from the sandbox.
   • renameFile(oldPath: string, newPath: string, options?: { stream?: boolean }): Rename a file in the sandbox.
   • moveFile(sourcePath: string, destinationPath: string, options?: { stream?: boolean }): Move a file from one location to another in the sandbox.
   • ping(): Ping the sandbox.

   Sandboxes are still experimental. We're using them to explore how isolated, container-like workloads might scale on Cloudflare — and to help define the developer experience around them.

   You can try it today from your Worker, with just a few lines of code. Let us know what you build.

Apr 07, 2025

1. Build MCP servers with the Agents SDK

   Agents Workers

   The Agents SDK now includes built-in support for building remote MCP (Model Context Protocol) servers directly as part of your Agent. This allows you to easily create and manage MCP servers, without the need for additional infrastructure or configuration.

   The SDK includes a new MCPAgent class that extends the Agent class and allows you to expose resources and tools over the MCP protocol, as well as authorization and authentication to enable remote MCP servers.

   JavaScript

   JavaScript

   export class MyMCP extends McpAgent {
     server = new McpServer({
       name: "Demo",
       version: "1.0.0",
     });
   
     async init() {
       this.server.resource(`counter`, `mcp://resource/counter`, (uri) => {
         // ...
       });
   
       this.server.tool(
         "add",
         "Add two numbers together",
         { a: z.number(), b: z.number() },
         async ({ a, b }) => {
           // ...
         },
       );
     }
   }

   TypeScript

   TypeScript

   export class MyMCP extends McpAgent<Env> {
     server = new McpServer({
       name: "Demo",
       version: "1.0.0",
     });
   
     async init() {
       this.server.resource(`counter`, `mcp://resource/counter`, (uri) => {
         // ...
       });
   
       this.server.tool(
         "add",
         "Add two numbers together",
         { a: z.number(), b: z.number() },
         async ({ a, b }) => {
           // ...
         },
       );
     }
   }

   See the example ↗ for the full code and as the basis for building your own MCP servers, and the client example ↗ for how to build an Agent that acts as an MCP client.

   To learn more, review the announcement blog ↗ as part of Developer Week 2025.

   Agents SDK updates

   We've made a number of improvements to the Agents SDK, including:

   • Support for building MCP servers with the new MCPAgent class.
   • The ability to export the current agent, request and WebSocket connection context using import { context } from "agents", allowing you to minimize or avoid direct dependency injection when calling tools.
   • Fixed a bug that prevented query parameters from being sent to the Agent server from the useAgent React hook.
   • Automatically converting the agent name in useAgent or useAgentChat to kebab-case to ensure it matches the naming convention expected by routeAgentRequest.

   To install or update the Agents SDK, run npm i agents@latest in an existing project, or explore the agents-starter project:

   npm create cloudflare@latest -- --template cloudflare/agents-starter

   See the full release notes and changelog on the Agents SDK repository ↗ and

Mar 18, 2025

1. npm i agents

   Agents Workers
   

   agents-sdk -> agents Updated

   📝 We've renamed the Agents package to agents!

   If you've already been building with the Agents SDK, you can update your dependencies to use the new package name, and replace references to agents-sdk with agents:

   # Install the new package
   npm i agents

   # Remove the old (deprecated) package
   npm uninstall agents-sdk
   
   # Find instances of the old package name in your codebase
   grep -r 'agents-sdk' .
   # Replace instances of the old package name with the new one
   # (or use find-replace in your editor)
   sed -i 's/agents-sdk/agents/g' $(grep -rl 'agents-sdk' .)

   All future updates will be pushed to the new agents package, and the older package has been marked as deprecated.

   Agents SDK updates New

   We've added a number of big new features to the Agents SDK over the past few weeks, including:

   • You can now set cors: true when using routeAgentRequest to return permissive default CORS headers to Agent responses.
   • The regular client now syncs state on the agent (just like the React version).
   • useAgentChat bug fixes for passing headers/credentials, including properly clearing cache on unmount.
   • Experimental /schedule module with a prompt/schema for adding scheduling to your app (with evals!).
   • Changed the internal zod schema to be compatible with the limitations of Google's Gemini models by removing the discriminated union, allowing you to use Gemini models with the scheduling API.

   We've also fixed a number of bugs with state synchronization and the React hooks.

   JavaScript

   JavaScript

   // via https://github.com/cloudflare/agents/tree/main/examples/cross-domain
   export default {
     async fetch(request, env) {
       return (
         // Set { cors: true } to enable CORS headers.
         (await routeAgentRequest(request, env, { cors: true })) ||
         new Response("Not found", { status: 404 })
       );
     },
   };

   TypeScript

   TypeScript

   // via https://github.com/cloudflare/agents/tree/main/examples/cross-domain
   export default {
     async fetch(request: Request, env: Env) {
       return (
         // Set { cors: true } to enable CORS headers.
         (await routeAgentRequest(request, env, { cors: true })) ||
         new Response("Not found", { status: 404 })
       );
     },
   } satisfies ExportedHandler<Env>;

   Call Agent methods from your client code New

   We've added a new @unstable_callable() decorator for defining methods that can be called directly from clients. This allows you call methods from within your client code: you can call methods (with arguments) and get native JavaScript objects back.

   JavaScript

   JavaScript

   // server.ts
   import { unstable_callable, Agent } from "agents";
   export class Rpc extends Agent {
     // Use the decorator to define a callable method
     @unstable_callable({
       description: "rpc test",
     })
     async getHistory() {
       return this.sql`SELECT * FROM history ORDER BY created_at DESC LIMIT 10`;
     }
   }

   TypeScript

   TypeScript

   // server.ts
   import { unstable_callable, Agent, type StreamingResponse } from "agents";
   import type { Env } from "../server";
   
   export class Rpc extends Agent<Env> {
     // Use the decorator to define a callable method
     @unstable_callable({
       description: "rpc test",
     })
     async getHistory() {
       return this.sql`SELECT * FROM history ORDER BY created_at DESC LIMIT 10`;
     }
   }

   agents-starter Updated

   We've fixed a number of small bugs in the agents-starter ↗ project — a real-time, chat-based example application with tool-calling & human-in-the-loop built using the Agents SDK. The starter has also been upgraded to use the latest wrangler v4 release.

   If you're new to Agents, you can install and run the agents-starter project in two commands:

   # Install it
   $ npm create cloudflare@latest agents-starter -- --template="cloudflare/agents-starter"
   # Run it
   $ npm run start

   You can use the starter as a template for your own Agents projects: open up src/server.ts and src/client.tsx to see how the Agents SDK is used.

   More documentation Updated

   We've heard your feedback on the Agents SDK documentation, and we're shipping more API reference material and usage examples, including:

   • Expanded API reference documentation, covering the methods and properties exposed by the Agents SDK, as well as more usage examples.
   • More Client API documentation that documents useAgent, useAgentChat and the new @unstable_callable RPC decorator exposed by the SDK.
   • New documentation on how to route requests to agents and (optionally) authenticate clients before they connect to your Agents.

   Note that the Agents SDK is continually growing: the type definitions included in the SDK will always include the latest APIs exposed by the agents package.

   If you're still wondering what Agents are, read our blog on building AI Agents on Cloudflare ↗ and/or visit the Agents documentation to learn more.

Feb 25, 2025

1. Introducing the Agents SDK

   Agents Workers

   We've released the Agents SDK ↗, a package and set of tools that help you build and ship AI Agents.

   You can get up and running with a chat-based AI Agent ↗ (and deploy it to Workers) that uses the Agents SDK, tool calling, and state syncing with a React-based front-end by running the following command:

   npm create cloudflare@latest agents-starter -- --template="cloudflare/agents-starter"
   # open up README.md and follow the instructions

   You can also add an Agent to any existing Workers application by installing the agents package directly

   npm i agents

   ... and then define your first Agent:

   TypeScript

   import { Agent } from "agents";
   
   export class YourAgent extends Agent<Env> {
     // Build it out
     // Access state on this.state or query the Agent's database via this.sql
     // Handle WebSocket events with onConnect and onMessage
     // Run tasks on a schedule with this.schedule
     // Call AI models
     // ... and/or call other Agents.
   }

   Head over to the Agents documentation to learn more about the Agents SDK, the SDK APIs, as well as how to test and deploying agents to production.

Feb 14, 2025

1. Build AI Agents with Example Prompts

   Agents Workers Workflows

   We've added an example prompt to help you get started with building AI agents and applications on Cloudflare Workers, including Workflows, Durable Objects, and Workers KV.

   You can use this prompt with your favorite AI model, including Claude 3.5 Sonnet, OpenAI's o3-mini, Gemini 2.0 Flash, or Llama 3.3 on Workers AI. Models with large context windows will allow you to paste the prompt directly: provide your own prompt within the <user_prompt></user_prompt> tags.

   {paste_prompt_here}
   <user_prompt>
   user: Build an AI agent using Cloudflare Workflows. The Workflow should run when a new GitHub issue is opened on a specific project with the label 'help' or 'bug', and attempt to help the user troubleshoot the issue by calling the OpenAI API with the issue title and description, and a clear, structured prompt that asks the model to suggest 1-3 possible solutions to the issue. Any code snippets should be formatted in Markdown code blocks. Documentation and sources should be referenced at the bottom of the response. The agent should then post the response to the GitHub issue. The agent should run as the provided GitHub bot account.
   </user_prompt>

   This prompt is still experimental, but we encourage you to try it out and provide feedback ↗.

Search all changelog entries