Models · Cloudflare Agents docs

The Agents SDK includes model providers for Workers AI and AI Gateway. Each provider is one createAI factory over the Worker's AI binding, or an account id and API token. There are two, one per framework:

Import	Framework	Use it with
`agents/models/ai-sdk`	AI SDK ↗︎ v7	`generateText`, `streamText`, Think, and any AI SDK consumer
`agents/models/pi-ai`	Pi AI ↗︎	The Pi harness, and Pi AI's `stream`

Both take the same options, route through the same gateway, and handle Workers AI the same way. The OpenCode harness has a third, agents/models/opencode, built on the AI SDK provider.

How a model is chosen

Name a model with a string, or pass a model object built by the vendor's own package:

ai("@cf/zai-org/glm-5.3-flash"); // Workers AI
ai("anthropic/claude-opus-5.5"); // AI Gateway catalog
ai("dynamic/support"); // AI Gateway dynamic route
ai(anthropic("claude-opus-5-5")); // the vendor's own model object

A Workers AI model is a @cf/ id. It runs through env.AI.run(). A compatibility layer turns each model's response into the standard OpenAI chat completions shape.
An AI Gateway catalog model is an <author>/<model> id from the model catalog, such as anthropic/claude-opus-5.5 or openai/gpt-5.5. It also runs through env.AI.run(), which sends it to AI Gateway. The gateway picks a provider and bills the call. Use the catalog's spelling, not the vendor's: anthropic/claude-opus-5.5, not claude-opus-5-5.
A dynamic route is dynamic/<route>. The route you configured on the gateway picks the model.
A model object comes from the vendor's provider package, such as anthropic("claude-opus-5-5"). The vendor's code builds the request and parses the response. The provider sends that request unchanged through the binding to AI Gateway's provider-native endpoint for that vendor.

The providers do not use the deprecated Universal Endpoint.

What every model gets

No vendor keys. AI Gateway holds third-party credentials, through Unified Billing or a key you store on the gateway. Unified Billing requires authentication on the gateway.
Gateway options. Caching, logging, metadata, timeouts, retries, and BYOK key aliases are options on the provider, the model, or the call. The default gateway is created the first time you use it.
Fallback. List models to try in order if the first fails before it produces output. Mix Workers AI ids, catalog ids, dynamic routes, and model objects.
Stream resume. Through the binding, a stream from a catalog model or a dynamic route resumes after a dropped connection. You do not need to configure anything.
Gateway metadata on every result. Each response carries the gateway log id, cache status, run id, and the model that actually answered.

createAI from agents/models/ai-sdk replaces workers-ai-provider and ai-gateway-provider. For AI Search, use ai-search-provider.

Connect to Cloudflare

Inside a Worker, pass the AI binding, createAI({ binding: env.AI }), and add it to your Wrangler configuration:

{
	"ai": {
		"binding": "AI",
	},
}

[ai]
binding = "AI"

To use a gateway in another account, or to call from outside a Worker, pass an account id and API token instead. Create the token with Workers AI Read and AI Gateway Run:

const ai = createAI({
	accountId: "<ACCOUNT_ID>",
	apiToken: env.CLOUDFLARE_API_TOKEN,
	gateway: "my-gateway",
});

Call models from a Durable Object

An agent is a Durable Object with the Agents SDK Lifecycle ↗︎ installed. Lifecycle.install(this) installs the platform fetch, alarm, and WebSocket handlers, and calls your onStart(), onRequest(), and onAlarm() callbacks instead. You can call models from any of these callbacks, from a WebSocket handler, or from your own RPC methods.

A Durable Object can call models on its own, without a client waiting, and can handle responses that take minutes (or longer) to finish.

To reach the Durable Object from your Worker, route requests with routeAgentRequest(). The default URL shape is /agents/:binding/:name:

src/index.jsjs

import { routeAgentRequest } from "agents";

export default {
	async fetch(request, env) {
		return (
			(await routeAgentRequest(request, env)) ??
			new Response("Not found", { status: 404 })
		);
	},
};

src/index.tsts

import { routeAgentRequest } from "agents";

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		return (
			(await routeAgentRequest(request, env)) ??
			new Response("Not found", { status: 404 })
		);
	},
} satisfies ExportedHandler<Env>;

The examples on this page show only the Durable Object class. To add the Durable Object binding to your Wrangler configuration, refer to Get started with Durable Objects.

Generate text with the AI SDK

npm i agents ai @ai-sdk/provider

yarn add agents ai @ai-sdk/provider

pnpm add agents ai @ai-sdk/provider

bun add agents ai @ai-sdk/provider

src/index.jsjs

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { generateText } from "ai";
import { createAI } from "agents/models/ai-sdk";

export class MyAgent extends DurableObject {
	lifecycle = Lifecycle.install(this);

	async onRequest(request) {
		const ai = createAI({ binding: this.env.AI });
		const { text } = await generateText({
			model: ai("anthropic/claude-opus-5.5"),
			prompt: "Build me an AI agent on Cloudflare Workers",
		});

		return Response.json({ modelResponse: text });
	}
}

src/index.tsts

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { generateText } from "ai";
import { createAI } from "agents/models/ai-sdk";

interface Env {
	AI: Ai;
}

export class MyAgent extends DurableObject<Env> {
	readonly lifecycle = Lifecycle.install(this);

	async onRequest(request: Request): Promise<Response> {
		const ai = createAI({ binding: this.env.AI });
		const { text } = await generateText({
			model: ai("anthropic/claude-opus-5.5"),
			prompt: "Build me an AI agent on Cloudflare Workers",
		});

		return Response.json({ modelResponse: text });
	}
}

To use a different model, change the string, such as ai("openai/gpt-5.5") or ai("@cf/zai-org/glm-5.3-flash"), or pass the vendor's own model object, such as ai(openai("gpt-5.5")). All of these route through AI Gateway, so you do not need a vendor API key in your Worker.

You can also use any other AI SDK provider directly, without createAI. The call then goes straight to the vendor, with your own API key, and skips AI Gateway:

npm i ai @ai-sdk/openai

yarn add ai @ai-sdk/openai

pnpm add ai @ai-sdk/openai

bun add ai @ai-sdk/openai

src/index.jsjs

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { generateText } from "ai";
import { createOpenAI } from "@ai-sdk/openai";

export class MyAgent extends DurableObject {
	lifecycle = Lifecycle.install(this);

	async onRequest(request) {
		const openai = createOpenAI({ apiKey: this.env.OPENAI_API_KEY });
		const { text } = await generateText({
			model: openai("gpt-5.5"),
			prompt: "Build me an AI agent on Cloudflare Workers",
		});

		return Response.json({ modelResponse: text });
	}
}

src/index.tsts

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { generateText } from "ai";
import { createOpenAI } from "@ai-sdk/openai";

interface Env {
	OPENAI_API_KEY: string;
}

export class MyAgent extends DurableObject<Env> {
	readonly lifecycle = Lifecycle.install(this);

	async onRequest(request: Request): Promise<Response> {
		const openai = createOpenAI({ apiKey: this.env.OPENAI_API_KEY });
		const { text } = await generateText({
			model: openai("gpt-5.5"),
			prompt: "Build me an AI agent on Cloudflare Workers",
		});

		return Response.json({ modelResponse: text });
	}
}

Stream over WebSockets

Reasoning models can take some time to both generate a response and stream it back to the client. Instead of buffering the entire response, stream it back over a WebSocket. Install the WebSockets capability to accept upgrades and handle messages. Without it, the Lifecycle declines WebSocket upgrades:

src/index.jsjs

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { WebSockets } from "agents/websockets";
import { streamText } from "ai";
import { createAI } from "agents/models/ai-sdk";

export class MyAgent extends DurableObject {
	webSockets = new WebSockets({
		handlers: {
			onMessage: (connection, message) => this.reply(connection, message),
		},
	});

	lifecycle = Lifecycle.install(this).use(this.webSockets);

	async reply(connection, message) {
		const { prompt } = JSON.parse(message);

		try {
			const ai = createAI({ binding: this.env.AI });
			const result = streamText({
				model: ai("anthropic/claude-opus-5.5"),
				prompt,
			});

			for await (const chunk of result.textStream) {
				if (chunk) {
					connection.send(JSON.stringify({ type: "chunk", content: chunk }));
				}
			}

			connection.send(JSON.stringify({ type: "done" }));
		} catch (error) {
			connection.send(JSON.stringify({ type: "error", error: String(error) }));
		}
	}
}

src/index.tsts

import { DurableObject } from "cloudflare:workers";
import { Lifecycle, type Connection } from "agents/lifecycle";
import { WebSockets, type WebSocketMessage } from "agents/websockets";
import { streamText } from "ai";
import { createAI } from "agents/models/ai-sdk";

interface Env {
	AI: Ai;
}

export class MyAgent extends DurableObject<Env> {
	readonly webSockets = new WebSockets({
		handlers: {
			onMessage: (connection, message) => this.reply(connection, message),
		},
	});

	readonly lifecycle = Lifecycle.install(this).use(this.webSockets);

	async reply(connection: Connection, message: WebSocketMessage) {
		const { prompt } = JSON.parse(message as string);

		try {
			const ai = createAI({ binding: this.env.AI });
			const result = streamText({
				model: ai("anthropic/claude-opus-5.5"),
				prompt,
			});

			for await (const chunk of result.textStream) {
				if (chunk) {
					connection.send(JSON.stringify({ type: "chunk", content: chunk }));
				}
			}

			connection.send(JSON.stringify({ type: "done" }));
		} catch (error) {
			connection.send(JSON.stringify({ type: "error", error: String(error) }));
		}
	}
}

To survive a dropped connection, save each response with the SQLite storage API on this.ctx.storage. When the client reconnects, read the message history back and send it.

Call the AI binding directly

You do not need a provider to call a model. You can call env.AI.run() with any of the Workers AI models. No API keys are required. Refer to Workers AI bindings for the full binding API.

Set stream: true to avoid buffering and delaying responses, especially for larger models or reasoning models:

src/index.jsjs

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";

export class MyAgent extends DurableObject {
	lifecycle = Lifecycle.install(this);

	async onRequest(request) {
		const stream = await this.env.AI.run("@cf/zai-org/glm-5.3-flash", {
			messages: [
				{
					role: "user",
					content: "Build me a Cloudflare Worker that returns JSON.",
				},
			],
			stream: true,
		});

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

src/index.tsts

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";

interface Env {
	AI: Ai;
}

export class MyAgent extends DurableObject<Env> {
	readonly lifecycle = Lifecycle.install(this);

	async onRequest(request: Request): Promise<Response> {
		const stream = await this.env.AI.run("@cf/zai-org/glm-5.3-flash", {
			messages: [
				{
					role: "user",
					content: "Build me a Cloudflare Worker that returns JSON.",
				},
			],
			stream: true,
		});

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

To send the call through AI Gateway, pass a gateway option. The gateway can then cache responses and route requests across providers based on availability, rate limits, or cost budgets:

src/index.jsjs

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";

export class MyAgent extends DurableObject {
	lifecycle = Lifecycle.install(this);

	async onRequest(request) {
		const response = await this.env.AI.run(
			"@cf/zai-org/glm-5.3-flash",
			{
				messages: [
					{
						role: "user",
						content: "Build me a Cloudflare Worker that returns JSON.",
					},
				],
			},
			{
				gateway: {
					id: "{gateway_id}",
					skipCache: false,
					cacheTtl: 3360,
				},
			},
		);

		return Response.json(response);
	}
}

src/index.tsts

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";

interface Env {
	AI: Ai;
}

export class MyAgent extends DurableObject<Env> {
	readonly lifecycle = Lifecycle.install(this);

	async onRequest(request: Request): Promise<Response> {
		const response = await this.env.AI.run(
			"@cf/zai-org/glm-5.3-flash",
			{
				messages: [
					{
						role: "user",
						content: "Build me a Cloudflare Worker that returns JSON.",
					},
				],
			},
			{
				gateway: {
					id: "{gateway_id}",
					skipCache: false,
					cacheTtl: 3360,
				},
			},
		);

		return Response.json(response);
	}
}

The same ai binding serves both Workers AI and AI Gateway. Refer to the AI Gateway documentation to configure a gateway and find its ID.

OpenAI-compatible endpoints

You can call models on any service that supports the OpenAI API. For example, use the OpenAI SDK to call one of Google's Gemini models ↗︎. These calls go straight to the vendor with your own API key.

Stream the response back over HTTP with Server-Sent Events (SSE) from fetch, or over a WebSocket.

src/index.jsjs

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { OpenAI } from "openai";

export class MyAgent extends DurableObject {
	lifecycle = Lifecycle.install(this);

	async onRequest(request) {
		const client = new OpenAI({
			apiKey: this.env.GEMINI_API_KEY,
			baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
		});

		const stream = await client.chat.completions.create({
			model: "gemini-3.5-flash",
			messages: [{ role: "user", content: "Write me a Cloudflare Worker." }],
			stream: true,
		});

		const encoder = new TextEncoder();
		const body = new ReadableStream({
			async start(controller) {
				for await (const part of stream) {
					controller.enqueue(
						encoder.encode(part.choices[0]?.delta?.content ?? ""),
					);
				}
				controller.close();
			},
		});

		return new Response(body);
	}
}

src/index.tsts

import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { OpenAI } from "openai";

interface Env {
	GEMINI_API_KEY: string;
}

export class MyAgent extends DurableObject<Env> {
	readonly lifecycle = Lifecycle.install(this);

	async onRequest(request: Request): Promise<Response> {
		const client = new OpenAI({
			apiKey: this.env.GEMINI_API_KEY,
			baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
		});

		const stream = await client.chat.completions.create({
			model: "gemini-3.5-flash",
			messages: [{ role: "user", content: "Write me a Cloudflare Worker." }],
			stream: true,
		});

		const encoder = new TextEncoder();
		const body = new ReadableStream({
			async start(controller) {
				for await (const part of stream) {
					controller.enqueue(
						encoder.encode(part.choices[0]?.delta?.content ?? ""),
					);
				}
				controller.close();
			},
		});

		return new Response(body);
	}
}

Choose a provider

AI SDK

A full AI SDK ProviderV4 for text, tools, structured output, embeddings, images, speech, transcription, and reranking.

Pi AI

Pi AI models for the Pi harness, Pi Durable, and any framework built on a Pi AI Models registry.