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

Agents API

Tato stránka poskytuje přehled Agents SDK. Podrobnou dokumentaci ke každé funkci najdete na odkazovaných referenčních stránkách.

Agents SDK poskytuje dvě hlavní API:

Agent je třída, která rozšiřuje základní Agent třída:

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

Každý Agent může mít miliony instancí. Každá instance je samostatný mikroserver, který běží nezávisle, což umožňuje horizontální škálování. Instance se adresují pomocí jedinečného identifikátoru (ID uživatele, e-mail, číslo tiketu atd.).

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"]

Každá instance Agent má vestavěnou databázi SQLite, ke které se přistupuje přes 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}`;

Pro stav, který je třeba synchronizovat s klienty, použijte Stavové API místo toho.

Exporty pomocných funkcí na úrovni modulu zahrnují agentTool() z agents/agent-tools, který převádí Think nebo AIChatAgent podtřídu na definici nástroje 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 });
}

Pro aplikace AI chatu rozšiřte AIChatAgent místo Agent:

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

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

Mezi funkce patří:

• Vestavěná perzistence zpráv
• Automatické obnovitelné streamování (opětovné připojení uprostřed streamu)
• Funguje s useAgentChat React hook

Viz Sestavte chatovacího agenta s kompletním tutoriálem.

K Agents se přistupuje prostřednictvím vzorů URL:

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

Použijte routeAgentRequest() ve vašem Workeru pro směrování požadavků:

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

Viz Směrování pro vlastní cesty, CORS a vzory pojmenování instancí.