Changelog

The Workers runtime now provides built-in tracing.startActiveSpan() and span.end() APIs, allowing you to write custom spans for operations that last beyond a single callback — for example, instrumenting a stream pipeline where the span should stay open until the stream is fully consumed.

This augments the existing API for writing custom spans, tracing.enterSpan(), which automatically ends a span when its callback is returned. With startActiveSpan(), the span remains open after the callback returns, and you call span.end() when the work is complete:

import { tracing } from "cloudflare:workers";

const encoder = new TextEncoder();

export default {
	fetch() {
		return tracing.startActiveSpan("stream-response", (span) => {
			let timer;

			const body = new ReadableStream({
				start(controller) {
					controller.enqueue(encoder.encode("Starting...\n"));

					timer = setTimeout(() => {
						controller.enqueue(encoder.encode("Complete.\n"));
						controller.close();

						span.setAttribute("stream.status", "complete");
						span.end();
					}, 1000);
				},

				cancel() {
					if (timer !== undefined) clearTimeout(timer);

					span.setAttribute("stream.status", "cancelled");
					span.end();
				},
			});

			return new Response(body, {
				headers: { "content-type": "text/plain" },
			});
		});
	},
};

import { tracing } from "cloudflare:workers";

const encoder = new TextEncoder();

export default {
	fetch(): Response {
		return tracing.startActiveSpan("stream-response", (span) => {
			let timer: ReturnType<typeof setTimeout> | undefined;

			const body = new ReadableStream<Uint8Array>({
				start(controller) {
					controller.enqueue(encoder.encode("Starting...\n"));

					timer = setTimeout(() => {
						controller.enqueue(encoder.encode("Complete.\n"));
						controller.close();

						span.setAttribute("stream.status", "complete");
						span.end();
					}, 1000);
				},

				cancel() {
					if (timer !== undefined) clearTimeout(timer);

					span.setAttribute("stream.status", "cancelled");
					span.end();
				},
			});

			return new Response(body, {
				headers: { "content-type": "text/plain" },
			});
		});
	},
};

For more details, refer to the custom spans documentation.

Agents SDK v0.20.0 adds client and server support for the MCP 2026-07-28 release candidate ↗. Workers can serve tools, prompts, resources, and elicitation without an MCP transport session or Durable Object. Agents can connect to both MCP 2026-07-28 servers and existing legacy servers.

The MCP client manager now uses @modelcontextprotocol/client. For each connection, it probes for MCP 2026-07-28 support with server/discover. If the server does not support the stateless protocol, the client continues with the legacy initialize handshake on the same connection. Existing addMcpServer calls do not need a protocol-version setting or separate clients for each protocol generation.

For stateless requests, elicitation uses input_required through multi-round-trip requests (MRTR). The legacy path uses the same form and URL handlers for pushed requests. The SDK collects input, retries the original operation, and resolves the original callTool, getPrompt, or readResource promise with its final result.

OAuth callbacks now validate issuer metadata through the v2 SDK. Discovery state and issuer-bound credentials persist across browser redirects and Durable Object hibernation.

createMcpHandler now accepts a factory that returns a server from @modelcontextprotocol/server. The factory creates an isolated server for each request.

import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";

function createServer() {
	return new McpServer({ name: "example", version: "1.0.0" });
}

export default {
	fetch(request, env, ctx) {
		return createMcpHandler(createServer)(request, env, ctx);
	},
};

import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";

function createServer() {
	return new McpServer({ name: "example", version: "1.0.0" });
}

export default {
	fetch(request, env, ctx) {
		return createMcpHandler(createServer)(request, env, ctx);
	},
} satisfies ExportedHandler;

The isolated agents/mcp/server entry keeps McpAgent, WorkerTransport, MCP client transports, and SDK v1 modules out of stateless server bundles.

The Workers wrapper validates present browser Origins, supports explicit delegation to trusted Origin middleware, and exposes request handling plus typed change notifications.

The same createMcpHandler(createServer)(request, env, ctx) route serves MCP 2026-07-28 clients and legacy clients that use stateless requests. You do not need separate routes or tool definitions for ordinary tools, prompts, and resources.

McpAgent is deprecated and feature-frozen. Migrate existing McpAgent servers to the stateless handler at your earliest convenience. If a server depends on protocol sessions, RPC, pushed server-to-client requests, standalone streams, or replay, use the migration guide to design stateless equivalents and run both routes while clients transition.

Upgrade the Agents SDK:

npm i agents@latest

yarn add agents@latest

pnpm add agents@latest

bun add agents@latest

Move ordinary SDK v1 server definitions into an SDK v2 factory and serve them with createMcpHandler. The handler's default legacy compatibility means most stateless deployments need only one route.

If an existing McpAgent server still needs sessionful features, add the stateless path beside it. Use isLegacyRequest() to send only legacy traffic to the existing route:

import { isLegacyRequest } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";
import { MyMcpAgent } from "./legacy-server";
import { createServer } from "./server";

const stateless = createMcpHandler(createServer, {
	route: "/mcp",
	legacy: "reject",
});
const legacy = MyMcpAgent.serve("/mcp");

export default {
	async fetch(request, env, ctx) {
		if (await isLegacyRequest(request)) {
			return legacy.fetch(request, env, ctx);
		}
		return stateless(request, env, ctx);
	},
};

import { isLegacyRequest } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";
import { MyMcpAgent } from "./legacy-server";
import { createServer } from "./server";

const stateless = createMcpHandler(createServer, {
	route: "/mcp",
	legacy: "reject",
});
const legacy = MyMcpAgent.serve("/mcp");

export default {
	async fetch(request: Request, env: Env, ctx: ExecutionContext) {
		if (await isLegacyRequest(request)) {
			return legacy.fetch(request, env, ctx);
		}
		return stateless(request, env, ctx);
	},
} satisfies ExportedHandler<Env>;

Migrate the remaining sessionful features, allow existing sessions to drain, then remove the legacy route. Refer to Migrate to MCP SDK v2 for package changes, compatibility limits, and rollout steps.

This release deprecates the following Agents SDK APIs:

The MCP 2026-07-28 draft separately deprecates Roots, Sampling, Logging, the old HTTP+SSE transport, and Dynamic Client Registration.

Wrangler now provides createTestHarness(), an API for running integration tests against Workers built with Wrangler or the Cloudflare Vite plugin from any Node.js test runner.

The test harness starts a local Worker server with helpers for dispatching requests, resetting storage, and inspecting runtime logs.

This is useful for tests that need to:

• Route requests across multiple Workers
• Mock outbound fetch() requests with Node.js request mocking libraries such as MSW ↗
• Run Playwright tests against a Worker

For example, this test starts two Workers and mocks an upstream API:

import { afterAll, afterEach, beforeAll, test } from "vitest";
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";
import { createTestHarness } from "wrangler";

const network = setupServer();
const server = createTestHarness({
	workers: [
		/** Includes `"routes": ["example.com/*"]` */
		{ configPath: "./workers/web/wrangler.jsonc" },
		/** Includes `"routes": ["api.example.com/v1/*"]` */
		{ configPath: "./workers/api/wrangler.jsonc" },
	],
});

beforeAll(async () => {
	network.listen({ onUnhandledRequest: "error" });
	await server.listen();
});

afterEach(async () => {
	network.resetHandlers();
	await server.reset();
});

afterAll(async () => {
	network.close();
	await server.close();
});

test("routes requests to each Worker", async ({ expect }) => {
	// Mock the outbound fetch used to load user profiles.
	network.use(
		http.get("http://identity.example.com/profile/123", ({ params }) => {
			return HttpResponse.json({ id: 123, name: "Ada" });
		}),
	);

	const apiWorkerResponse = await server.fetch(
		"http://api.example.com/v1/users/123",
	);
	expect(await apiWorkerResponse.json()).toEqual({
		id: 123,
		name: "Ada",
	});

	const webWorkerResponse = await server.fetch("http://example.com/users/123");
	expect(await webWorkerResponse.text()).toBe("Profile: Ada");
});

import { afterAll, afterEach, beforeAll, test } from "vitest";
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";
import { createTestHarness } from "wrangler";

const network = setupServer();
const server = createTestHarness({
	workers: [
		/** Includes `"routes": ["example.com/*"]` */
		{ configPath: "./workers/web/wrangler.jsonc" },
		/** Includes `"routes": ["api.example.com/v1/*"]` */
		{ configPath: "./workers/api/wrangler.jsonc" },
	],
});

beforeAll(async () => {
	network.listen({ onUnhandledRequest: "error" });
	await server.listen();
});

afterEach(async () => {
	network.resetHandlers();
	await server.reset();
});

afterAll(async () => {
	network.close();
	await server.close();
});

test("routes requests to each Worker", async ({ expect }) => {
	// Mock the outbound fetch used to load user profiles.
	network.use(
		http.get("http://identity.example.com/profile/123", ({ params }) => {
			return HttpResponse.json({ id: 123, name: "Ada" });
		}),
	);

	const apiWorkerResponse = await server.fetch(
		"http://api.example.com/v1/users/123",
	);
	expect(await apiWorkerResponse.json()).toEqual({
		id: 123,
		name: "Ada",
	});

	const webWorkerResponse = await server.fetch("http://example.com/users/123");
	expect(await webWorkerResponse.text()).toBe("Profile: Ada");
});

Cloudflare now recommends createTestHarness() for integration tests instead of unstable_startWorker() or unstable_dev(). To start a development server programmatically, use the Vite createServer() ↗ API with the Cloudflare Vite plugin.

For more information about createTestHarness(), refer to the Integration test harness guide.

Sippy can now incrementally migrate data from Azure Blob Storage and any S3-compatible object storage provider to Cloudflare R2, in addition to Amazon S3 and Google Cloud Storage. Sippy copies objects to R2 as your application requests them, so you can start serving data from R2 without first moving your entire dataset or paying migration-specific egress fees.

Run the following command and follow the prompts to select and configure your source storage provider:

npx wrangler r2 bucket sippy enable <BUCKET_NAME>

For Azure Blob Storage, provide your storage account name, container name, and either an account key or a shared access signature (SAS) token with read and list permissions. For an S3-compatible provider, provide the S3 API endpoint URL and read-only Access Key ID and Secret Access Key.

After you enable Sippy, requests for objects that are not yet in R2 are served from your source bucket and copied to R2. Subsequent requests for those objects are served from R2.

For setup instructions and credential requirements, refer to the Sippy documentation.

Workers Builds now automatically skips a queued build when a newer build for the same build trigger is also queued.

The agents, @cloudflare/ai-chat, @cloudflare/codemode, and @cloudflare/think packages now support AI SDK v6 and v7. Existing applications can remain on v6 when updating these packages. Applications can also adopt v7 without changing the Cloudflare Agents APIs they use.

The supported peer ranges are ai@^6 || ^7 and @ai-sdk/react@^3 || ^4. Use matching major versions: pair AI SDK v6 with @ai-sdk/react v3, or pair AI SDK v7 with @ai-sdk/react v4.

To install the latest packages with AI SDK v7:

npm i agents@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/think@latest ai@^7 @ai-sdk/react@^4

yarn add agents@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/think@latest ai@^7 @ai-sdk/react@^4

pnpm add agents@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/think@latest ai@^7 @ai-sdk/react@^4

bun add agents@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/think@latest ai@^7 @ai-sdk/react@^4

Think normalizes streaming, tool completion events, and telemetry across both AI SDK versions. Existing v6 applications do not need to migrate these integrations before updating Think.

For setup and usage details, refer to the Think documentation.

This release reduces repeated MCP schema conversion and adds an opt-out for Think's automatic MCP tool exposure. It also lets non-AI-SDK hosts invoke the durable Code Mode runtime directly.

Agents SDK MCP clients now reuse converted input and output schemas while a live connection keeps the same tool catalog. This avoids converting every MCP JSON Schema to Zod again for each model turn.

@cloudflare/think also adds includeMcpTools. Set it to false when you expose MCP tools through Code Mode or another mechanism outside Think's automatic tool set:

import { Think } from "@cloudflare/think";

export class MyAgent extends Think {
	includeMcpTools = false;
	waitForMcpConnections = true;
}

import { Think } from "@cloudflare/think";

export class MyAgent extends Think<Env> {
	includeMcpTools = false;
	waitForMcpConnections = true;
}

This setting skips Think's automatic getAITools() call. MCP registration, restoration, discovery, raw catalog access, direct calls, and Code Mode connectors continue to work.

Use listTools() when you only need the raw MCP catalog. For connector setup, refer to Use MCP tools with Code Mode.

@cloudflare/codemode@latest adds execute(), search(), and describe() to the durable runtime handle. MCP servers and other hosts can now execute code and discover connector methods without adapting the runtime to an AI SDK tool.

const matches = await runtime.search("create issue");
const docs = await runtime.describe(matches.results[0].path);
const outcome = await runtime.execute({
	code: `async () => github.create_issue({ title: "Bug" })`,
});

const matches = await runtime.search("create issue");
const docs = await runtime.describe(matches.results[0].path);
const outcome = await runtime.execute({
	code: `async () => github.create_issue({ title: "Bug" })`,
});

Search and describe results include requiresApproval: true for protected connector methods. Resolve a paused execution with the existing approve() and reject() methods.

For setup and exact method types, refer to Create a durable Code Mode runtime and the Code Mode API reference.

npm i agents@latest @cloudflare/think@latest @cloudflare/codemode@latest

yarn add agents@latest @cloudflare/think@latest @cloudflare/codemode@latest

pnpm add agents@latest @cloudflare/think@latest @cloudflare/codemode@latest

bun add agents@latest @cloudflare/think@latest @cloudflare/codemode@latest

Devin Outposts ↗ lets you run Devin agents on Cloudflare. Each Devin session runs in its own isolated sandbox backed by Cloudflare Containers, so agents can execute code and use development tooling in an isolated environment.

Use Devin Outposts when you want Devin sessions to run on Cloudflare managed infrastructure, with each session isolated from the others.

To get started, refer to Run Devin on Cloudflare using Devin Outposts.

We are turning on budget alerts by default for eligible Pay-as-you-go accounts. If your account does not already have a budget alert, Cloudflare will create one for you with a $10 account-level threshold. Your default alert will enable at the turn of your next billing cycle, so it will not fire based on usage you have already incurred.

We are rolling this out in cohorts over the coming weeks, so eligible accounts may see their default alert appear at different times.

The default alert behaves exactly like an alert you would create yourself. When your cumulative usage-based spend this cycle reaches the threshold, you receive an email notification. The alert is informational only. It does not cap your usage or impact your account in any way.

Usage is processed once per day for the prior day's activity, so budget alerts fire the day after the threshold is reached rather than in real time.

Budget alerts only consider spend on usage-based products. Recurring subscription fees, such as the Workers Paid plan fee or other monthly plan charges, are not included in the threshold calculation.

You can change the threshold, add additional alerts, or remove the default alert entirely from Manage Account > Billing > Billable Usage, or from your Notifications settings. If you already configured your own budget alert, nothing changes.

Enterprise contract accounts are not in scope.

For more information, refer to the Budget alerts documentation.

You can now monitor the total SQLite storage used by a Durable Object namespace over time in the Cloudflare dashboard. The new Total storage chart shows the maximum storage reported during each hour. This helps you identify storage growth, validate data cleanup, and investigate unexpected usage.

The chart appears only for SQLite-backed Durable Object namespaces. It does not appear for namespaces that use the legacy key-value storage backend. Viewing storage for individual Durable Objects by ID or name is not supported.

For more information, refer to Metrics and analytics.

You can now preview the content of sent emails directly from the Email Service Activity log. Expand a sent email and open the new Preview section to inspect the message as it was sent, across tabs for the rendered HTML body, the Text body, the Headers, the Attachments, and the full Raw RFC 5322 ↗ source.

Previously, the Activity log surfaced delivery and authentication metadata but not the message content, making rendering and content issues harder to debug. Message preview closes that gap.

To make messages previewable, turn on Email preview in your sending domain's settings. Previews cover messages sent while the setting is turned on and are retained for about seven days. Sending domains onboarded on or after 2026-07-02 have Email preview turned on automatically.

Refer to Email logs for more information.

Wrangler now includes wrangler flagship, a command suite for managing Flagship apps and feature flags from your terminal.

Create an app and, if you use it from a Worker, add it to your wrangler.json or wrangler.jsonc file as a binding:

wrangler flagship apps create "My Worker App" \
  --binding FLAGS \
  --update-config

Then create flags for the behavior you want to control. Flags can be booleans, strings, numbers, or JSON values:

wrangler flagship flags create <APP_ID> new-checkout

wrangler flagship flags create <APP_ID> checkout-flow \
  --variation control=old-checkout \
  --variation treatment=new-checkout \
  --default control \
  --type string

After a flag exists, change its default variation or use enable and disable commands as kill switches. Existing targeting rules continue to apply unless you change or clear them explicitly:

wrangler flagship flags update <APP_ID> checkout-flow --default treatment
wrangler flagship flags disable <APP_ID> checkout-flow
wrangler flagship flags enable <APP_ID> checkout-flow

For release workflows, use rollout, split, and rules to change exposure without redeploying your Worker:

wrangler flagship flags rollout <APP_ID> new-checkout \
  --to on \
  --percentage 25 \
  --by user_id

wrangler flagship flags split <APP_ID> checkout-flow \
  --weight control=80 \
  --weight treatment=20 \
  --by user_id

wrangler flagship flags rules update <APP_ID> checkout-flow \
  --priority 1 \
  --when "country equals US"

These commands can also be used from CI/CD pipelines, scripts, and AI agents to inspect Flagship state, update flag behavior, or roll back changes through Wrangler.

Refer to the wrangler flagship command reference for the full command guide.

You can now subscribe to Email Sending events through Queues event subscriptions and receive outbound transactional email lifecycle events on a queue. Each subscription is scoped to one sending domain — either the zone apex, such as example.com, or a verified sending subdomain, such as send.example.com.

Six event types are published: message.delivered, message.deferred, message.bounced, message.failed, message.rejected, and message.complained. Use them to track deliverability, react to bounces and complaints, and drive suppression or retry logic. Email Routing events are not published on this source.

Each event includes the message details, delivery status, and SMTP response:

{
	"type": "cf.email.sending.message.delivered",
	"source": {
		"type": "email.sending",
		"zoneId": "023e105f4ecef8ad9ca31a8372d0c353",
		"domain": "example.com"
	},
	"payload": {
		"messageId": "0101018f7d0c4d9a-msg-deadbeef",
		"recipient": "user@example.net",
		"terminal": true,
		"delivery": {
			"status": "delivered",
			"smtpStatusCode": "250"
		}
	}
}

Refer to Event subscriptions to see all event types and example payloads.

The legacy Workers KV API routes under /accounts/{account_id}/workers/namespaces/* are deprecated as of July 15, 2026, and will stop working on October 15, 2026. Migrate to the documented Workers KV API routes under /accounts/{account_id}/storage/kv/namespaces/* before that date.

The legacy and replacement routes are interchangeable. They accept the same request parameters and return the same response payloads. To migrate, update the URL path from /workers/namespaces/ to /storage/kv/namespaces/.

Update any integration that calls a route under /accounts/{account_id}/workers/namespaces/ to use the equivalent route under /accounts/{account_id}/storage/kv/namespaces/. The migration is a direct URL path substitution — request parameters and response payloads are identical:

• GET and POST /accounts/{account_id}/workers/namespaces → GET and POST /accounts/{account_id}/storage/kv/namespaces
• GET, PUT, and DELETE /accounts/{account_id}/workers/namespaces/{namespace_id} → GET, PUT, and DELETE /accounts/{account_id}/storage/kv/namespaces/{namespace_id}
• GET /accounts/{account_id}/workers/namespaces/{namespace_id}/keys → GET /accounts/{account_id}/storage/kv/namespaces/{namespace_id}/keys
• GET /accounts/{account_id}/workers/namespaces/{namespace_id}/metadata/{key_name} → GET /accounts/{account_id}/storage/kv/namespaces/{namespace_id}/metadata/{key_name}
• GET, PUT, and DELETE /accounts/{account_id}/workers/namespaces/{namespace_id}/values/{key_name} → GET, PUT, and DELETE /accounts/{account_id}/storage/kv/namespaces/{namespace_id}/values/{key_name}

For more information about the deprecation timeline, refer to API deprecations.

Cloudflare Web Analytics (Real User Monitoring) has rolled out performance optimizations to significantly improve the stability and loading speed of account-wide dashboards.

For larger accounts (with >100 Web Analytics sites), loading the aggregate account-wide view would often fail, running into timeouts or unexpected interface errors due to the massive scale of parallel query processing. This update optimizes how high-volume multi-site data is queried to reduce errors and provide a snappier dashboard experience.

Accounts with up to 1,000 sites will now be able to load this account-wide aggregate view without experiencing misleading errors.

If you have an account with over 1,000 sites, we cannot currently aggregate over this volume due to processing constraints but you will now be presented with a clear error and instruction to filter to the relevant site(s) you wish to see the data for.

Platforms can now create temporary preview accounts through the Cloudflare REST API. This lets your platform deploy a live Worker before the user signs in to Cloudflare.

With the Temporary Accounts API, coding agents, AI app builders, and other platforms can build a similar flow for generated Workers and supported resources.

Your platform can keep users in its onboarding flow while they generate, deploy, and test an application. Users do not need an existing Cloudflare account, and your platform does not need write access to one.

The API returns a claim URL that lets the user make the temporary account and its resources permanent.

Cloudflare Drop ↗ demonstrates this preview-and-claim pattern for static sites. Someone can upload a site, test and share it for one hour, then sign in or create an account only when they want to keep it.

This API expands the flow first introduced with wrangler deploy --temporary. Your backend now controls the provisioning and deployment experience directly:

1. Show Cloudflare's Terms of Service and Privacy Policy in your product, and require the user to accept them.
2. Request and solve a proof-of-work challenge.
3. Create a temporary preview account.
4. Deploy with the returned temporary account ID and API token.
5. Show the deployed Worker URL and claim URL to the user.

curl "https://api.cloudflare.com/client/v4/provisioning/previews/challenge" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{}'

curl "https://api.cloudflare.com/client/v4/provisioning/previews" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "termsOfService": "https://www.cloudflare.com/terms/",
    "privacyPolicy": "https://www.cloudflare.com/privacypolicy/",
    "acceptTermsOfService": "yes",
    "challengeToken": "<CHALLENGE_TOKEN>",
    "solution": {
      "checkpoints": "<BASE64_CHECKPOINTS>"
    }
  }'

For the complete API flow, proof-of-work requirements, supported products, and limits, refer to Claim deployments (temporary accounts). For the background and design goals behind this flow, refer to Temporary Cloudflare Accounts for AI agents ↗.

Agents connected to Model Context Protocol (MCP) servers with addMcpServer can now handle elicitation ↗ requests.

Elicitation lets an MCP server request user input while it handles a tool call. Form mode collects structured, non-sensitive data. URL mode asks for consent before opening an out-of-band flow, such as third-party authorization or payment.

sequenceDiagram
    participant User
    participant Agent as Agent (MCP client)
    participant Server as MCP server
    participant Browser

    Server->>Agent: elicitation/create
    Agent->>User: Show server, reason, and input or URL
    User->>Agent: Submit, open, decline, or cancel
    Agent->>Browser: Open URL after consent (URL mode)
    Agent->>Server: accept, decline, or cancel
    Server-->>Agent: Optional URL completion notification

Register a handler for each mode your Agent supports in onStart():

import { Agent } from "agents";

export class MyAgent extends Agent {
	onStart() {
		this.mcp.configureElicitationHandlers({
			form: (request, serverId) => this.forwardToUser(request, serverId),
			url: (request, serverId) => this.forwardToUser(request, serverId),
		});
	}

	forwardToUser(request, serverId) {
		// Show the request in your UI and resolve after the user responds.
		throw new Error(
			`Implement elicitation for ${serverId}: ${request.params.message}`,
		);
	}
}

import { Agent } from "agents";
import type { ElicitRequest, ElicitResult } from "agents/mcp";

export class MyAgent extends Agent<Env> {
	onStart() {
		this.mcp.configureElicitationHandlers({
			form: (request, serverId) => this.forwardToUser(request, serverId),
			url: (request, serverId) => this.forwardToUser(request, serverId),
		});
	}

	private forwardToUser(
		request: ElicitRequest,
		serverId: string,
	): Promise<ElicitResult> {
		// Show the request in your UI and resolve after the user responds.
		throw new Error(
			`Implement elicitation for ${serverId}: ${request.params.message}`,
		);
	}
}

Connections advertise only the modes with configured handlers. An Agent without handlers advertises no elicitation capability, which lets the server use its fallback. The SDK stores the advertised modes with each MCP server registration so they survive Durable Object hibernation. Callback functions remain in memory and reattach when onStart() runs.

For implementation details and a browser forwarding pattern, refer to MCP client elicitation. The mcp-client ↗ and mcp-elicitation ↗ examples implement both sides.

To update to this release:

npm i agents@latest

yarn add agents@latest

pnpm add agents@latest

bun add agents@latest

R2 Data Catalog now accepts read-only API tokens, so query engines and clients that only read data no longer need a read-write token. Previously, every catalog operation required an Admin Read & Write token, which granted read-only clients more access than they needed.

You can now authenticate your Iceberg engine based on your workload:

• Read-only operations (such as listing namespaces, loading tables, and querying data) work with an Admin Read only token (R2 Data Catalog read and R2 storage read).
• Write operations (such as creating or dropping tables and committing transactions) continue to require an Admin Read & Write token.

This lets you follow the principle of least privilege — for example, using a read-write token for the pipeline that writes to your tables and read-only tokens for engines like R2 SQL, DuckDB, or PyIceberg that query them.

Note that credentials vended by the catalog inherit the R2 storage permissions of the token used to authenticate. To ensure read-only access to your underlying data, scope the R2 storage permission to read-only as well.

For details on choosing and creating the right token, refer to Authenticate your Iceberg engine.

R2 Data Catalog, a managed Apache Iceberg ↗ catalog built into R2, now automatically optimizes manifest files as part of compaction.

Manifest files track the data files that make up an Iceberg table. As a table accumulates many small or fragmented manifests, query engines must read more metadata during query planning, which slows down queries even before any data is scanned.

When compaction runs, R2 Data Catalog now rewrites and clusters manifest files by partition as a best-effort pre-step. This consolidates fragmented manifests, reduces the number of manifests a query engine must open, and lowers metadata I/O overhead. Tables that are already well-clustered are skipped, so the operation only runs when it provides a benefit.

This happens automatically for tables with compaction enabled — no configuration changes are required.

For more information, refer to Table maintenance.

The Markdown Conversion service now supports a new output conversion option that controls the format of the converted content.

Set output.format to text to receive plain text with Markdown syntax removed. The default value is markdown, so existing conversions are unchanged.

Use the env.AI binding:

await env.AI.toMarkdown(
	{ name: "page.html", blob: new Blob([html]) },
	{
		conversionOptions: {
			output: { format: "text" },
		},
	},
);

await env.AI.toMarkdown(
	{ name: "page.html", blob: new Blob([html]) },
	{
		conversionOptions: {
			output: { format: "text" },
		},
	},
);

Or call the REST API:

curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/tomarkdown \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -F 'files=@index.html' \
  -F 'conversionOptions={"output": {"format": "text"}}'

When you request text output, the format field of each result is set to text. For more details, refer to Conversion Options.

With Workflows, you can configure built-in retry behavior for each step. Previously, you could configure step retries with fixed delay durations, such as seconds, minutes, or hours, and backoff strategies such as constant, linear, or exponential.

Step retries now support dynamic delay functions. Instead of choosing only a base delay and backoff strategy, pass a function to retries.delay and calculate the next delay from the failed attempt and thrown error.

This is useful when retries should depend on the failure. Your Workflow may need to wait longer after a rate-limit error, but retry sooner after a short network failure. The delay function can also accommodate provider guidance if, for example, a downstream API returns a Retry-After value in its error messaging.

await step.do(
	"sync customer",
	{
		retries: {
			limit: 5,
			delay: ({ ctx, error }) => {
				if (error.message.includes("rate limit")) {
					return `${ctx.attempt * 30} seconds`;
				}

				return "10 seconds";
			},
		},
	},
	async () => {
		await syncCustomer();
	},
);

await step.do(
	"sync customer",
	{
		retries: {
			limit: 5,
			delay: ({ ctx, error }) => {
				if (error.message.includes("rate limit")) {
					return `${ctx.attempt * 30} seconds`;
				}

				return "10 seconds";
			},
		},
	},
	async () => {
		await syncCustomer();
	},
);

Dynamic delay functions can return a duration string, a number, or a promise that resolves to a duration. Use them to add adaptive retry behavior without writing separate queue or scheduling logic. For more information, refer to Sleeping and retrying.

If your account does not already have a key-value (KV) backed Durable Object namespace, you can no longer create new ones. New Durable Object namespaces must use the SQLite storage backend, which has been recommended for all new Durable Objects since it became generally available ↗ in 2024.

Create a new class with a new_sqlite_classes migration:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": [
        "MyDurableObject"
      ]
    }
  ]
}

[[migrations]]
tag = "v1"
new_sqlite_classes = ["MyDurableObject"]

SQLite-backed Durable Objects have feature parity with the key-value backend — including the key-value storage API — and additionally support relational SQL queries and point-in-time recovery to restore an object's storage to any point in the past 30 days.

If you attempt to create a new key-value backed namespace (a new_classes migration) on an affected account, the deployment fails with the following error:

Creating new key-value backed Durable Object namespaces is no longer supported on this account. Please create a namespace using a `new_sqlite_classes` migration instead.

This change only affects accounts that are not already using the key-value storage backend. Accounts with at least one existing key-value backed namespace can still create new ones for now, and the Workers Free plan has only ever supported SQLite-backed Durable Objects. It is part of a broader move toward SQLite as the single storage backend for Durable Objects, ahead of a future migration path for existing key-value backed objects.

For more information, refer to Durable Objects migrations.

On October 5, 2026, two changes take effect across the Zero Trust Networks API and Cloudflare Tunnel API: the CIDR-encoded route endpoints are removed, and tunnel list and get responses no longer include the connections field. If you manage private network routes or read tunnel connection details through the API, cloudflared, Terraform, or another integration, review the changes in the following sections and migrate before the removal date.

The CIDR-encoded route endpoints are deprecated in favor of the standard, route_id-based endpoints that already exist today. Both sets of endpoints route a private network through Cloudflare Tunnel or Cloudflare Mesh (the API still refers to Mesh nodes as warp_connector) — only the request shape changes.

Deprecated endpoints (removed October 5, 2026):

• Create a tunnel route (CIDR Endpoint): POST /accounts/{account_id}/teamnet/routes/network/{ip_network_encoded}
• Update a tunnel route (CIDR Endpoint): PATCH /accounts/{account_id}/teamnet/routes/network/{ip_network_encoded}
• Delete a tunnel route (CIDR Endpoint): DELETE /accounts/{account_id}/teamnet/routes/network/{ip_network_encoded}

Replacement endpoints:

• Create a tunnel route: POST /accounts/{account_id}/teamnet/routes
• Update a tunnel route: PATCH /accounts/{account_id}/teamnet/routes/{route_id}
• Delete a tunnel route: DELETE /accounts/{account_id}/teamnet/routes/{route_id}

1. Capture each route's route_id by calling List tunnel routes, or read it from the response the first time you create a route with the replacement endpoint.
2. Update any scripts, backend services, or CI/CD pipelines that call the CIDR-encoded endpoints directly.
3. If you manage routes with the cloudflared tunnel route ip add | delete commands, upgrade cloudflared to the latest version ↗.
4. If you manage routes with Terraform, make sure you are on a current version of the cloudflare_zero_trust_tunnel_cloudflared_route ↗ resource and the Cloudflare Terraform provider ↗.

# Before: create a route by URL-encoding the CIDR into the path
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/teamnet/routes/network/172.16.0.0%2F16 \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
     -d '{"tunnel_id": "'$TUNNEL_ID'", "comment": "Example comment for this route."}'

# After: create a route with the network in the request body
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/teamnet/routes \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
     -d '{"network": "172.16.0.0/16", "tunnel_id": "'$TUNNEL_ID'", "comment": "Example comment for this route."}'

# After: update or delete a route using its route_id
curl -X PATCH https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/teamnet/routes/$ROUTE_ID \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
     -d '{"comment": "Updated comment for this route."}'

curl -X DELETE https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/teamnet/routes/$ROUTE_ID \
     -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Starting the same day, the connections array is removed from list and get responses for Cloudflare Tunnel and Cloudflare Mesh nodes (the cfd_tunnel and warp_connector API resources). Query the dedicated connections endpoint instead of reading the field off the tunnel or node object.

This affects:

• GET /accounts/{account_id}/cfd_tunnel — connections removed from each item in result
• GET /accounts/{account_id}/cfd_tunnel/{tunnel_id} — connections removed from result
• GET /accounts/{account_id}/warp_connector — connections removed from each item in result
• GET /accounts/{account_id}/warp_connector/{tunnel_id} — connections removed from result

Fetch connection details from the tunnel-specific connections endpoint instead of parsing it off the list or get response. For Cloudflare Tunnel, call GET /accounts/{account_id}/cfd_tunnel/{tunnel_id}/connections. For Cloudflare Mesh, call GET /accounts/{account_id}/warp_connector/{tunnel_id}/connections.

# Before: read connections off the tunnel object
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cfd_tunnel/$TUNNEL_ID \
     -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

# After: query connections directly
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/cfd_tunnel/$TUNNEL_ID/connections \
     -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Update any dashboards, monitoring scripts, or automation that parses connections from the tunnel list or get response. cloudflared and the Cloudflare Terraform provider do not read this field, so no changes are required on their side for this part of the update.

• Smaller, faster responses. Cloudflare Tunnel and Cloudflare Mesh nodes with many connections no longer inflate every list and get call — connection detail is only fetched when you need it.
• A single way to identify a route. Consolidating on route_id removes the need to URL-encode CIDR ranges into the path and matches how every other resource in the Zero Trust Networks API is addressed.
• Consistency across the API. Both changes align these endpoints with Cloudflare's standard REST conventions for resource identifiers and nested detail endpoints.

To learn more, refer to the Zero Trust Networks API, the Cloudflare Tunnel API, and Routes documentation.

Wrangler now collects npm package dependency information from your project's package.json during wrangler deploy and wrangler versions upload, and includes it in the upload metadata sent to the Cloudflare API. This data, each dependency's name, declared version range, and exact installed version, enables dependency analytics and future supply chain security features such as vulnerability alerting.

To opt out, set dependencies_instrumentation.enabled to false in your Wrangler configuration file:

{
	"dependencies_instrumentation": {
		"enabled": false
	}
}

[dependencies_instrumentation]
enabled = false

For more details, refer to Wrangler configuration.

In AI Search, you can upload files to an instance, or connect a data source such as an R2 bucket, to make your content searchable with natural language. Each file becomes an item identified by an object key (its filename or path). The list items endpoint returns the items in an instance.

That endpoint now accepts a key query parameter, so you can look up a single item by its exact object key without paging through the full list. This complements the existing item_id filter for when you know the key but not the ID.

curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai-search/instances/<INSTANCE_NAME>/items?key=docs/readme.md" \
  -H "Authorization: Bearer <API_TOKEN>"

Keys are unique per data source, so combine key with source (for example, source=builtin) to disambiguate when the same key exists across multiple sources.

For more information, refer to managing items.