模型 · Cloudflare Agents 文档

Agents SDK 包含适用于 Workers AI 和 AI Gateway 的模型提供程序。每个提供程序都是一个 createAI 工厂，可通过 Worker 的 AI 绑定，或通过账户 ID 和 API 令牌使用。每种框架各有一个提供程序：

导入路径	框架	配合使用
`agents/models/ai-sdk`	AI SDK ↗ v7	`generateText`、`streamText`、Think 和任何 AI SDK 使用方
`agents/models/pi-ai`	Pi AI ↗	Pi 执行框架和 Pi AI 的 `stream`

两者采用相同的选项、通过相同的网关路由，并以相同方式处理 Workers AI。OpenCode harness 还有第三种提供程序 agents/models/opencode，它基于 AI SDK 提供程序构建。

如何选择模型

使用字符串指定模型，或传入由供应商自有软件包构建的模型对象：

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

Workers AI 模型是一个 @cf/ ID。它通过 env.AI.run() 运行。兼容层会将每种模型的响应转换为标准的 OpenAI chat completions 格式。
AI Gateway 目录模型是来自模型目录的 <author>/<model> ID，例如 anthropic/claude-opus-5.5 或 openai/gpt-5.5。它也通过 env.AI.run() 运行，后者会将其发送到 AI Gateway。网关会选择提供程序并对此调用计费。请使用目录中的拼写，而非供应商的拼写：anthropic/claude-opus-5.5，而不是 claude-opus-5-5。
动态路由 的格式为 dynamic/<route>。你在网关上配置的路由会选择模型。
模型对象来自供应商的提供程序软件包，例如 anthropic("claude-opus-5-5")。供应商的代码负责构建请求并解析响应。提供程序会通过绑定将请求原样发送到该供应商在 AI Gateway 上的原生端点。

这些提供程序不使用已弃用的 Universal Endpoint。

每个模型获得的功能

无需供应商密钥。 AI Gateway 会通过统一计费或你存储在网关上的密钥保管第三方凭据。统一计费要求在网关上进行身份验证。
网关选项。 缓存、日志记录、元数据、超时、重试和 BYOK 密钥别名都是提供程序、模型或调用的选项。首次使用时会创建 default 网关。
回退。 按尝试顺序列出模型；如果第一个模型在生成输出前失败，就会尝试后续模型。可以混用 Workers AI ID、目录 ID、动态路由和模型对象。
流恢复。 通过绑定发送的目录模型或动态路由流在连接断开后会恢复。无需进行任何配置。
每个结果都包含网关元数据。 每个响应都携带网关日志 ID、缓存状态、运行 ID 以及实际作答的模型。

agents/models/ai-sdk 中的 createAI 取代了 workers-ai-provider 和 ai-gateway-provider。对于 AI Search，请使用 ai-search-provider。

连接到 Cloudflare

在 Worker 中，传入 AI 绑定，使用 createAI({ binding: env.AI })，并将其添加到 Wrangler 配置：

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

[ai]
binding = "AI"

若要在另一个账户中使用网关，或从 Worker 外部调用，请改为传入账户 ID 和 API 令牌。使用 Workers AI Read 和 AI Gateway Run 权限创建令牌：

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

从 Durable Object 调用模型

Agent 是安装了 Agents SDK Lifecycle ↗ 的 Durable Object。Lifecycle.install(this) 会安装平台的 fetch、alarm 和 WebSocket 处理程序，并改为调用你的 onStart()、onRequest() 和 onAlarm() 回调。你可以从这些回调、WebSocket 处理程序或自己的 RPC 方法调用模型。

Durable Object 可以自行调用模型，无需等待客户端，并且能够处理需要数分钟（甚至更久）才能完成的响应。

要从 Worker 访问 Durable Object，请使用 routeAgentRequest() 路由请求。默认 URL 格式为 /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>;

本页示例仅展示 Durable Object 类。要将 Durable Object 绑定添加到 Wrangler 配置，请参阅开始使用 Durable Objects。

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

要使用其他模型，请更改字符串，例如 ai("openai/gpt-5.5") 或 ai("@cf/zai-org/glm-5.3-flash")；也可以传入供应商自己的模型对象，例如 ai(openai("gpt-5.5"))。这些调用都会通过 AI Gateway 路由，因此 Worker 中无需供应商 API 密钥。

你也可以直接使用任何其他 AI SDK 提供程序，而不使用 createAI。此时调用会携带你自己的 API 密钥直接发送给供应商，并绕过 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 });
    }
}

通过 WebSocket 流式传输

推理模型生成响应并将其流式传输给客户端都可能需要一些时间。与其缓冲整个响应，不如通过 WebSocket 将其流式传回。安装 WebSockets 功能以接受升级请求并处理消息。若未安装，Lifecycle 会拒绝 WebSocket 升级：

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

要在连接断开后继续处理，请使用 this.ctx.storage 上的 SQLite 存储 API保存每个响应。客户端重新连接时，读取消息历史并重新发送。

直接调用 AI 绑定

调用模型不需要提供程序。你可以通过 env.AI.run() 调用任何 Workers AI 模型，且无需 API 密钥。完整绑定 API 请参阅 Workers AI 绑定。

设置 stream: true 可避免缓冲和延迟响应，尤其适用于较大的模型或推理模型：

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

要通过 AI Gateway 发送调用，请传入 gateway 选项。网关随后可以缓存响应，并根据可用性、速率限制或成本预算跨提供程序路由请求：

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

同一个 ai 绑定同时适用于 Workers AI 和 AI Gateway。请参阅 AI Gateway 文档以配置网关并查找其 ID。

OpenAI 兼容端点

你可以调用任何支持 OpenAI API 的服务上的模型。例如，使用 OpenAI SDK 调用 Google 的某个 Gemini 模型 ↗。这些调用会携带你自己的 API 密钥直接发送给供应商。

使用服务器发送事件 (SSE) 通过 fetch 经 HTTP 流式返回响应，或通过 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);
    }
}

选择提供程序

AI SDK

完整的 AI SDK ProviderV4，支持文本、工具、结构化输出、嵌入、图像、语音、转录和重排序。

Pi AI

用于 Pi 执行框架、Pi Durable 和任何基于 Pi AI 模型注册表构建的框架的 Pi AI 模型。