From 59ea7fd3ed8c7d8864c96c601de510301d68fc2d Mon Sep 17 00:00:00 2001 From: Matt Carey Date: Tue, 20 Oct 2026 21:47:41 +0100 Subject: [PATCH 1/4] [Workers AI, AI Gateway] Move docs off workers-ai-provider and ai-gateway-provider --- ...rovider-ai-gateway-provider-deprecated.mdx | 33 +++ src/content/docs/agent-memory/get-started.mdx | 8 +- .../chat/chat-agents.mdx | 36 +-- .../agents/communication-channels/voice.mdx | 6 +- .../docs/agents/concepts/calling-llms.mdx | 24 +- .../docs/agents/examples/browser-agent.mdx | 12 +- .../docs/agents/examples/chat-agent.mdx | 8 +- .../docs/agents/examples/voice-agent.mdx | 6 +- .../agents/harnesses/think/configuration.mdx | 2 +- .../harnesses/think/getting-started.mdx | 8 +- .../docs/agents/harnesses/think/index.mdx | 6 +- .../apis/client-api.mdx | 6 +- .../agents/runtime/communication/http-sse.mdx | 6 +- .../runtime/operations/using-ai-models.mdx | 16 +- src/content/docs/agents/tools/browser.mdx | 6 +- .../docs/agents/tools/codemode/browser.mdx | 6 +- src/content/docs/agents/tools/filesystem.mdx | 4 +- src/content/docs/agents/tools/mcp.mdx | 6 +- src/content/docs/agents/tools/sandbox.mdx | 4 +- .../ai-gateway/integrations/vercel-ai-sdk.mdx | 124 ++++++++-- .../docs/ai-search/agent-sdks/agents-sdk.mdx | 10 +- .../how-to/talk-to-your-knowledge-base.mdx | 6 +- .../build-an-ai-code-interpreter.mdx | 10 +- .../sdk/tutorials/ai-code-executor.mdx | 2 +- .../docs/workers-ai/configuration/ai-sdk.mdx | 231 +++++++++++------- 25 files changed, 377 insertions(+), 209 deletions(-) create mode 100644 src/content/changelog/workers-ai/2026-10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx diff --git a/src/content/changelog/workers-ai/2026-10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx b/src/content/changelog/workers-ai/2026-10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx new file mode 100644 index 00000000000..30bc959491c --- /dev/null +++ b/src/content/changelog/workers-ai/2026-10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx @@ -0,0 +1,33 @@ +--- +title: workers-ai-provider and ai-gateway-provider are deprecated +description: The workers-ai-provider and ai-gateway-provider npm packages are deprecated. Use createAI from agents/models/ai-sdk, and ai-search-provider for AI Search. +products: + - workers-ai + - ai-gateway +date: 2026-10-21 +--- + +The `workers-ai-provider` and `ai-gateway-provider` npm packages are deprecated. To call Workers AI and AI Gateway from the [AI SDK](https://ai-sdk.dev/), use [`createAI`](/agents/models/ai-sdk/) from `agents/models/ai-sdk`. For AI Search, use [`ai-search-provider`](/ai-search/agent-sdks/ai-sdk/). + +Existing code keeps working. Nothing changes at runtime. + +```sh +npm install agents ai @ai-sdk/provider +``` + +```ts +import { createAI } from "agents/models/ai-sdk"; + +const ai = createAI({ binding: env.AI }); + +const model = ai("@cf/zai-org/glm-4.7-flash"); +``` + +| Before | After | +| ------------------------------------------------------- | -------------------------------------------------------- | +| `createWorkersAI({ binding })` | `createAI({ binding })` | +| `createWorkersAI({ accountId, apiKey })` | `createAI({ accountId, apiToken })` | +| `createAiGateway(...)` | `createAI(...)`, with `fallback` for a list of models | +| `createAISearch` from `workers-ai-provider` | `createAISearchNamespace` from `ai-search-provider` | + +For more information, refer to [AI SDK](/agents/models/ai-sdk/). diff --git a/src/content/docs/agent-memory/get-started.mdx b/src/content/docs/agent-memory/get-started.mdx index 52931736416..ac18713e71f 100644 --- a/src/content/docs/agent-memory/get-started.mdx +++ b/src/content/docs/agent-memory/get-started.mdx @@ -55,7 +55,7 @@ cd memory-agent Install the dependencies used by this guide: - + ## 2. Create a namespace @@ -183,7 +183,7 @@ Change the `agents` import and add the AI SDK imports. Keep the `Session` import import { Agent, getAgentByName, routeAgentRequest } from "agents"; import { convertToModelMessages, generateText, stepCountIs } from "ai"; import type { UIMessage } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; ``` @@ -218,9 +218,9 @@ export class ChatAgent extends Agent { await this.scheduleIngest(); - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = await generateText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), system: await this.session.freezeSystemPrompt(), messages: await convertToModelMessages( (await this.session.getHistory()) as UIMessage[], diff --git a/src/content/docs/agents/communication-channels/chat/chat-agents.mdx b/src/content/docs/agents/communication-channels/chat/chat-agents.mdx index 0795d15836e..d09c77754bd 100644 --- a/src/content/docs/agents/communication-channels/chat/chat-agents.mdx +++ b/src/content/docs/agents/communication-channels/chat/chat-agents.mdx @@ -40,7 +40,7 @@ Built on the [AI SDK](https://ai-sdk.dev) and Cloudflare Durable Objects, you ge ### Install - + ### Server @@ -48,16 +48,16 @@ Built on the [AI SDK](https://ai-sdk.dev) and Cloudflare Durable Objects, you ge ```ts import { AIChatAgent } from "@cloudflare/ai-chat"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; import { streamText, convertToModelMessages } from "ai"; export class ChatAgent extends AIChatAgent { async onChatMessage() { - // Use any provider such as workers-ai-provider, openai, anthropic, google, etc. - const workersai = createWorkersAI({ binding: this.env.AI }); + // Use any AI SDK provider, such as createAI from agents/models/ai-sdk, openai, anthropic, or google. + const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), messages: await convertToModelMessages(this.messages), }); @@ -194,10 +194,10 @@ This is the main method you override. It receives the conversation context and s ```ts export class ChatAgent extends AIChatAgent { async onChatMessage() { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), system: "You are a helpful assistant.", messages: await convertToModelMessages(this.messages), }); @@ -270,10 +270,10 @@ import { streamText, convertToModelMessages, pruneMessages } from "ai"; export class ChatAgent extends AIChatAgent { async onChatMessage() { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), messages: pruneMessages({ messages: await convertToModelMessages(this.messages), reasoning: "before-last-message", @@ -550,7 +550,7 @@ When a user clicks "stop" in the chat UI, the client sends a `CF_AGENT_CHAT_REQU export class ChatAgent extends AIChatAgent { async onChatMessage(_onFinish, options) { const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), messages: await convertToModelMessages(this.messages), abortSignal: options?.abortSignal, // Pass through for cancellation }); @@ -949,10 +949,10 @@ import { streamText, convertToModelMessages, tool, stepCountIs } from "ai"; import { z } from "zod"; export class ChatAgent extends AIChatAgent { async onChatMessage() { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), messages: await convertToModelMessages(this.messages), tools: { getWeather: tool({ @@ -1201,12 +1201,12 @@ import { export class ChatAgent extends AIChatAgent { async onChatMessage() { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const stream = createUIMessageStream({ execute: async ({ writer }) => { const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), messages: await convertToModelMessages(this.messages), }); @@ -1380,7 +1380,7 @@ Storage (`maxPersistedMessages`) and LLM context are independent: export class ChatAgent extends AIChatAgent { async onChatMessage() { const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), messages: pruneMessages({ // LLM context limit messages: await convertToModelMessages(this.messages), @@ -1405,11 +1405,11 @@ export class ChatAgent extends AIChatAgent { ```ts -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; -const workersai = createWorkersAI({ binding: this.env.AI }); +const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), messages: await convertToModelMessages(this.messages), }); ``` diff --git a/src/content/docs/agents/communication-channels/voice.mdx b/src/content/docs/agents/communication-channels/voice.mdx index 2314189c260..1d54af060c3 100644 --- a/src/content/docs/agents/communication-channels/voice.mdx +++ b/src/content/docs/agents/communication-channels/voice.mdx @@ -243,17 +243,17 @@ export class MyAgent extends VoiceAgent { ```ts import { streamText } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; export class MyAgent extends VoiceAgent { transcriber = new WorkersAIFluxSTT(this.env.AI); tts = new WorkersAITTS(this.env.AI); async onTurn(transcript: string, context: VoiceTurnContext) { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersai("@cf/moonshotai/kimi-k2.6"), + model: ai("@cf/moonshotai/kimi-k2.6"), system: "You are a helpful voice assistant. Keep responses concise.", messages: [ ...context.messages.map((m) => ({ diff --git a/src/content/docs/agents/concepts/calling-llms.mdx b/src/content/docs/agents/concepts/calling-llms.mdx index 8ad30643d7c..45d48faf6ac 100644 --- a/src/content/docs/agents/concepts/calling-llms.mdx +++ b/src/content/docs/agents/concepts/calling-llms.mdx @@ -58,15 +58,15 @@ An Agent keeps running after the client disconnects. When the response arrives, ```ts import { Agent } from "agents"; import { streamText } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; export class MyAgent extends Agent { async onMessage(connection: Connection, message: WSMessage) { const { prompt } = JSON.parse(message as string); - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), prompt, }); @@ -103,9 +103,9 @@ export class DigestAgent extends Agent { SELECT title, body FROM articles WHERE created_at > datetime('now', '-1 day')`; - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const { text } = await generateText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), prompt: `Summarize these articles:\n${articles.map((a) => a.title + ": " + a.body).join("\n\n")}`, }); @@ -128,25 +128,25 @@ Because an Agent maintains state across calls, you can chain multiple models in ```ts import { Agent } from "agents"; import { generateText, embed } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; export class TriageAgent extends Agent { async triage(ticket: string) { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const { text: category } = await generateText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), prompt: `Classify this support ticket into one of: billing, technical, account. Ticket: ${ticket}`, }); const { embedding } = await embed({ - model: workersai("@cf/baai/bge-base-en-v1.5"), + model: ai.embedding("@cf/baai/bge-base-en-v1.5"), value: ticket, }); const similar = await this.env.VECTOR_DB.query(embedding, { topK: 5 }); const { text: response } = await generateText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), prompt: `Draft a response for this ${category} ticket. Similar resolved tickets: ${JSON.stringify(similar)}. Ticket: ${ticket}`, }); @@ -180,9 +180,9 @@ export class CachingAgent extends Agent { return cached[0].response; } - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const { text } = await generateText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), prompt, }); diff --git a/src/content/docs/agents/examples/browser-agent.mdx b/src/content/docs/agents/examples/browser-agent.mdx index 2a0985df7ba..bfd90b3d310 100644 --- a/src/content/docs/agents/examples/browser-agent.mdx +++ b/src/content/docs/agents/examples/browser-agent.mdx @@ -93,12 +93,12 @@ Pass browser tools alongside your other tools. The `model` can be any AI SDK pro ```ts import { streamText } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; -const workersai = createWorkersAI({ binding: env.AI }); +const ai = createAI({ binding: env.AI }); const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), system: "You are a helpful assistant that can inspect web pages.", messages, tools: { @@ -151,19 +151,19 @@ The typical pattern is to create browser tools inside an [`AIChatAgent`](/agents ```ts import { AIChatAgent } from "@cloudflare/ai-chat"; import { createBrowserTools } from "agents/browser/ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; import { streamText, convertToModelMessages, stepCountIs } from "ai"; export class MyAgent extends AIChatAgent { async onChatMessage() { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const browserTools = createBrowserTools({ browser: this.env.BROWSER, loader: this.env.LOADER, }); const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), system: "You can browse the web and inspect pages.", messages: await convertToModelMessages(this.messages), tools: { diff --git a/src/content/docs/agents/examples/chat-agent.mdx b/src/content/docs/agents/examples/chat-agent.mdx index 1f44045af8d..32169801577 100644 --- a/src/content/docs/agents/examples/chat-agent.mdx +++ b/src/content/docs/agents/examples/chat-agent.mdx @@ -35,7 +35,7 @@ Select **"Hello World" Worker** when prompted. Then install the dependencies: ```sh cd chat-agent -npm install agents @cloudflare/ai-chat ai workers-ai-provider zod +npm install agents @cloudflare/ai-chat ai @ai-sdk/provider zod ``` ## 2. Configure Wrangler @@ -76,7 +76,7 @@ Create `src/server.ts`. This is where your agent lives: ```ts import { AIChatAgent } from "@cloudflare/ai-chat"; import { routeAgentRequest } from "agents"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; import { streamText, convertToModelMessages, @@ -88,10 +88,10 @@ import { z } from "zod"; export class ChatAgent extends AIChatAgent { async onChatMessage() { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersai("@cf/meta/llama-4-scout-17b-16e-instruct"), + model: ai("@cf/meta/llama-4-scout-17b-16e-instruct"), system: "You are a helpful assistant. You can check the weather, " + "get the user's timezone, and run calculations.", diff --git a/src/content/docs/agents/examples/voice-agent.mdx b/src/content/docs/agents/examples/voice-agent.mdx index a20ef51b612..1a439fa4cd6 100644 --- a/src/content/docs/agents/examples/voice-agent.mdx +++ b/src/content/docs/agents/examples/voice-agent.mdx @@ -94,7 +94,7 @@ import { type VoiceTurnContext, } from "@cloudflare/voice"; import { streamText, tool, stepCountIs } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; import { z } from "zod"; const VoiceAgent = withVoice(Agent); @@ -104,10 +104,10 @@ export class MyVoiceAgent extends VoiceAgent { tts = new WorkersAITTS(this.env.AI); async onTurn(transcript: string, context: VoiceTurnContext) { - const workersAi = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersAi("@cf/moonshotai/kimi-k2.6"), + model: ai("@cf/moonshotai/kimi-k2.6"), system: "You are a helpful voice assistant. Keep responses concise — you are being spoken aloud.", messages: [ diff --git a/src/content/docs/agents/harnesses/think/configuration.mdx b/src/content/docs/agents/harnesses/think/configuration.mdx index ed1f3c95439..f6e15ba066c 100644 --- a/src/content/docs/agents/harnesses/think/configuration.mdx +++ b/src/content/docs/agents/harnesses/think/configuration.mdx @@ -52,7 +52,7 @@ export class MyAgent extends Think { fast: "@cf/moonshotai/kimi-k2.6", capable: "@cf/meta/llama-4-scout-17b-16e-instruct", }; - return createWorkersAI({ binding: this.env.AI })(models[tier]); + return createAI({ binding: this.env.AI })(models[tier]); } } ``` diff --git a/src/content/docs/agents/harnesses/think/getting-started.mdx b/src/content/docs/agents/harnesses/think/getting-started.mdx index 428046a1c87..065acce96db 100644 --- a/src/content/docs/agents/harnesses/think/getting-started.mdx +++ b/src/content/docs/agents/harnesses/think/getting-started.mdx @@ -37,7 +37,7 @@ npm init -y Install dependencies: ```sh -npm install @cloudflare/think @cloudflare/computer @cloudflare/ai-chat agents ai zod workers-ai-provider react react-dom +npm install @cloudflare/think @cloudflare/computer @cloudflare/ai-chat agents ai zod @ai-sdk/provider react react-dom npm install -D wrangler @cloudflare/vite-plugin @cloudflare/workers-types @vitejs/plugin-react @tailwindcss/vite tailwindcss typescript vite ``` @@ -101,12 +101,12 @@ Create `src/server.ts`: ```ts import { Think } from "@cloudflare/think"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; import { routeAgentRequest } from "agents"; export class MyAgent extends Think { getModel() { - return createWorkersAI({ binding: this.env.AI })( + return createAI({ binding: this.env.AI })( "@cf/moonshotai/kimi-k2.6", ); } @@ -226,7 +226,7 @@ Override `configureSession` to give the model writable memory that survives rest ```ts export class MyAgent extends Think { getModel(): LanguageModel { - return createWorkersAI({ binding: this.env.AI })( + return createAI({ binding: this.env.AI })( "@cf/moonshotai/kimi-k2.6", ); } diff --git a/src/content/docs/agents/harnesses/think/index.mdx b/src/content/docs/agents/harnesses/think/index.mdx index e11a8dbfe35..4fa40869ad9 100644 --- a/src/content/docs/agents/harnesses/think/index.mdx +++ b/src/content/docs/agents/harnesses/think/index.mdx @@ -32,7 +32,7 @@ If this is your first agent, start with the [Getting started tutorial](/agents/h ### Install - + Think supports AI SDK v6 and v7. Use `ai@^6` with `@ai-sdk/react@^3`, or use `ai@^7` with `@ai-sdk/react@^4`. Keep the AI SDK packages on matching major versions throughout your project. @@ -42,12 +42,12 @@ Think supports AI SDK v6 and v7. Use `ai@^6` with `@ai-sdk/react@^3`, or use `ai ```ts import { Think } from "@cloudflare/think"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; import { routeAgentRequest } from "agents"; export class MyAgent extends Think { getModel() { - return createWorkersAI({ binding: this.env.AI })( + return createAI({ binding: this.env.AI })( "@cf/moonshotai/kimi-k2.6", ); } diff --git a/src/content/docs/agents/model-context-protocol/apis/client-api.mdx b/src/content/docs/agents/model-context-protocol/apis/client-api.mdx index 2b061bc435e..097dccef32a 100644 --- a/src/content/docs/agents/model-context-protocol/apis/client-api.mdx +++ b/src/content/docs/agents/model-context-protocol/apis/client-api.mdx @@ -349,13 +349,13 @@ To use MCP tools with the AI SDK, use `this.mcp.getAITools()` which converts MCP ```ts import { generateText } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; export class MyAgent extends Agent { async onRequest(request: Request) { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const response = await generateText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), prompt: "What's the weather in San Francisco?", tools: this.mcp.getAITools(), }); diff --git a/src/content/docs/agents/runtime/communication/http-sse.mdx b/src/content/docs/agents/runtime/communication/http-sse.mdx index cda13eb8cda..860023ce43c 100644 --- a/src/content/docs/agents/runtime/communication/http-sse.mdx +++ b/src/content/docs/agents/runtime/communication/http-sse.mdx @@ -118,7 +118,7 @@ The [AI SDK](https://ai-sdk.dev/) provides built-in SSE streaming: ```ts import { Agent } from "agents"; import { streamText } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; interface Env { AI: Ai; @@ -128,10 +128,10 @@ export class ChatAgent extends Agent { async onRequest(request: Request): Promise { const { prompt } = await request.json<{ prompt: string }>(); - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), prompt: prompt, }); diff --git a/src/content/docs/agents/runtime/operations/using-ai-models.mdx b/src/content/docs/agents/runtime/operations/using-ai-models.mdx index 13a93257a05..9e5d8ff5066 100644 --- a/src/content/docs/agents/runtime/operations/using-ai-models.mdx +++ b/src/content/docs/agents/runtime/operations/using-ai-models.mdx @@ -39,7 +39,7 @@ Modern reasoning models can take some time to both generate a response _and_ str ```ts import { Agent } from "agents"; import { streamText } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; interface Env { AI: Ai; @@ -57,9 +57,9 @@ export class MyAgent extends Agent { async queryReasoningModel(connection: Connection, userPrompt: string) { try { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), prompt: userPrompt, }); @@ -183,16 +183,16 @@ Visit the [AI Gateway documentation](/ai-gateway/) to learn how to configure a g ## AI SDK -The [AI SDK](https://ai-sdk.dev/docs/introduction) provides a unified API for text generation, tool calling, structured responses, and more. It works with any provider that has an AI SDK adapter, including Workers AI via [`workers-ai-provider`](https://www.npmjs.com/package/workers-ai-provider). +The [AI SDK](https://ai-sdk.dev/docs/introduction) provides a unified API for text generation, tool calling, structured responses, and more. It works with any provider that has an AI SDK adapter, including Workers AI and AI Gateway through [`createAI`](/agents/models/ai-sdk/) from `agents/models/ai-sdk`. - + ```ts import { Agent } from "agents"; import { generateText } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; interface Env { AI: Ai; @@ -200,9 +200,9 @@ interface Env { export class MyAgent extends Agent { async onRequest(request: Request): Promise { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const { text } = await generateText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), prompt: "Build me an AI agent on Cloudflare Workers", }); diff --git a/src/content/docs/agents/tools/browser.mdx b/src/content/docs/agents/tools/browser.mdx index 8bc6f0d7305..04d906b59e8 100644 --- a/src/content/docs/agents/tools/browser.mdx +++ b/src/content/docs/agents/tools/browser.mdx @@ -344,11 +344,11 @@ Create browser tools with the Browser Run and Worker Loader bindings, then pass import { AIChatAgent } from "@cloudflare/ai-chat"; import { createBrowserTools } from "agents/browser/ai"; import { streamText, convertToModelMessages, stepCountIs } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; export class BrowserAgent extends AIChatAgent { async onChatMessage() { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const browserTools = createBrowserTools({ ctx: this.ctx, browser: this.env.BROWSER, @@ -356,7 +356,7 @@ export class BrowserAgent extends AIChatAgent { }); const result = streamText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), system: "You can inspect web pages with browser tools.", messages: await convertToModelMessages(this.messages), tools: browserTools, diff --git a/src/content/docs/agents/tools/codemode/browser.mdx b/src/content/docs/agents/tools/codemode/browser.mdx index 6429e787f97..94d293b855a 100644 --- a/src/content/docs/agents/tools/codemode/browser.mdx +++ b/src/content/docs/agents/tools/codemode/browser.mdx @@ -157,7 +157,7 @@ The browser creates the Code Mode tool and registers it as a dynamic client tool ```ts import { AIChatAgent, createToolsFromClientSchemas } from "@cloudflare/ai-chat"; import { convertToModelMessages, stepCountIs, streamText } from "ai"; - import { createWorkersAI } from "workers-ai-provider"; + import { createAI } from "agents/models/ai-sdk"; export class BrowserCodemode extends AIChatAgent { async onChatMessage( @@ -166,10 +166,10 @@ The browser creates the Code Mode tool and registers it as a dynamic client tool clientTools?: Parameters[0]; } ) { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersai("@cf/moonshotai/kimi-k2.7-code"), + model: ai("@cf/moonshotai/kimi-k2.7-code"), system: "Use the codemode tool to write JavaScript that calls browser-provided tools.", messages: await convertToModelMessages(this.messages), diff --git a/src/content/docs/agents/tools/filesystem.mdx b/src/content/docs/agents/tools/filesystem.mdx index f8a1cf1d3e7..9e6471eca72 100644 --- a/src/content/docs/agents/tools/filesystem.mdx +++ b/src/content/docs/agents/tools/filesystem.mdx @@ -175,14 +175,14 @@ import { Workspace } from "@cloudflare/computer"; import { createAITools } from "@cloudflare/computer/tools/ai-sdk"; import { generateText, stepCountIs } from "ai"; import { DurableObject } from "cloudflare:workers"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; export class WriterAgent extends DurableObject { workspace = new Workspace({ storage: this.ctx.storage }); async write(prompt: string) { const { text } = await generateText({ - model: createWorkersAI({ binding: this.env.AI })( + model: createAI({ binding: this.env.AI })( "@cf/moonshotai/kimi-k2.6", ), system: diff --git a/src/content/docs/agents/tools/mcp.mdx b/src/content/docs/agents/tools/mcp.mdx index 5d73ff761b0..9f9e9904206 100644 --- a/src/content/docs/agents/tools/mcp.mdx +++ b/src/content/docs/agents/tools/mcp.mdx @@ -30,7 +30,7 @@ Call `addMcpServer()` to connect to a remote MCP server, then pass `this.mcp.get ```ts import { Agent } from "agents"; import { generateText } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; export class ToolAgent extends Agent { async onStart() { @@ -38,10 +38,10 @@ export class ToolAgent extends Agent { } async onRequest(request: Request) { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const response = await generateText({ - model: workersai("@cf/zai-org/glm-4.7-flash"), + model: ai("@cf/zai-org/glm-4.7-flash"), prompt: "Use available tools to summarize the latest issue activity.", tools: this.mcp.getAITools(), }); diff --git a/src/content/docs/agents/tools/sandbox.mdx b/src/content/docs/agents/tools/sandbox.mdx index f6c5cecf49d..7e4b17b3af0 100644 --- a/src/content/docs/agents/tools/sandbox.mdx +++ b/src/content/docs/agents/tools/sandbox.mdx @@ -39,7 +39,7 @@ The following [Think](/agents/harnesses/think/) agent gives the model one tool, import { Think } from "@cloudflare/think"; import { routeAgentRequest } from "agents"; import { tool } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; import { z } from "zod"; const MAX_OUTPUT_CHARS = 10_000; @@ -59,7 +59,7 @@ export class CodeAgent extends Think { } getModel() { - return createWorkersAI({ binding: this.env.AI })( + return createAI({ binding: this.env.AI })( "@cf/moonshotai/kimi-k2.6", ); } diff --git a/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx b/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx index 41463ad0e53..2bbf8f94357 100644 --- a/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx +++ b/src/content/docs/ai-gateway/integrations/vercel-ai-sdk.mdx @@ -1,6 +1,6 @@ --- title: Vercel AI SDK -description: Route Vercel AI SDK requests through AI Gateway using the ai-gateway-provider package. +description: Call AI Gateway from the AI SDK with createAI from agents/models/ai-sdk. pcx_content_type: configuration sidebar: order: 2 @@ -8,60 +8,130 @@ products: - ai-gateway --- -import { Details, Tabs, TabItem, TypeScriptExample } from "~/components"; -import CodeSnippets from "~/components/ai-gateway/code-examples.astro"; +import { + PackageManagers, + TypeScriptExample, + WranglerConfig, +} from "~/components"; -The [Vercel AI SDK](https://sdk.vercel.ai/) is a TypeScript library for building AI applications. The SDK supports many different AI providers, tools for streaming completions, and more. -To use Cloudflare AI Gateway with Vercel AI SDK, you will need to use the `ai-gateway-provider` package. +To call AI Gateway from the [AI SDK](https://ai-sdk.dev/), use `createAI` from `agents/models/ai-sdk`. It calls models from the [model catalog](/ai/models/), [dynamic routes](/ai-gateway/features/dynamic-routing/), and a vendor's own AI SDK models through your gateway. This page covers the AI Gateway features. For the full reference, refer to [AI SDK](/agents/models/ai-sdk/). + +The `ai-gateway-provider` package is deprecated. Use `createAI` instead. ## Installation -```bash -npm install ai-gateway-provider -``` +Install the Agents SDK and the AI SDK. `createAI` needs `ai@^7` and `@ai-sdk/provider@^4`: + + -## Examples +In a Worker, add the `AI` binding to your Wrangler configuration: - + -### AI binding with third-party models +```jsonc +{ + "ai": { + "binding": "AI", + }, +} +``` -If you are already using the [`workers-ai-provider`](https://www.npmjs.com/package/workers-ai-provider) package, you can route requests through AI Gateway to call third-party models without needing separate provider SDKs. Pass a `gateway` option with your gateway ID to `createWorkersAI`: + + +## Call a catalog model + +Pass an `/` id from the [model catalog](/ai/models/). You do not need a vendor package or a vendor key. AI Gateway bills the request through [Unified Billing](/ai-gateway/features/unified-billing/), or uses a [key stored on the gateway](/ai-gateway/configuration/bring-your-own-keys/): ```ts -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; import { streamText } from "ai"; export default { - async fetch(request, env) { - const workersai = createWorkersAI({ - binding: env.AI, - gateway: { id: "my-gateway" }, - }); + async fetch(request: Request, env: Env) { + const ai = createAI({ binding: env.AI, id: "my-gateway" }); const result = streamText({ - model: workersai("openai/gpt-4o"), + model: ai("anthropic/claude-opus-5.5"), messages: [{ role: "user", content: "Write a short story" }], }); return result.toTextStreamResponse(); }, -} satisfies ExportedHandler; +}; ``` -This works with any [supported provider and model](/ai/models/) available through AI Gateway. +Use the catalog's spelling of the id, such as `anthropic/claude-opus-5.5` or `openai/gpt-5.5`. `id` sets the gateway and defaults to `default`. A [dynamic route](/ai-gateway/features/dynamic-routing/) on that gateway is `dynamic/`, for example `ai("dynamic/support")`. + +## Call a vendor's model object + +Pass a model from the vendor's own AI SDK package. The request goes unchanged to the vendor's [provider-native endpoint](/ai-gateway/usage/providers/) on your gateway. AI Gateway holds the credential, so the vendor's `apiKey` is a placeholder: + +```ts +import { createAnthropic } from "@ai-sdk/anthropic"; +import { createAI } from "agents/models/ai-sdk"; + +const ai = createAI({ binding: env.AI, id: "my-gateway" }); +const anthropic = createAnthropic({ apiKey: "cloudflare" }); + +const model = ai(anthropic("claude-opus-5-5")); +``` + +Use the vendor's own model id here, such as `claude-opus-5-5`. To send a key you hold instead, refer to [Unified billing and BYOK](/agents/models/ai-sdk/#unified-billing-and-byok). + +## Fall back to another model + +`fallback` lists models to try in order if the primary model fails before it produces any output. Mix catalog ids, dynamic routes, Workers AI ids, and model objects: -### Fallback Providers +```ts +const model = ai(anthropic("claude-opus-5-5"), { + fallback: ["openai/gpt-5.5", "@cf/zai-org/glm-4.7-flash"], +}); +``` + +## Set gateway options + +Set [caching](/ai-gateway/features/caching/), logging, metadata, timeouts, and retries on the provider, on a model, or per call under `providerOptions.cloudflare`: + +```ts +const ai = createAI({ + binding: env.AI, + id: "my-gateway", + cacheTtl: 60, + metadata: { app: "support-bot" }, +}); + +await generateText({ + model: ai("openai/gpt-5.5"), + prompt: "Summarize this ticket", + providerOptions: { + cloudflare: { skipCache: true, metadata: { userId: "u_123" } }, + }, +}); +``` + +For every option, refer to [Set options](/agents/models/ai-sdk/#set-options). + +## Use an account id and API token -To specify model or provider fallbacks to handle request failures and ensure reliability, you can pass an array of models to the `model` option. +To use a gateway in another account, or to call from outside a Worker, pass `accountId` and `apiToken` instead of `binding`: -```js title="" -const { text } = await generateText({ - model: aigateway([openai.chat("gpt-5.1"), anthropic("claude-sonnet-4-5")]), - prompt: "Write a vegetarian lasagna recipe for 4 people.", +```ts +const ai = createAI({ + accountId: "", + apiToken: env.CLOUDFLARE_API_TOKEN, + gateway: "my-gateway", }); ``` + +The call forms and options are the same. [Create an API token](/fundamentals/api/get-started/create-token/) with the **Workers AI Read** permission for model ids and **AI Gateway Run** for model objects. + +## Related resources + +- [AI SDK provider reference](/agents/models/ai-sdk/) +- [Model catalog](/ai/models/) +- [Dynamic routing](/ai-gateway/features/dynamic-routing/) +- [Unified Billing](/ai-gateway/features/unified-billing/) diff --git a/src/content/docs/ai-search/agent-sdks/agents-sdk.mdx b/src/content/docs/ai-search/agent-sdks/agents-sdk.mdx index 4aa95cb2528..1a4c84fd5df 100644 --- a/src/content/docs/ai-search/agent-sdks/agents-sdk.mdx +++ b/src/content/docs/ai-search/agent-sdks/agents-sdk.mdx @@ -53,9 +53,9 @@ cd ai-search-agent ## 2. Install the Agents SDK packages -Install the Agents SDK, the AI SDK, and the Workers AI provider: +Install the Agents SDK and the AI SDK. The example calls Workers AI with [`createAI`](/agents/models/ai-sdk/) from `agents/models/ai-sdk`: - + ## 3. Bind your Worker to AI Search @@ -100,7 +100,7 @@ Create `src/server.ts`. New AI Search instances use [hybrid search](/ai-search/c ```ts import { AIChatAgent } from "@cloudflare/ai-chat"; import { routeAgentRequest } from "agents"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; import { streamText, convertToModelMessages, tool, stepCountIs } from "ai"; import { z } from "zod"; @@ -149,10 +149,10 @@ export class SearchAgent extends AIChatAgent { // The agent exposes AI Search's search() as a tool instead of using AI // Search's own chat model, so this model must support function calling to // decide when to search and drive the tool calls. - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = streamText({ - model: workersai("@cf/zai-org/glm-5.2"), + model: ai("@cf/zai-org/glm-5.2"), system: "You are a support assistant. Use search_knowledge_base to find " + "relevant content before answering, and cite what you use.", diff --git a/src/content/docs/ai-search/how-to/talk-to-your-knowledge-base.mdx b/src/content/docs/ai-search/how-to/talk-to-your-knowledge-base.mdx index 6500558616f..2059cb136fd 100644 --- a/src/content/docs/ai-search/how-to/talk-to-your-knowledge-base.mdx +++ b/src/content/docs/ai-search/how-to/talk-to-your-knowledge-base.mdx @@ -123,7 +123,7 @@ import { type VoiceTurnContext, } from "@cloudflare/voice"; import { generateText, tool, stepCountIs } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; import { z } from "zod"; const VoiceAgent = withVoice(Agent); @@ -137,11 +137,11 @@ export class TalkToDocs extends VoiceAgent { // the reply, calling AI Search as a retrieval tool when it needs facts from // your knowledge base. async onTurn(transcript: string, context: VoiceTurnContext) { - const workersai = createWorkersAI({ binding: this.env.AI }); + const ai = createAI({ binding: this.env.AI }); const result = await generateText({ // Use a Workers AI model that supports function calling. - model: workersai("@cf/zai-org/glm-5.2"), + model: ai("@cf/zai-org/glm-5.2"), system: "You are a helpful voice assistant that answers from a Cloudflare AI Search knowledge base. " + "For questions about the product, call the searchKnowledgeBase tool first and answer using the results. " + diff --git a/src/content/docs/sandbox/get-started/build-an-ai-code-interpreter.mdx b/src/content/docs/sandbox/get-started/build-an-ai-code-interpreter.mdx index e62d604eb3a..2688cc57b1d 100644 --- a/src/content/docs/sandbox/get-started/build-an-ai-code-interpreter.mdx +++ b/src/content/docs/sandbox/get-started/build-an-ai-code-interpreter.mdx @@ -65,9 +65,9 @@ You will learn how to: cd sandbox-code-interpreter ``` -3. Install the [AI SDK](https://ai-sdk.dev/), the [Workers AI provider](/workers-ai/configuration/ai-sdk/), and [Zod](https://zod.dev/): +3. Install the [Agents SDK](/agents/), the [AI SDK](https://ai-sdk.dev/), and [Zod](https://zod.dev/). The Worker calls Workers AI with [`createAI`](/agents/models/ai-sdk/) from `agents/models/ai-sdk`: - + 4. Replace `wrangler.jsonc` to add a Workers AI binding and a Worker Loader binding: @@ -192,7 +192,7 @@ Replace `src/index.ts`. The Worker gives the model a `runJavaScript` tool and re ```ts import { generateText, isStepCount, tool } from "ai"; -import { createWorkersAI } from "workers-ai-provider"; +import { createAI } from "agents/models/ai-sdk"; import { z } from "zod"; import { runJavaScript, type Output } from "./sandbox"; @@ -223,12 +223,12 @@ export default { ); } - const workersai = createWorkersAI({ binding: env.AI }); + const ai = createAI({ binding: env.AI }); const runs: Run[] = []; try { const result = await generateText({ - model: workersai(model), + model: ai(model), instructions, prompt: body.data.question, tools: { diff --git a/src/content/docs/sandbox/sdk/tutorials/ai-code-executor.mdx b/src/content/docs/sandbox/sdk/tutorials/ai-code-executor.mdx index c37b20bc743..21edb1077b0 100644 --- a/src/content/docs/sandbox/sdk/tutorials/ai-code-executor.mdx +++ b/src/content/docs/sandbox/sdk/tutorials/ai-code-executor.mdx @@ -250,4 +250,4 @@ You created an AI code execution system that: - [Anthropic Claude documentation](https://docs.anthropic.com/) - [Workers AI](/workers-ai/) - Use Cloudflare's built-in models -- [workers-ai-provider package](https://github.com/cloudflare/ai/tree/main/packages/workers-ai-provider) - Official Workers AI integration +- [AI SDK provider](/agents/models/ai-sdk/) - Call Workers AI and AI Gateway models from the AI SDK diff --git a/src/content/docs/workers-ai/configuration/ai-sdk.mdx b/src/content/docs/workers-ai/configuration/ai-sdk.mdx index b801f722eff..9460c961e5c 100644 --- a/src/content/docs/workers-ai/configuration/ai-sdk.mdx +++ b/src/content/docs/workers-ai/configuration/ai-sdk.mdx @@ -1,129 +1,194 @@ --- pcx_content_type: configuration title: Vercel AI SDK -description: Use Workers AI with the Vercel AI SDK for streaming text generation, tool calls, and structured output. +description: Use Workers AI models with the AI SDK through createAI from agents/models/ai-sdk. sidebar: order: 3 products: - workers-ai --- -import { PackageManagers } from "~/components"; +import { + PackageManagers, + TypeScriptExample, + WranglerConfig, +} from "~/components"; -Workers AI can be used with the [Vercel AI SDK](https://sdk.vercel.ai/) for JavaScript and TypeScript codebases. +To use Workers AI with the [AI SDK](https://ai-sdk.dev/), use `createAI` from `agents/models/ai-sdk`. This page covers Workers AI models. For AI Gateway catalog models, fallback, gateway options, and the full option reference, refer to [AI SDK](/agents/models/ai-sdk/). + +The `workers-ai-provider` package is deprecated. Use `createAI` instead. ## Setup -Install the [`workers-ai-provider` provider](https://sdk.vercel.ai/providers/community-providers/cloudflare-workers-ai): +Install the Agents SDK and the AI SDK. `createAI` needs `ai@^7` and `@ai-sdk/provider@^4`: + + - +Add the `AI` binding to your Wrangler configuration: -Then, add an AI binding in your Workers project Wrangler file: + -```toml -[ai] -binding = "AI" +```jsonc +{ + "ai": { + "binding": "AI", + }, +} ``` -## Models + -The AI SDK can be configured to work with [any AI model](/workers-ai/models/). +## Choose a model -```js -import { createWorkersAI } from "workers-ai-provider"; +Pass the id of any [Workers AI model](/workers-ai/models/). Model ids start with `@cf/` and autocomplete from `@cloudflare/workers-types`: -const workersai = createWorkersAI({ binding: env.AI }); +```ts +import { createAI } from "agents/models/ai-sdk"; -// Choose any model: https://developers.cloudflare.com/workers-ai/models/ -const model = workersai("@cf/meta/llama-3.1-8b-instruct", {}); -``` +const ai = createAI({ binding: env.AI }); -## Generate Text +const model = ai("@cf/zai-org/glm-4.7-flash"); +``` -Once you have selected your model, you can generate text from a given prompt. +## Generate text -```js -import { createWorkersAI } from 'workers-ai-provider'; -import { generateText } from 'ai'; + -type Env = { - AI: Ai; -}; +```ts +import { createAI } from "agents/models/ai-sdk"; +import { generateText } from "ai"; export default { - async fetch(_: Request, env: Env) { - const workersai = createWorkersAI({ binding: env.AI }); - const result = await generateText({ - model: workersai('@cf/meta/llama-2-7b-chat-int8'), - prompt: 'Write a 50-word essay about hello world.', - }); - - return new Response(result.text); - }, + async fetch(request: Request, env: Env) { + const ai = createAI({ binding: env.AI }); + + const { text } = await generateText({ + model: ai("@cf/zai-org/glm-4.7-flash"), + prompt: "Write a 50-word essay about hello world.", + }); + + return new Response(text); + }, }; ``` -## Stream Text + -For longer responses, consider streaming responses to provide as the generation completes. +## Stream text -```js -import { createWorkersAI } from 'workers-ai-provider'; -import { streamText } from 'ai'; +For longer responses, stream the output as the model generates it: -type Env = { - AI: Ai; -}; + + +```ts +import { createAI } from "agents/models/ai-sdk"; +import { streamText } from "ai"; export default { - async fetch(_: Request, env: Env) { - const workersai = createWorkersAI({ binding: env.AI }); - const result = streamText({ - model: workersai('@cf/meta/llama-2-7b-chat-int8'), - prompt: 'Write a 50-word essay about hello world.', - }); - - return result.toTextStreamResponse({ - headers: { - // add these headers to ensure that the - // response is chunked and streamed - 'Content-Type': 'text/x-unknown', - 'content-encoding': 'identity', - 'transfer-encoding': 'chunked', - }, - }); - }, + async fetch(request: Request, env: Env) { + const ai = createAI({ binding: env.AI }); + + const result = streamText({ + model: ai("@cf/zai-org/glm-4.7-flash"), + prompt: "Write a 50-word essay about hello world.", + }); + + return result.toTextStreamResponse(); + }, }; ``` -## Generate Structured Objects + -You can provide a Zod schema to generate a structured JSON response. +## Generate structured output -```js -import { createWorkersAI } from 'workers-ai-provider'; -import { generateObject } from 'ai'; -import { z } from 'zod'; +Pass a Zod schema to get a typed JSON response: -type Env = { - AI: Ai; -}; + + +```ts +import { createAI } from "agents/models/ai-sdk"; +import { generateText, Output } from "ai"; +import { z } from "zod"; export default { - async fetch(_: Request, env: Env) { - const workersai = createWorkersAI({ binding: env.AI }); - const result = await generateObject({ - model: workersai('@cf/meta/llama-3.1-8b-instruct'), - prompt: 'Generate a Lasagna recipe', - schema: z.object({ - recipe: z.object({ - ingredients: z.array(z.string()), - description: z.string(), - }), - }), - }); - - return Response.json(result.object); - }, + async fetch(request: Request, env: Env) { + const ai = createAI({ binding: env.AI }); + + const { output } = await generateText({ + model: ai("@cf/zai-org/glm-4.7-flash"), + prompt: "Generate a lasagna recipe.", + output: Output.object({ + schema: z.object({ + recipe: z.object({ + ingredients: z.array(z.string()), + description: z.string(), + }), + }), + }), + }); + + return Response.json(output); + }, }; ``` + + + +## Use other model types + +Embeddings, images, speech, transcription, and reranking come from the same provider: + +```ts +import { + embedMany, + generateImage, + generateSpeech, + rerank, + transcribe, +} from "ai"; + +const { embeddings } = await embedMany({ + model: ai.embedding("@cf/baai/bge-base-en-v1.5"), + values: ["hello", "world"], +}); + +const { image } = await generateImage({ + model: ai.image("@cf/black-forest-labs/flux-1-schnell"), + prompt: "A cyberpunk lizard", +}); + +const { audio } = await generateSpeech({ + model: ai.speech("@cf/deepgram/aura-1"), + text: "Hello from Cloudflare.", +}); + +const { text } = await transcribe({ + model: ai.transcription("@cf/openai/whisper-large-v3-turbo"), + audio: audio.uint8Array, +}); + +const { rerankedDocuments } = await rerank({ + model: ai.reranking("@cf/baai/bge-reranker-base"), + documents: ["a cyberpunk lizard", "a rainy Tuesday"], + query: "Which one is cooler?", +}); +``` + +For model-specific settings, refer to [Use other modalities](/agents/models/ai-sdk/#use-other-modalities). + +## Use AI Gateway + +Requests go through [AI Gateway](/ai-gateway/). The gateway defaults to `default`. To use another gateway, set its `id`: + +```ts +const ai = createAI({ binding: env.AI, id: "my-gateway" }); +``` + +The same provider also calls models from the [AI Gateway catalog](/ai/models/), such as `anthropic/claude-opus-5.5`. Refer to [AI SDK](/agents/models/ai-sdk/) for catalog models, caching, fallback, and the other gateway options. + +## Related resources + +- [AI SDK provider reference](/agents/models/ai-sdk/) +- [Workers AI models](/workers-ai/models/) +- [AI SDK documentation](https://ai-sdk.dev/docs/introduction) From 8495c88e847135fbe6c29cecf1fe64acf48802e1 Mon Sep 17 00:00:00 2001 From: Matt Carey Date: Tue, 20 Oct 2026 21:55:21 +0100 Subject: [PATCH 2/4] [AI Gateway] createAI in the chat completion AI SDK samples; current model ids --- .../ai-gateway/code-example-selector.tsx | 63 ++++----- src/components/ai-gateway/code-examples.astro | 133 +++++++++--------- 2 files changed, 91 insertions(+), 105 deletions(-) diff --git a/src/components/ai-gateway/code-example-selector.tsx b/src/components/ai-gateway/code-example-selector.tsx index 9ab58fd68f7..c46dc8b31f8 100644 --- a/src/components/ai-gateway/code-example-selector.tsx +++ b/src/components/ai-gateway/code-example-selector.tsx @@ -382,58 +382,54 @@ export function CodeExample({ export const modelOptions = [ { - model: "gpt-5.2", + model: "gpt-6-luna", provider: "openai", aiSDK: { + id: "openai/gpt-6-luna", + pkg: "@ai-sdk/openai", providerFactory: "createOpenAI", - providerUsage: "openai.chat", provider: "openai", }, }, { - model: "claude-4-5-sonnet", + model: "claude-opus-5-5", provider: "anthropic", aiSDK: { + id: "anthropic/claude-opus-5.5", + pkg: "@ai-sdk/anthropic", providerFactory: "createAnthropic", - providerUsage: "anthropic", provider: "anthropic", }, }, { - model: "gemini-2.5-pro", + model: "gemini-4-argon", provider: "google", aiSDK: { - providerFactory: "createGoogle", - providerUsage: "google", + id: "google/gemini-4-argon", + pkg: "@ai-sdk/google", + providerFactory: "createGoogleGenerativeAI", provider: "google", }, }, { - model: "grok-4", + model: "grok-4.7", provider: "grok", aiSDK: { + id: "xai/grok-4.7", + pkg: "@ai-sdk/xai", providerFactory: "createXai", - providerUsage: "xai", provider: "xai", }, }, { model: "customer-support", provider: "dynamic", - aiSDK: { - providerFactory: "createUnified", - providerUsage: "unified", - provider: "unified", - }, + aiSDK: { id: "dynamic/customer-support" }, }, { model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast", provider: "workers-ai", - aiSDK: { - providerFactory: "createUnified", - providerUsage: "unified", - provider: "unified", - }, + aiSDK: { id: "@cf/meta/llama-3.3-70b-instruct-fp8-fast" }, }, ]; export const code = `import OpenAI from "openai"; @@ -450,38 +446,35 @@ const response = await client.chat.completions.create({ messages: [{ role: "user", content: "Hello, world!" }], });`; -export const aiSDKUnifiedCode = `import { createAiGateway } from 'ai-gateway-provider'; -import { createUnified } from 'ai-gateway-provider/providers/unified'; +export const aiSDKUnifiedCode = `import { createAI } from "agents/models/ai-sdk"; import { generateText } from "ai"; -const aigateway = createAiGateway({ +const ai = createAI({ accountId: "{CLOUDFLARE_ACCOUNT_ID}", - gateway: '{GATEWAY_NAME}', - apiKey: '{CF_AIG_TOKEN}', + apiToken: "{CF_API_TOKEN}", + gateway: "{GATEWAY_NAME}", }); -const unified = createUnified({apikey}); - const { text } = await generateText({ - model: aigateway(unified('{provider}/{model}')), - prompt: 'What is Cloudflare?', + model: ai("{id}"), + prompt: "What is Cloudflare?", });`; -export const aiSDKNativeCode = `import { createAiGateway } from 'ai-gateway-provider'; -import { {providerFactory} } from 'ai-gateway-provider/providers/{provider}'; +export const aiSDKNativeCode = `import { createAI } from "agents/models/ai-sdk"; +import { {providerFactory} } from "{pkg}"; import { generateText } from "ai"; -const aigateway = createAiGateway({ +const ai = createAI({ accountId: "{CLOUDFLARE_ACCOUNT_ID}", - gateway: '{GATEWAY_NAME}', - apiKey: '{CF_AIG_TOKEN}', + apiToken: "{CF_API_TOKEN}", + gateway: "{GATEWAY_NAME}", }); const {provider} = {providerFactory}({apikey}); const { text } = await generateText({ - model: aigateway({providerUsage}('{model}')), - prompt: 'What is Cloudflare?', + model: ai({provider}("{model}"){vendorKey}), + prompt: "What is Cloudflare?", });`; export const curlCode = `curl -X POST https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions \\ diff --git a/src/components/ai-gateway/code-examples.astro b/src/components/ai-gateway/code-examples.astro index a67d754d6eb..52f366fe8b6 100644 --- a/src/components/ai-gateway/code-examples.astro +++ b/src/components/ai-gateway/code-examples.astro @@ -103,81 +103,74 @@ const { forceClient, forceAPI } = props.parse(Astro.props); ))} {(!forceClient || forceClient === "aisdk") && - modelOptions.map((option) => ( - - - - ))} - - {(!forceClient || forceClient === "aisdk") && - modelOptions.map((option) => ( - - - - ))} + modelOptions + .filter((option) => option.aiSDK.pkg !== undefined) + .flatMap((option) => + (["unified", "native"] as const).map((apiType) => ({ + option, + apiType, + })), + ) + .map(({ option, apiType }) => ( + + + + ))} {(!forceClient || forceClient === "aisdk") && - modelOptions.map((option) => ( - - - - ))} + modelOptions + .filter((option) => option.aiSDK.pkg !== undefined) + .map((option) => ( + + + + ))} {(!forceClient || forceClient === "curl") && modelOptions.map((option) => ( From f43fa9f52f1dee2aa1391e9f90d65b73eb2c440f Mon Sep 17 00:00:00 2001 From: Matt Carey Date: Tue, 20 Oct 2026 22:12:51 +0100 Subject: [PATCH 3/4] [Workers AI, AI Gateway] Changelog leads with createAI --- ...rovider-ai-gateway-provider-deprecated.mdx | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/src/content/changelog/workers-ai/2026-10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx b/src/content/changelog/workers-ai/2026-10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx index 30bc959491c..c1ef8ff5011 100644 --- a/src/content/changelog/workers-ai/2026-10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx +++ b/src/content/changelog/workers-ai/2026-10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx @@ -1,18 +1,19 @@ --- -title: workers-ai-provider and ai-gateway-provider are deprecated -description: The workers-ai-provider and ai-gateway-provider npm packages are deprecated. Use createAI from agents/models/ai-sdk, and ai-search-provider for AI Search. +title: createAI replaces workers-ai-provider and ai-gateway-provider +description: The Agents SDK has a new createAI function for the AI SDK and Pi AI that unifies workers-ai-provider and ai-gateway-provider. Both packages are now feature frozen and deprecated. products: - workers-ai - ai-gateway + - agents date: 2026-10-21 --- -The `workers-ai-provider` and `ai-gateway-provider` npm packages are deprecated. To call Workers AI and AI Gateway from the [AI SDK](https://ai-sdk.dev/), use [`createAI`](/agents/models/ai-sdk/) from `agents/models/ai-sdk`. For AI Search, use [`ai-search-provider`](/ai-search/agent-sdks/ai-sdk/). +The Agents SDK has a new `createAI` function for the [AI SDK](/agents/models/ai-sdk/) and [Pi AI](/agents/models/pi-ai/). It unifies what `workers-ai-provider` and `ai-gateway-provider` did: Workers AI models, AI Gateway catalog models, dynamic routes, and vendor models, through the `AI` binding or an account id and API token. -Existing code keeps working. Nothing changes at runtime. +`workers-ai-provider` and `ai-gateway-provider` are now feature frozen and marked as deprecated. Existing code keeps working. Migrate at your convenience. ```sh -npm install agents ai @ai-sdk/provider +npm i agents ``` ```ts @@ -23,11 +24,11 @@ const ai = createAI({ binding: env.AI }); const model = ai("@cf/zai-org/glm-4.7-flash"); ``` -| Before | After | -| ------------------------------------------------------- | -------------------------------------------------------- | -| `createWorkersAI({ binding })` | `createAI({ binding })` | -| `createWorkersAI({ accountId, apiKey })` | `createAI({ accountId, apiToken })` | -| `createAiGateway(...)` | `createAI(...)`, with `fallback` for a list of models | -| `createAISearch` from `workers-ai-provider` | `createAISearchNamespace` from `ai-search-provider` | +| Before | After | +| ------------------------------------------- | ----------------------------------------------------- | +| `createWorkersAI({ binding })` | `createAI({ binding })` | +| `createWorkersAI({ accountId, apiKey })` | `createAI({ accountId, apiToken })` | +| `createAiGateway(...)` | `createAI(...)`, with `fallback` for a list of models | +| `createAISearch` from `workers-ai-provider` | `createAISearchNamespace` from `ai-search-provider` | -For more information, refer to [AI SDK](/agents/models/ai-sdk/). +For AI Search, use [`ai-search-provider`](/ai-search/agent-sdks/ai-sdk/). For more information, refer to [Models](/agents/models/). From e55e6f43b6ca0b3116f5faeea12491e588a43719 Mon Sep 17 00:00:00 2001 From: Matt Carey Date: Tue, 20 Oct 2026 22:13:44 +0100 Subject: [PATCH 4/4] [Workers AI, AI Gateway] Changelog wording --- ...10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/changelog/workers-ai/2026-10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx b/src/content/changelog/workers-ai/2026-10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx index c1ef8ff5011..cfa6dfb4216 100644 --- a/src/content/changelog/workers-ai/2026-10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx +++ b/src/content/changelog/workers-ai/2026-10-21-workers-ai-provider-ai-gateway-provider-deprecated.mdx @@ -10,7 +10,7 @@ date: 2026-10-21 The Agents SDK has a new `createAI` function for the [AI SDK](/agents/models/ai-sdk/) and [Pi AI](/agents/models/pi-ai/). It unifies what `workers-ai-provider` and `ai-gateway-provider` did: Workers AI models, AI Gateway catalog models, dynamic routes, and vendor models, through the `AI` binding or an account id and API token. -`workers-ai-provider` and `ai-gateway-provider` are now feature frozen and marked as deprecated. Existing code keeps working. Migrate at your convenience. +`workers-ai-provider` and `ai-gateway-provider` are now feature frozen and marked as deprecated. Please migrate at your convenience. ```sh npm i agents