← Vytvářejte agenty na Cloudflare / agents / runtime / operations

Používání modelů AI

Agents mohou volat AI modely od libovolného poskytovatele. Workers AI je vestavěný a nevyžaduje žádné API klíče. Můžete také použít OpenAI ↗, Anthropic ↗, Google Gemini ↗, nebo jakoukoli službu, která zpřístupňuje API kompatibilní s OpenAI.

AI SDK ↗ poskytuje jednotné rozhraní napříč všemi těmito poskytovateli a je to právě to, co AIChatAgent a startovací šablona používají pod kapotou. Funkce směrování modelů můžete použít i v AI Gateway ke směrování napříč poskytovateli, vyhodnocování odpovědí a správě omezení rychlosti požadavků.

Volání modelů AI

Modely můžete volat z kterékoli metody uvnitř Agenta, včetně z HTTP požadavků pomocí onRequest handler, když naplánovaná úloha se spustí, když při zpracování zprávy WebSocket v onMessage handler, nebo z kterékoli vlastní metody.

Agents mohou volat AI modely samy, autonomně, a zvládnou i dlouho trvající odpovědi, jejichž úplné dokončení trvá minuty (nebo déle). Pokud se klient uprostřed streamu odpojí, Agent běží dál a po opětovném připojení může klienta doplnit o vše, co zmeškal.

Streamování přes WebSockets

Generování odpovědi u moderních modelů s uvažováním může nějakou dobu trvat a streamovat odpověď zpět klientovi. Místo bufferování celé odpovědi ji můžete streamovat zpět přes WebSockets.

src/index.js

import { Agent } from "agents";
import { streamText } from "ai";
import { createWorkersAI } from "workers-ai-provider";

export class MyAgent extends Agent {
	async onConnect(connection, ctx) {
		//
	}

	async onMessage(connection, message) {
		let msg = JSON.parse(message);
		await this.queryReasoningModel(connection, msg.prompt);
	}

	async queryReasoningModel(connection, userPrompt) {
		try {
			const workersai = createWorkersAI({ binding: this.env.AI });
			const result = streamText({
				model: workersai("@cf/zai-org/glm-4.7-flash"),
				prompt: userPrompt,
			});

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

src/index.ts

import { Agent } from "agents";
import { streamText } from "ai";
import { createWorkersAI } from "workers-ai-provider";

interface Env {
	AI: Ai;
}

export class MyAgent extends Agent<Env> {
	async onConnect(connection: Connection, ctx: ConnectionContext) {
		//
	}

	async onMessage(connection: Connection, message: WSMessage) {
		let msg = JSON.parse(message);
		await this.queryReasoningModel(connection, msg.prompt);
	}

	async queryReasoningModel(connection: Connection, userPrompt: string) {
		try {
			const workersai = createWorkersAI({ binding: this.env.AI });
			const result = streamText({
				model: workersai("@cf/zai-org/glm-4.7-flash"),
				prompt: userPrompt,
			});

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

Odpovědi AI modelu můžete také ukládat zpět do Stav agenta pomocí this.setState. Pokud se uživatel odpojí, načtěte historii zpráv a při opětovném připojení mu ji znovu odešlete.

Workers AI

Můžete použít kterýkoli z modelů dostupných ve Workers AI ve vašem Agentu pomocí konfigurace vazby. Nejsou vyžadovány žádné API klíče.

Workers AI podporuje streamování odpovědí nastavením stream: true. Použijte streamování, abyste se vyhnuli bufferování a zpožďování odpovědí, zejména u větších modelů nebo modelů typu reasoning.

src/index.js

import { Agent } from "agents";

export class MyAgent extends Agent {
	async onRequest(request) {
		const stream = await this.env.AI.run(
			"@cf/deepseek-ai/deepseek-r1-distill-qwen-32b",
			{
				prompt: "Build me a Cloudflare Worker that returns JSON.",
				stream: true,
			},
		);

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

src/index.ts

import { Agent } from "agents";

interface Env {
	AI: Ai;
}

export class MyAgent extends Agent<Env> {
	async onRequest(request: Request) {
		const stream = await this.env.AI.run(
			"@cf/deepseek-ai/deepseek-r1-distill-qwen-32b",
			{
				prompt: "Build me a Cloudflare Worker that returns JSON.",
				stream: true,
			},
		);

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

Vaše konfigurace Wrangler potřebuje ai binding:

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

[ai]
binding = "AI"

Směrování modelu

Můžete použít AI Gateway přímo z Agenta zadáním gateway konfigurace při volání vazby AI. Směrování modelů umožňuje směrovat požadavky mezi poskytovateli podle dostupnosti, limitů rychlosti nebo rozpočtu na náklady.

src/index.js

import { Agent } from "agents";

export class MyAgent extends Agent {
	async onRequest(request) {
		const response = await this.env.AI.run(
			"@cf/deepseek-ai/deepseek-r1-distill-qwen-32b",
			{
				prompt: "Build me a Cloudflare Worker that returns JSON.",
			},
			{
				gateway: {
					id: "{gateway_id}",
					skipCache: false,
					cacheTtl: 3360,
				},
			},
		);

		return Response.json(response);
	}
}

src/index.ts

import { Agent } from "agents";

interface Env {
	AI: Ai;
}

export class MyAgent extends Agent<Env> {
	async onRequest(request: Request) {
		const response = await this.env.AI.run(
			"@cf/deepseek-ai/deepseek-r1-distill-qwen-32b",
			{
				prompt: "Build me a Cloudflare Worker that returns JSON.",
			},
			{
				gateway: {
					id: "{gateway_id}",
					skipCache: false,
					cacheTtl: 3360,
				},
			},
		);

		return Response.json(response);
	}
}

ai vazba ve vaší konfiguraci Wrangler se sdílí mezi Workers AI a AI Gateway.

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

[ai]
binding = "AI"

Navštivte dokumentace AI Gateway a zjistěte, jak nakonfigurovat gateway a získat ID gateway.

AI SDK

AI SDK ↗ poskytuje jednotné API pro generování textu, volání nástrojů, strukturované odpovědi a další. Funguje s libovolným poskytovatelem, který má adaptér AI SDK, včetně Workers AI prostřednictvím workers-ai-provider ↗.

npm i ai workers-ai-provider

src/index.js

import { Agent } from "agents";
import { generateText } from "ai";
import { createWorkersAI } from "workers-ai-provider";

export class MyAgent extends Agent {
	async onRequest(request) {
		const workersai = createWorkersAI({ binding: this.env.AI });
		const { text } = await generateText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			prompt: "Build me an AI agent on Cloudflare Workers",
		});

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

src/index.ts

import { Agent } from "agents";
import { generateText } from "ai";
import { createWorkersAI } from "workers-ai-provider";

interface Env {
	AI: Ai;
}

export class MyAgent extends Agent<Env> {
	async onRequest(request: Request): Promise<Response> {
		const workersai = createWorkersAI({ binding: this.env.AI });
		const { text } = await generateText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			prompt: "Build me an AI agent on Cloudflare Workers",
		});

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

Poskytovatele můžete zaměnit tak, aby používal OpenAI, Anthropic nebo jiný adaptér kompatibilní s AI SDK:

npm i ai @ai-sdk/openai

src/index.js

import { Agent } from "agents";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

export class MyAgent extends Agent {
	async onRequest(request) {
		const { text } = await generateText({
			model: openai("gpt-4o"),
			prompt: "Build me an AI agent on Cloudflare Workers",
		});

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

src/index.ts

import { Agent } from "agents";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

export class MyAgent extends Agent {
	async onRequest(request: Request): Promise<Response> {
		const { text } = await generateText({
			model: openai("gpt-4o"),
			prompt: "Build me an AI agent on Cloudflare Workers",
		});

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

Endpointy kompatibilní s OpenAI

Agents mohou volat modely napříč libovolnou službou, která podporuje OpenAI API. Můžete například použít OpenAI SDK k volání jednoho z Modely Gemini od Google ↗ přímo z vašeho Agenta.

Agents mohou streamovat odpovědi zpět přes HTTP pomocí Server-Sent Events (SSE) uvnitř onRequest handler, nebo pomocí nativního WebSocket API ke streamování odpovědí zpět klientovi.

src/index.js

import { Agent } from "agents";
import { OpenAI } from "openai";

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

		let { readable, writable } = new TransformStream();
		let writer = writable.getWriter();
		const textEncoder = new TextEncoder();

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

				for await (const part of stream) {
					writer.write(
						textEncoder.encode(part.choices[0]?.delta?.content || ""),
					);
				}
				writer.close();
			})(),
		);

		return new Response(readable);
	}
}

src/index.ts

import { Agent } from "agents";
import { OpenAI } from "openai";

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

		let { readable, writable } = new TransformStream();
		let writer = writable.getWriter();
		const textEncoder = new TextEncoder();

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

				for await (const part of stream) {
					writer.write(
						textEncoder.encode(part.choices[0]?.delta?.content || ""),
					);
				}
				writer.close();
			})(),
		);

		return new Response(readable);
	}
}