mattzcarey · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026 · Oct 16, 2026
@@ -0,0 +1,56 @@
+---
+title: createAI, one model provider for the AI SDK and Pi AI
+description: The Agents SDK's createAI calls Workers AI, the AI Gateway catalog, dynamic routes, and vendor models through the AI binding, from the AI SDK or Pi AI. It replaces the binding mode of workers-ai-provider and ai-gateway-provider.
+products:
+  - agents
+  - workers
+date: 2026-10-14
+---
+
+import { TypeScriptExample } from "~/components";
+
+The Agents SDK now ships [`createAI`](/agents/models/), one model provider for Workers AI and AI Gateway over the Worker's `AI` binding. There are two imports, with the same options:
+
+- `agents/models/ai-sdk` for the [AI SDK](/agents/models/ai-sdk/). It replaces the `AI` binding mode of `workers-ai-provider` and `ai-gateway-provider`.
+- `agents/models/pi-ai` for [Pi AI](/agents/models/pi-ai/) and the [Pi harness](/agents/harnesses/pi/). It gives Pi AI the same binding-based support.
+
+The [OpenCode harness](/agents/harnesses/opencode/) uses the AI SDK provider through `agents/models/opencode`.
+
+<TypeScriptExample>
+
+```ts
+import { createAI } from "agents/models/ai-sdk";
+import { streamText } from "ai";
+
+export default {
+	async fetch(request: Request, env: Env) {
+		const ai = createAI({ binding: env.AI, id: "my-gateway" });
+
+		const result = streamText({
+			model: ai("anthropic/claude-opus-5.5", {
+				fallback: ["@cf/zai-org/glm-4.7-flash"],
+			}),
+			prompt: "Write a haiku about Durable Objects",
+		});
+
+		return result.toTextStreamResponse();
+	},
+};
+```
+
+</TypeScriptExample>
+
+With `createAI` you get:
+
+- **Every model by id.** Workers AI `@cf/` ids, any model in the [AI Gateway catalog](/ai/models/) such as `anthropic/claude-opus-5.5`, and [dynamic routes](/ai-gateway/features/dynamic-routing/) as `dynamic/<route>`.
+- **Vendor model objects.** Pass a model from the vendor's own package, such as `ai(anthropic("claude-opus-5-5"))`. The request goes unchanged to AI Gateway's [provider-native endpoint](/ai-gateway/usage/providers/).
+- **No API tokens.** Every request goes through the `AI` binding. AI Gateway bills through [Unified Billing](/ai-gateway/features/unified-billing/) or a [stored key](/ai-gateway/configuration/bring-your-own-keys/). `byokAlias` picks a stored key, `zdr` sets Zero Data Retention, and `vendorKey: "request"` sends a key you hold.
+- **Gateway options.** Caching, logging, metadata, timeouts, and retries on the provider, the model, or the call.
+- **Fallback.** Try models in order if one fails before it answers. Mix ids and model objects.
+- **Stream resume.** A catalog or dynamic route stream that drops mid-answer resumes, with nothing lost or repeated.
+- **Gateway metadata and typed errors.** Each result carries the log id, cache status, run id, and the model that answered. Failures throw `CloudflareAIError`.
+- **Other model types.** Embeddings, images, speech, transcription, and reranking from Workers AI in the AI SDK provider, and images in Pi AI.
+
+`createAI` does not use AI Gateway's deprecated [Universal Endpoint](/ai-gateway/usage/universal/). Once `createAI` covers everything `workers-ai-provider` and `ai-gateway-provider` do, those packages will be deprecated.
+
+For more information, refer to [Models](/agents/models/).
@@ -1,6 +1,6 @@
 ---
 title: OpenCode
-description: Run OpenCode 2.0 in a plain Durable Object with the Agents SDK, Workers AI models, bundled plugins, and durable sessions.
+description: Run OpenCode 2.0 in a plain Durable Object with the Agents SDK, Workers AI and AI Gateway models, bundled plugins, and durable sessions.
 pcx_content_type: overview
 sidebar:
   order: 11
@@ -18,7 +18,7 @@ import {
 
 [OpenCode](https://opencode.ai/v2/docs/build/sdk/) is an extensible agent harness. The Agents SDK's `OpenCodeHarness` runs its Workerd SDK inside a plain Durable Object. Refer to [OpenCode's Cloudflare SDK documentation](https://opencode.ai/v2/docs/build/sdk/cloudflare/) for the embedded host API.
 
-OpenCode owns the agent loop, transcript, tools, and session recovery. `OpenCodeHarness` supplies SQLite storage and wakes the object after an interrupted run. The `agents/models/opencode` provider connects OpenCode to Workers AI through your `AI` binding.
+OpenCode owns the agent loop, transcript, tools, and session recovery. `OpenCodeHarness` supplies SQLite storage and wakes the object after an interrupted run. The `agents/models/opencode` provider connects OpenCode to Workers AI models, [AI Gateway](/ai-gateway/) catalog models, and dynamic routes through your `AI` binding.
 
 <CopyPromptButton
 	tooltip="Build and deploy an OpenCode agent"
@@ -40,7 +40,7 @@ flowchart LR
         host <--> sqlite[("SQLite: opencode_ tables")]
         host <--> plugins["Bundled plugins"]
     end
-    host --> ai["Workers AI binding"]
+    host --> ai["AI binding"]
     plugins --> mcp["Remote MCP server"]
     plugins --> workspace["External execution environment"]
 ```
@@ -52,7 +52,7 @@ flowchart LR
 | Capability                                     | Support                                                  |
 | ---------------------------------------------- | -------------------------------------------------------- |
 | Durable sessions and interrupted-turn recovery | OpenCode persists state; Lifecycle jobs wake the object. |
-| Workers AI models                              | Register the `agents/models/opencode` plugin.            |
+| Workers AI and AI Gateway models               | Register the `agents/models/opencode` plugin.            |
 | Custom tools, agents, and skills               | Bundle OpenCode plugins with your Worker.                |
 | Remote Model Context Protocol (MCP) servers    | Register remote servers through a plugin.                |
 | Live events and durable event replay           | Use `session.events()` and `session.log()`.              |
@@ -63,9 +63,9 @@ Install the Agents SDK and OpenCode packages:
 
 <PackageManagers pkg="agents@latest @opencode/sdk@2 @opencode/plugin@2" />
 
-Use `agents` version 0.28.1 or later. The OpenCode packages are optional peer dependencies, required by this integration, with a supported range of `^2.0.24`.
+Use the latest `agents` release. The OpenCode packages are optional peer dependencies, required by this integration, with a supported range of `^2.0.24`.
 
-Add the Workers AI binding, a SQLite-backed Durable Object, and `nodejs_compat` to your Wrangler configuration:
+Add the `AI` binding, a SQLite-backed Durable Object, and `nodejs_compat` to your Wrangler configuration:
 
 <WranglerConfig>
 
@@ -172,12 +172,26 @@ export default {
 
 </TypeScriptExample>
 
-Pass the factory's `storage` to `OpenCodeWorkerd.create()` so OpenCode uses the prefixed database. Register `this.ai.plugin` to make the Workers AI models available. `models: { fetch: false }` skips OpenCode's external model catalog refresh; the provider registers models you name with `this.ai()`.
+Pass the factory's `storage` to `OpenCodeWorkerd.create()` so OpenCode uses the prefixed database. Register `this.ai.plugin` to add a provider named "Cloudflare" (id `cloudflare`) to OpenCode. `models: { fetch: false }` skips OpenCode's external model catalog refresh. The provider registers the models you name with `this.ai()`.
 
 The Lifecycle manages host startup. The factory runs again when the harness reopens an idle host, so it must support repeated calls.
 
 The `"demo"` object name is for this example. In an application, choose an object name based on an authenticated user or conversation.
 
+## Choose a model
+
+`this.ai()` takes the same model ids as the [AI SDK provider](/agents/models/ai-sdk/), and accepts its model options:
+
+```ts
+this.ai("@cf/moonshotai/kimi-k2.7-code"); // Workers AI
+this.ai("anthropic/claude-opus-5.5"); // AI Gateway catalog
+this.ai("dynamic/support"); // AI Gateway dynamic route
+```
+
+A catalog id uses the [model catalog](/ai/models/)'s spelling, such as `anthropic/claude-opus-5.5`. A dynamic route belongs to one gateway, so pass that gateway's `id` to `createAI`. An id that is not one of these three forms throws a `TypeError` on the line that names it. Streams from catalog models and dynamic routes [resume after a dropped connection](/agents/models/ai-sdk/#resume-a-dropped-stream).
+
+Each call returns OpenCode's model reference, `{ providerID, id }`. Pass it to `defaults.model` or `session.setModel()`. To set how OpenCode budgets a model's context, pass `limit: { context, output }`. The default is 128,000 context tokens and 8,192 output tokens.
+
 ## Send prompts
 
 `harness.prompt()` submits to the root session and waits for completion. It returns `status`, optional `text` or `reason`, and the active transcript as `messages`. Check `status`: `"done"` means answered; `"unanswered"` means failed, interrupted, withdrawn, or not found.