Developer Platform Release Notes

We are partnering with Google to bring @cf/google/gemma-4-26b-a4b-it to Workers AI. Gemma 4 26B A4B is a Mixture-of-Experts (MoE) model built from Gemini 3 research, with 26B total parameters and only 4B active per forward pass. By activating a small subset of parameters during inference, the model runs almost as fast as a 4B-parameter model while delivering the quality of a much larger one.

Gemma 4 is Google's most capable family of open models, designed to maximize intelligence-per-parameter.

Key capabilities

• Mixture-of-Experts architecture with 8 active experts out of 128 total (plus 1 shared expert), delivering frontier-level performance at a fraction of the compute cost of dense models
• 256,000 token context window for retaining full conversation history, tool definitions, and long documents across extended sessions
• Built-in thinking mode that lets the model reason step-by-step before answering, improving accuracy on complex tasks
• Vision understanding for object detection, document and PDF parsing, screen and UI understanding, chart comprehension, OCR (including multilingual), and handwriting recognition, with support for variable aspect ratios and resolutions
• Function calling with native support for structured tool use, enabling agentic workflows and multi-step planning
• Multilingual with out-of-the-box support for 35+ languages, pre-trained on 140+ languages
• Coding for code generation, completion, and correction

Use Gemma 4 26B A4B through the Workers AI binding (env.AI.run()), the REST API at /run or /v1/chat/completions, or the OpenAI-compatible endpoint.

For more information, refer to the Gemma 4 26B A4B model page.

Original source Report a problem

AI Gateway now supports automatic retries at the gateway level. When an upstream provider returns an error, your gateway retries the request based on the retry policy you configure, without requiring any client-side changes.

You can configure the retry count (up to 5 attempts), the delay between retries (from 100ms to 5 seconds), and the backoff strategy (Constant, Linear, or Exponential). These defaults apply to all requests through the gateway, and per-request headers can override them.

This is particularly useful when you do not control the client making the request and cannot implement retry logic on the caller side. For more complex failover scenarios — such as failing across different providers — use Dynamic Routing.

For more information, refer to Manage gateways.

Original source Report a problem

All wrangler workflows commands now accept a --local flag to target a Workflow running in a local wrangler dev session instead of the production API.

You can now manage the full Workflow lifecycle locally, including triggering Workflows, listing instances, pausing, resuming, restarting, terminating, and sending events:

npx wrangler workflows list --local
npx wrangler workflows trigger my-workflow --local
npx wrangler workflows instances list my-workflow --local
npx wrangler workflows instances pause my-workflow <INSTANCE_ID> --local
npx wrangler workflows instances send-event my-workflow <INSTANCE_ID> --type my-event --local

All commands also accept --port to target a specific wrangler dev session (defaults to 8787).

For more information, refer to Workflows local development.

Original source Report a problem

Four new fields are now available on request.cf.tlsClientAuth in Workers for requests that include a mutual TLS (mTLS) client certificate. These fields encode the client certificate and its intermediate chain in RFC 9440 format — the same standard format used by the Client-Cert and Client-Cert-Chain HTTP headers — so your Worker can forward them directly to your origin without any custom parsing or encoding logic.

New fields

Field Type Description certRFC9440 String The client leaf certificate in RFC 9440 format (:base64-DER:). Empty if no client certificate was presented. certRFC9440TooLarge Boolean true if the leaf certificate exceeded 10 KB and was omitted from certRFC9440. certChainRFC9440 String The intermediate certificate chain in RFC 9440 format as a comma-separated list. Empty if no intermediates were sent or if the chain exceeded 16 KB. certChainRFC9440TooLarge Boolean true if the intermediate chain exceeded 16 KB and was omitted from certChainRFC9440.

Example: forwarding client certificate headers to your origin

export default {
  async fetch(request) {
    const tls = request.cf.tlsClientAuth;
    // Only forward if cert was verified and chain is complete
    if (!tls || !tls.certVerified || tls.certRevoked || tls.certChainRFC9440TooLarge) {
      return new Response("Unauthorized", { status: 401 });
    }
    const headers = new Headers(request.headers);
    headers.set("Client-Cert", tls.certRFC9440);
    headers.set("Client-Cert-Chain", tls.certChainRFC9440);
    return fetch(new Request(request, { headers }));
  },
};

For more information, refer to Client certificate variables and Mutual TLS authentication.

Original source Report a problem

Containers and Sandboxes now support connecting directly to Workers over HTTP.

This allows you to call Workers functions and bindings, like KV or R2, from within the container at specific hostnames.

Run Worker code

Define an outbound handler to capture any HTTP request or use outboundByHost to capture requests to individual hostnames and IPs.

export class MyApp extends Sandbox {}
MyApp.outbound = async (request, env, ctx) => {
  // you can run arbitrary functions defined in your Worker on any HTTP request
  return await someWorkersFunction(request.body);
};
MyApp.outboundByHost = {
  "my.worker": async (request, env, ctx) => {
    return await anotherFunction(request.body);
  },
};

In this example, requests from the container to http://my.worker will run the function defined within outboundByHost, and any other HTTP requests will run the outbound handler. These handlers run entirely inside the Workers runtime, outside of the container sandbox.

TLS support coming soon

Containers and Sandboxes currently only intercept HTTP traffic. HTTPS interception is coming soon. This will enable using Workers as a transparent proxy for credential injection.

Even though this is just using HTTP, traffic to Workers is secure and runs on the same machine as the container.

If needed, you can also upgrade requests to TLS from the Worker itself.

Access Workers bindings

Each handler has access to env, so it can call any binding set in Wrangler config.

Code inside the container makes a standard HTTP request to that hostname and the outbound Worker translates it into a binding call.

export class MyApp extends Sandbox {}
MyApp.outboundByHost = {
  "my.kv": async (request, env, ctx) => {
    const key = new URL(request.url).pathname.slice(1);
    const value = await env.KV.get(key);
    return new Response(value ?? "", { status: value ? 200 : 404 });
  },
  "my.r2": async (request, env, ctx) => {
    const key = new URL(request.url).pathname.slice(1);
    const object = await env.BUCKET.get(key);
    return new Response(object?.body ?? "", { status: object ? 200 : 404 });
  },
};

Now, from inside the container sandbox, curl http://my.kv/some-key will access Workers KV and curl http://my.r2/some-object will access R2.

Access Durable Object state

Use ctx.containerId to reference the container's automatically provisioned Durable Object.

export class MyContainer extends Container {}
MyContainer.outboundByHost = {
  "get-state.do": async (request, env, ctx) => {
    const id = env.MY_CONTAINER.idFromString(ctx.containerId);
    const stub = env.MY_CONTAINER.get(id);
    return stub.getStateForKey(request.body);
  },
};

This provides an easy way to associate state with any container instance, and includes a built-in SQLite database.

Get Started Today

Upgrade to @cloudflare/containers version 0.2.0 or later, or @cloudflare/sandbox version 0.8.0 or later to use outbound Workers.

Refer to Containers outbound traffic and Sandboxes outbound traffic for more details and examples.

Original source Report a problem

The new secrets configuration property lets you declare the secret names your Worker requires in your Wrangler configuration file. Required secrets are validated during local development and deploy, and used as the source of truth for type generation.

wrangler.jsonc

{
"secrets": {
"required": ["API_KEY", "DB_PASSWORD"],
},
}

wrangler.toml

[secrets]
required = [ "API_KEY", "DB_PASSWORD" ]

Local development

When secrets is defined, wrangler dev and vite dev load only the keys listed in secrets.required from .dev.vars or .env/process.env. Additional keys in those files are excluded. If any required secrets are missing, a warning is logged listing the missing names.

Type generation

wrangler types generates typed bindings from secrets.required instead of inferring names from .dev.vars or .env. This lets you run type generation in CI or other environments where those files are not present. Per-environment secrets are supported — the aggregated Env type marks secrets that only appear in some environments as optional.

Deploy

wrangler deploy and wrangler versions upload validate that all secrets in secrets.required are configured on the Worker before the operation succeeds. If any required secrets are missing, the command fails with an error listing which secrets need to be set.

For more information, refer to the secrets configuration property reference.

Original source Report a problem

Containers now support Docker Hub images. You can use a fully qualified Docker Hub image reference in your Wrangler configuration instead of first pushing the image to Cloudflare Registry.

wrangler.jsonc

{
  "containers": [
    {
      // Example: docker.io/cloudflare/sandbox:0.7.18
      "image": "docker.io/<NAMESPACE>/<REPOSITORY>:<TAG>",
    },
  ],
}

wrangler.toml

[[containers]]
image = "docker.io/<NAMESPACE>/<REPOSITORY>:<TAG>"

Containers also support private Docker Hub images. To configure credentials, refer to Use private Docker Hub images.

For more information, refer to Image management.

Original source Report a problem

Dynamic Workers are now in open beta for all paid Workers users. You can now have a Worker spin up other Workers, called Dynamic Workers, at runtime to execute code on-demand in a secure, sandboxed environment. Dynamic Workers start in milliseconds, making them well suited for fast, secure code execution at scale.

Use Dynamic Workers for

• Code Mode: LLMs are trained to write code. Run tool-calling logic written in code instead of stepping through many tool calls, which can save up to 80% in inference tokens and cost.
• AI agents executing code: Run code for tasks like data analysis, file transformation, API calls, and chained actions.
• Running AI-generated code: Run generated code for prototypes, projects, and automations in a secure, isolated sandboxed environment.
• Fast development and previews: Load prototypes, previews, and playgrounds in milliseconds.
• Custom automations: Create custom tools on the fly that execute a task, call an integration, or automate a workflow.

Executing Dynamic Workers

Dynamic Workers support two loading modes:

• load(code) — for one-time code execution (equivalent to calling get() with a null ID).
• get(id, callback) — caches a Dynamic Worker by ID so it can stay warm across requests. Use this when the same code will receive subsequent requests.

JavaScript

export default {
async fetch(request, env) {
const worker = env.LOADER.load({
compatibilityDate: "2026-01-01",
mainModule: "src/index.js",
modules: {
"src/index.js": `
export default {
fetch() {
return new Response("Hello from a dynamic Worker");
},
};
`,
},
// Block all outbound network access from the Dynamic Worker.
globalOutbound: null,
});
return worker.getEntrypoint().fetch(request);
},
};

TypeScript

export default {
async fetch(request: Request, env: Env): Promise<Response> {
const worker = env.LOADER.load({
compatibilityDate: "2026-01-01",
mainModule: "src/index.js",
modules: {
"src/index.js": `
export default {
fetch() {
return new Response("Hello from a dynamic Worker");
},
};
`,
},
// Block all outbound network access from the Dynamic Worker.
globalOutbound: null,
});
return worker.getEntrypoint().fetch(request);
},
};

Helper libraries for Dynamic Workers

Here are 3 new libraries to help you build with Dynamic Workers:

• @cloudflare/codemode: Replace individual tool calls with a single code() tool, so LLMs write and execute TypeScript that orchestrates multiple API calls in one pass.
• @cloudflare/worker-bundler: Resolve npm dependencies and bundle source files into ready-to-load modules for Dynamic Workers, all at runtime.
• @cloudflare/shell: Give your agent a virtual filesystem inside a Dynamic Worker with persistent storage backed by SQLite and R2.

Try it out

Dynamic Workers Starter

Use this starter to deploy a Worker that can load and execute Dynamic Workers.

Dynamic Workers Playground

Deploy the Dynamic Workers Playground to write or import code, bundle it at runtime with @cloudflare/worker-bundler, execute it through a Dynamic Worker, and see real-time responses and execution logs.

For the full API reference and configuration options, refer to the Dynamic Workers documentation.

Pricing

Dynamic Workers pricing is based on three dimensions: Dynamic Workers created daily, requests, and CPU time.

Included Additional usage Dynamic Workers created daily 1,000 unique Dynamic Workers per month Requests ¹ 10 million per month CPU time ¹ 30 million CPU milliseconds per month

¹ Uses Workers Standard rates and will appear as part of your existing Workers bill, not as separate Dynamic Workers charges.

Note: Dynamic Workers requests and CPU time are already billed as part of your Workers plan and will count toward your Workers requests and CPU usage. The Dynamic Workers created daily charge is not yet active — you will not be billed for the number of Dynamic Workers created at this time. Pricing information is shared in advance so you can estimate future costs.

Original source Report a problem

Workflow instance methods pause(), resume(), restart(), and terminate() are now available in local development when using wrangler dev.

You can now test the full Workflow instance lifecycle locally:

const instance = await env.MY_WORKFLOW.create({
id: "my-instance-id",
});
await instance.pause(); // pauses a running workflow instance
await instance.resume(); // resumes a paused instance
await instance.restart(); // restarts the instance from the beginning
await instance.terminate(); // terminates the instance immediately

Original source Report a problem

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

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

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

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

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

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

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

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

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

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

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

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

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

Original source Report a problem