Developer Platform Updates & Release Notes

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)

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 });

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)

const client = new AgentClient({
	agent: "game-agent",
	name: "room-123", …

AI Search now offers new REST API endpoints for search and chat that use an OpenAI compatible format. This means you can use the familiar messages array structure that works with existing OpenAI SDKs and tools. The messages array also lets you pass previous messages within a session, so the model can maintain context across multiple turns.

Endpoint

Path

Chat Completions

POST /accounts/{account_id}/ai-search/instances/{name}/chat/completions

Search

POST /accounts/{account_id}/ai-search/instances/{name}/search

Here is an example request to the Chat Completions endpoint using the new messages array format:

curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai-search/instances/{NAME}/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -d '{
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful documentation assistant."
      },
      {
        "role": "user",
        "content": "How do I get started?"
      }
    ]
  }'

For more details, refer to the AI Search REST API guide.

Migration from existing AutoRAG API (recommended)

…

AI Search now supports public endpoints, UI snippets, and MCP, making it easy to add search to your website or connect AI agents.

Public endpoints allow you to expose AI Search capabilities without requiring API authentication. To enable public endpoints:

1. Go to AI Search in the Cloudflare dashboard. Go to AI Search ↗
2. Select your instance, and turn on Public Endpoint in Settings. For more details, refer to Public endpoint configuration.

UI snippets

UI snippets are pre-built search and chat components you can embed in your website. Visit search.ai.cloudflare.com ↗︎ to configure and preview components for your AI Search instance.

Example of the search-modal-snippet component

To add a search modal to your page:

<script
	type="module"
	src="https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/assets/v0.0.25/search-snippet.es.js"
></script>

<search-modal-snippet
	api-url="https://<PUBLIC_ENDPOINT_ID>.search.ai.cloudflare.com/"
	placeholder="Search..."
>
</search-modal-snippet>
``` …

AI Search now supports custom metadata filtering, allowing you to define your own metadata fields and filter search results based on attributes like category, version, or any custom field you define.

Define a custom metadata schema

You can define up to 5 custom metadata fields per AI Search instance. Each field has a name and data type (text, number, or boolean):

curl -X POST https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai-search/instances \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -d '{
    "id": "my-instance",
    "type": "r2",
    "source": "my-bucket",
    "custom_metadata": [
      { "field_name": "category", "data_type": "text" },
      { "field_name": "version", "data_type": "number" },
      { "field_name": "is_public", "data_type": "boolean" }
    ]
  }'

Add metadata to your documents

How you attach metadata depends on your data source:

• R2 bucket: Set metadata using S3-compatible custom headers (x-amz-meta-*) when uploading objects. Refer to R2 custom metadata for examples. …

R2 SQL now supports an expanded SQL grammar so you can write richer analytical queries without exporting data. This release adds CASE expressions, column aliases, arithmetic in clauses, 163 scalar functions, 33 aggregate functions, EXPLAIN, Common Table Expressions (CTEs),and full struct/array/map access. R2 SQL is Cloudflare's serverless, distributed, analytics query engine for querying Apache Iceberg ↗︎ tables stored in R2 Data Catalog. This page documents the supported SQL syntax.

Highlights

• Column aliases — SELECT col AS alias now works in all clauses
• CASE expressions — conditional logic directly in SQL (searched and simple forms)
• Scalar functions — 163 new functions across math, string, datetime, regex, crypto, encoding, and type inspection categories
• Aggregate functions — statistical (variance, stddev, correlation, regression), bitwise, boolean, and positional aggregates join the existing basic and approximate functions
• Complex types — query struct fields with bracket notation, use 46 array functions, and extract map keys/values
• Common table expressions (CTEs) — use WITH ... AS to define named temporary result sets. Chained CTEs are supported. All CTEs must reference the same single table. …

Each VPC Service now has a Metrics tab so you can monitor connection health and debug failures without leaving the dashboard.

Workers VPC Metrics dashboard showing connections, latency, and errors charts

• Connections — See successful and failed connections over time, broken down by what is responsible: your origin (Bad Upstream), your configuration (Client), or Cloudflare (Internal).
• Latency — Track connection and DNS resolution latency trends.
• Errors — Drill into specific error codes grouped by category, with filters to isolate upstream, client, or internal failures.

You can also view and edit your VPC Service configuration, host details, and port assignments from the Settings tab.

For a full list of error codes and what they mean, refer to Troubleshooting.

Hyperdrive now supports custom TLS/SSL certificates for MySQL databases, bringing the same certificate options previously available for PostgreSQL to MySQL connections.

You can now configure:

• Server certificate verification with VERIFY_CA or VERIFY_IDENTITY SSL modes to verify that your MySQL database server's certificate is signed by the expected certificate authority (CA).
• Client certificates (mTLS) for Hyperdrive to authenticate itself to your MySQL database with credentials beyond username and password.

Create a Hyperdrive configuration with custom certificates for MySQL:

# Upload a CA certificate
npx wrangler cert upload certificate-authority --ca-cert your-ca-cert.pem --name your-custom-ca-name

# Create a Hyperdrive with VERIFY_IDENTITY mode
npx wrangler hyperdrive create your-hyperdrive-config \
  --connection-string="mysql://user:password@hostname:port/database" \
  --ca-certificate-id <CA_CERT_ID> \
  --sslmode VERIFY_IDENTITY

For more information, refer to SSL/TLS certificates for Hyperdrive and MySQL TLS/SSL modes.

You can now manage Cloudflare Tunnels directly from Wrangler, the CLI for the Cloudflare Developer Platform. The new wrangler tunnel commands let you create, run, and manage tunnels without leaving your terminal.

Wrangler tunnel commands demo

Available commands:

• wrangler tunnel create — Create a new remotely managed tunnel.
• wrangler tunnel list — List all tunnels in your account.
• wrangler tunnel info — Display details about a specific tunnel.
• wrangler tunnel delete — Delete a tunnel.
• wrangler tunnel run — Run a tunnel using the cloudflared daemon.
• wrangler tunnel quick-start — Start a free, temporary tunnel without an account using Quick Tunnels.

Wrangler handles downloading and managing the cloudflared binary automatically. On first use, you will be prompted to download cloudflared to a local cache directory.

These commands are currently experimental and may change without notice. …

Workers AI is officially in the big models game. @cf/moonshotai/kimi-k2.5 is the first frontier-scale open-source model on our AI inference platform — a large model with a full 256k context window, multi-turn tool calling, vision inputs, and structured outputs. By bringing a frontier-scale model directly onto the Cloudflare Developer Platform, you can now run the entire agent lifecycle on a single, unified platform.

The model has proven to be a fast, efficient alternative to larger proprietary models without sacrificing quality. As AI adoption increases, the volume of inference is skyrocketing — now you can access frontier intelligence at a fraction of the cost.

Key capabilities

• 256,000 token context window for retaining full conversation history, tool definitions, and entire codebases across long-running agent sessions
• Multi-turn tool calling for building agents that invoke tools across multiple conversation turns
• Vision inputs for processing images alongside text
• Structured outputs with JSON mode and JSON Schema support for reliable downstream parsing
• Function calling for integrating external tools and APIs into agent workflows

Prefix caching and session affinity

…

You can now use a Workers binding to transform videos with Media Transformations. This allows you to resize, crop, extract frames, and extract audio from videos stored anywhere, even in private locations like R2 buckets.

The Media Transformations binding is useful when you want to:

• Transform videos stored in private or protected sources
• Optimize videos and store the output directly back to R2 for re-use
• Extract still frames for classification or description with Workers AI
• Extract audio tracks for transcription using Workers AI

To get started, add the Media binding to your Wrangler configuration:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "media": {
    "binding": "MEDIA"
  }
}

[media]
binding = "MEDIA"

Then use the binding in your Worker to transform videos:

export default {
	async fetch(request, env) {
		const video = await env.R2_BUCKET.get("input.mp4");

		const result = env.MEDIA.input(video.body)
			.transform({ width: 480, height: 270 })
			.output({ mode: "video", duration: "5s" });

		return await result.response();
	},
};

export default {
	async fetch(request, env) {
		const video = await env.R2_BUCKET.get("input.mp4");

		const result = env.MEDIA.input(video.body)
			.transform({ width: 480, height: 270 })
			.output({ mode: "video", duration: "5s" });

		return await result.response();
	},
};
``` …

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.

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 });

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 …

AI Gateway now supports the cf-aig-collect-log-payload header, which controls whether request and response bodies are stored in logs. By default, this header is set to true and payloads are stored alongside metadata. Set this header to false to skip payload storage while still logging metadata such as token counts, model, provider, status code, cost, and duration.

This is useful when you need usage metrics but do not want to persist sensitive prompt or response data.

curl https://gateway.ai.cloudflare.com/v1/$ACCOUNT_ID/$GATEWAY_ID/openai/chat/completions \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-collect-log-payload: false' \
  --data '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "What is the email address and phone number of user123?"
      }
    ]
  }'

For more information, refer to Logging.

When your Worker accesses a Durable Object via idFromName() or getByName(), the same name is now available on ctx.id.name inside the object — no need to pass it through method arguments or persist it in storage. This brings the runtime behavior in line with the Workers runtime types.

This is especially useful for alarms, where there is no calling client to pass the name as an argument. When an alarm handler runs, ctx.id.name will hold the same name the object was originally accessed with.

import { DurableObject } from "cloudflare:workers";

export class ChatRoom extends DurableObject {
  async getRoomName() {
    // ctx.id.name returns the name passed to getByName() or idFromName()
    return this.ctx.id.name;
  }
}

// Worker
export default {
  async fetch(request, env) {
    const stub = env.CHAT_ROOM.getByName("general");
    const roomName = await stub.getRoomName();
    return new Response(`Welcome to ${roomName}!`);
  },
};

ctx.id.name is undefined in the following cases:

• For Durable Objects created with newUniqueId().
• When accessed via idFromString(), even if the ID was originally created from a name.
• For names longer than 1,024 bytes. …

When your Worker accesses a Durable Object via idFromName() or getByName(), the same name is now available on ctx.id.name inside the object — no need to pass it through method arguments or persist it in storage. This brings the runtime behavior in line with the Workers runtime types.

This is especially useful for alarms, where there is no calling client to pass the name as an argument. When an alarm handler runs, ctx.id.name will hold the same name the object was originally accessed with.

import { DurableObject } from "cloudflare:workers";

export class ChatRoom extends DurableObject {
  async getRoomName() {
    // ctx.id.name returns the name passed to getByName() or idFromName()
    return this.ctx.id.name;
  }
}

// Worker
export default {
  async fetch(request, env) {
    const stub = env.CHAT_ROOM.getByName("general");
    const roomName = await stub.getRoomName();
    return new Response(`Welcome to ${roomName}!`);
  },
};

ctx.id.name is undefined in the following cases:

• For Durable Objects created with newUniqueId().
• When accessed via idFromString(), even if the ID was originally created from a name.
• For names longer than 1,024 bytes. …

You can now SSH into running Container instances using Wrangler. This is useful for debugging, inspecting running processes, or executing one-off commands inside a Container.

To connect, enable wrangler_ssh in your Container configuration and add your ssh-ed25519 public key to authorized_keys:

{
	"containers": [
		{
			"wrangler_ssh": {
				"enabled": true
			},
			"authorized_keys": [
				{
					"name": "<NAME>",
					"public_key": "<YOUR_PUBLIC_KEY_HERE>"
				}
			]
		}
	]
}

[[containers]]
[containers.wrangler_ssh]
enabled = true

[[containers.authorized_keys]]
name = "<NAME>"
public_key = "<YOUR_PUBLIC_KEY_HERE>"

Then connect with:

wrangler containers ssh <INSTANCE_ID>

You can also run a single command without opening an interactive shell:

wrangler containers ssh <INSTANCE_ID> -- ls -al

Use wrangler containers instances <APPLICATION> to find the instance ID for a running Container.

For more information, refer to the SSH documentation.

A new wrangler containers instances command lists all instances for a given Container application. This mirrors the instances view in the Cloudflare dashboard.

The command displays each instance's ID, name, state, location, version, and creation time:

wrangler containers instances <APPLICATION_ID>

Use the --json flag for machine-readable output, which is also the default format in non-interactive environments such as CI pipelines.

For the full list of options, refer to the containers instances command reference.

A new wrangler containers instances command lists all instances for a given Container application. This mirrors the instances view in the Cloudflare dashboard.

The command displays each instance's ID, name, state, location, version, and creation time:

wrangler containers instances <APPLICATION_ID>

Use the --json flag for machine-readable output, which is also the default format in non-interactive environments such as CI pipelines.

For the full list of options, refer to the containers instances command reference.

We're excited to partner with NVIDIA to bring @cf/nvidia/nemotron-3-120b-a12b to Workers AI. NVIDIA Nemotron 3 Super is a Mixture-of-Experts (MoE) model with a hybrid Mamba-transformer architecture, 120B total parameters, and 12B active parameters per forward pass.

The model is optimized for running many collaborating agents per application. It delivers high accuracy for reasoning, tool calling, and instruction following across complex multi-step tasks.

Key capabilities:

• Hybrid Mamba-transformer architecture delivers over 50% higher token generation throughput compared to leading open models, reducing latency for real-world applications
• Tool calling support for building AI agents that invoke tools across multiple conversation turns
• Multi-Token Prediction (MTP) accelerates long-form text generation by predicting several future tokens simultaneously in a single forward pass
• 32,000 token context window for retaining conversation history and plan states across multi-step agent workflows

Prompt caching

For optimal performance with multi-turn conversations, send the x-session-affinity header with a unique session identifier to enable prompt caching. This routes requests to the same model instance, reducing latency and inference costs. For details, refer to Prompt caching. …