INTEGRITY Документация

← Создание агентов на Cloudflare / agents / runtime / operations

Использование ИИ-моделей

Agents могут вызывать ИИ-модели от любого провайдера. Workers AI встроен и не требует ключей API. Вы также можете использовать OpenAI ↗, Anthropic ↗, Google Gemini ↗, либо любой сервис, предоставляющий API, совместимый с OpenAI.

AI SDK ↗ предоставляет единый интерфейс для всех этих провайдеров, и именно AIChatAgent и стартовый шаблон используют «под капотом». Вы также можете использовать функции маршрутизации моделей в AI Gateway чтобы маршрутизировать запросы между провайдерами, оценивать ответы и управлять ограничениями скорости.

Вызов ИИ-моделей

Вы можете вызывать модели из любого метода внутри Agent, в том числе из HTTP-запросов, с помощью onRequest обработчик, когда запланированная задача выполняется при обработке сообщения WebSocket в onMessage обработчик, либо из любого из ваших собственных методов.

Agents могут вызывать ИИ-модели самостоятельно, автономно, и способны обрабатывать долгие ответы, полное получение которых занимает минуты (а иногда и дольше). Если клиент отключается посреди потока, Agent продолжает работу и может передать клиенту всё пропущенное после повторного подключения.

Потоковая передача через WebSockets

Современным моделям с продвинутым рассуждением может потребоваться время как на генерацию ответа, и передавать ответ клиенту потоково. Вместо буферизации всего ответа вы можете передавать его потоково через 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 }));
		}
	}
}

Вы также можете сохранять ответы модели AI обратно в Состояние Agent с помощью this.setState. Если пользователь отключается, считайте историю сообщений и отправьте её пользователю при повторном подключении.

Workers AI

Вы можете использовать любая из моделей, доступных в Workers AI внутри вашего Agent с помощью настройка привязки. Не требуются API-ключи.

Workers AI поддерживает потоковые ответы при установке stream: true. Используйте потоковую передачу, чтобы избежать буферизации и задержки ответов, особенно для больших моделей и моделей с рассуждением.

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

Вашей конфигурации Wrangler нужен ai в качестве привязки:

{
	"ai": {
		"binding": "AI",
	},
}
[ai]
binding = "AI"

Маршрутизация модели

Вы можете использовать AI Gateway напрямую из Agent, указав gateway конфигурация при вызове привязки AI. Маршрутизация моделей позволяет направлять запросы между провайдерами на основе доступности, ограничений скорости запросов или бюджетов затрат.

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 привязка в конфигурации Wrangler является общей для Workers AI и AI Gateway.

{
	"ai": {
		"binding": "AI",
	},
}
[ai]
binding = "AI"

Перейдите в Документация AI Gateway чтобы узнать, как настроить шлюз и получить его идентификатор.

AI SDK

AI SDK ↗ предоставляет единый API для генерации текста, вызова инструментов, структурированных ответов и многого другого. Он работает с любым провайдером, у которого есть адаптер AI SDK, включая Workers AI через 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 });
	}
}

Вы можете заменить провайдера, чтобы использовать OpenAI, Anthropic или любой другой адаптер, совместимый с 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 });
	}
}

Эндпойнты, совместимые с OpenAI

Agents могут вызывать модели через любой сервис, поддерживающий OpenAI API. Например, можно использовать OpenAI SDK для вызова одной из Модели Gemini от Google ↗ напрямую из вашего Agent.

Agents могут передавать ответы обратно по HTTP в виде потока с помощью Server-Sent Events (SSE) изнутри onRequest обработчик, либо с помощью нативного WebSocket API чтобы передавать ответы клиенту потоком.

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