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

Agents API

Эта страница даёт общий обзор Agents SDK. Подробную документацию по каждой функции см. на связанных справочных страницах.

Agents SDK предоставляет два основных API:

Agent представляет собой класс, расширяющий базовый Agent класс:

import { Agent, routeAgentRequest } from "agents";

export class MyAgent extends Agent<Env, State> {
	// Your agent logic
}

export default {
	async fetch(request: Request, env: Env) {
		return (
			(await routeAgentRequest(request, env)) ||
			new Response("Not found", { status: 404 })
		);
	},
} satisfies ExportedHandler<Env>;

У каждого Agent может быть миллионы экземпляров. Каждый экземпляр представляет собой отдельный микросервер, который выполняется независимо, что обеспечивает горизонтальное масштабирование. Экземпляры адресуются по уникальному идентификатору (ID пользователя, email, номер тикета и так далее).

flowchart TD
    A["onStart<br/>(instance wakes up)"] --> B["onRequest<br/>(HTTP)"]
    A --> C["onConnect<br/>(WebSocket)"]
    A --> D["onEmail"]
    C --> E["onMessage ↔ send()<br/>onError (on failure)"]
    E --> F["onClose"]

Каждый экземпляр Agent имеет встроенную базу данных SQLite, доступ к которой осуществляется через this.sql:

// Create tables
this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`;

// Insert data
this.sql`INSERT INTO users (id, name) VALUES (${id}, ${name})`;

// Query data
const users = this.sql<User>`SELECT * FROM users WHERE id = ${id}`;

Для состояния, которое нужно синхронизировать с клиентами, используйте API состояния взамен.

Экспортируемые вспомогательные функции на уровне модуля включают agentTool() от agents/agent-tools, который преобразует Think или AIChatAgent подкласс в определение инструмента AI SDK.

import { useAgent } from "agents/react";
import type { MyAgent } from "./server";

function App() {
	const agent = useAgent<MyAgent, State>({
		agent: "my-agent",
		name: "user-123",
	});

	// Call methods on the agent
	agent.stub.someMethod();

	// Update state (syncs to server and all clients)
	agent.setState({ count: 1 });
}

Для чат-приложений на базе ИИ расширьте AIChatAgent вместо Agent:

import { AIChatAgent } from "@cloudflare/ai-chat";

class ChatAgent extends AIChatAgent {
	async onChatMessage(onFinish) {
		// this.messages contains the conversation history
		// Return a streaming response
	}
}

Возможности включают:

• Встроенное сохранение сообщений
• Автоматическая возобновляемая потоковая передача (переподключение посреди потока)
• Работает с useAgentChat React-хук

См. Создайте чат-агента для полного руководства.

Agents доступны через URL-паттерны:

https://your-worker.workers.dev/agents/:agent-name/:instance-name

Используйте routeAgentRequest() в вашем Worker для маршрутизации запросов:

import { routeAgentRequest } from "agents";

export default {
	async fetch(request: Request, env: Env) {
		return (
			routeAgentRequest(request, env) ||
			new Response("Not found", { status: 404 })
		);
	},
} satisfies ExportedHandler<Env>;

См. Маршрутизация для пользовательских путей, CORS и шаблонов именования инстансов.