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

Volání LLM

Agents mění způsob práce s LLM. V bezstavovém Workeru začíná každý požadavek od nuly: znovu sestavíte kontext, zavoláte model, vrátíte odpověď a na vše zapomenete. Agent si stav mezi jednotlivými voláními uchovává, zůstává připojený ke klientům přes WebSocket a může volat modely podle vlastního plánu i bez přítomnosti uživatele.

Tato stránka popisuje vzory, které se otevírají, když vaše volání LLM probíhají uvnitř stavového Agenta. Nastavení poskytovatele a příklady kódu najdete na Používání modelů AI.

Stav jako kontext

Každý Agent má vestavěný Databáze SQL a stav typu klíč-hodnota. Místo aby se s každým požadavkem z klienta posílala celá historie konverzace, Agent si ji ukládá sám a prompty sestavuje z vlastního úložiště.

import { Agent } from "agents";

export class ResearchAgent extends Agent {
	async buildPrompt(userMessage) {
		const history = this.sql`
			SELECT role, content FROM messages
			ORDER BY timestamp DESC LIMIT 50`;

		const preferences = this.sql`
			SELECT key, value FROM user_preferences`;

		return [
			{ role: "system", content: this.systemPrompt(preferences) },
			...history.reverse(),
			{ role: "user", content: userMessage },
		];
	}
}

import { Agent } from "agents";

export class ResearchAgent extends Agent<Env> {
	async buildPrompt(userMessage: string) {
		const history = this.sql<{ role: string; content: string }>`
			SELECT role, content FROM messages
			ORDER BY timestamp DESC LIMIT 50`;

		const preferences = this.sql<{ key: string; value: string }>`
			SELECT key, value FROM user_preferences`;

		return [
			{ role: "system", content: this.systemPrompt(preferences) },
			...history.reverse(),
			{ role: "user", content: userMessage },
		];
	}
}

To znamená, že klient nemusí s každou zprávou odesílat celou konverzaci. Agent vlastní historii, může ji prořezávat, obohacovat o vyhledané dokumenty nebo před odesláním modelu shrnovat starší kola.

Přežití odpojení

Modely pro uvažování, jako DeepSeek R1 nebo GLM-4, mohou na odpověď potřebovat 30 sekund až několik minut. V bezstavové architektuře request-response musí klient zůstat po celou dobu připojený. Při výpadku spojení se odpověď ztratí.

Agent běží dál i po odpojení klienta. Jakmile odpověď dorazí, Agent ji může uložit do stavu a doručit ji, jakmile se klient znovu připojí, třeba i po hodinách či dnech.

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

export class MyAgent extends Agent {
	async onMessage(connection, message) {
		const { prompt } = JSON.parse(message);
		const workersai = createWorkersAI({ binding: this.env.AI });

		const result = streamText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			prompt,
		});

		for await (const chunk of result.textStream) {
			connection.send(JSON.stringify({ type: "chunk", content: chunk }));
		}

		this.sql`INSERT INTO responses (prompt, response, timestamp)
			VALUES (${prompt}, ${await result.text}, ${Date.now()})`;
	}
}

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

export class MyAgent extends Agent<Env> {
	async onMessage(connection: Connection, message: WSMessage) {
		const { prompt } = JSON.parse(message as string);
		const workersai = createWorkersAI({ binding: this.env.AI });

		const result = streamText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			prompt,
		});

		for await (const chunk of result.textStream) {
			connection.send(JSON.stringify({ type: "chunk", content: chunk }));
		}

		this.sql`INSERT INTO responses (prompt, response, timestamp)
			VALUES (${prompt}, ${await result.text}, ${Date.now()})`;
	}
}

S AIChatAgent, to se řeší automaticky: zprávy se ukládají do SQLite a streamy se po opětovném připojení obnoví.

Autonomní volání modelu

Agents nepotřebují k volání modelu žádný požadavek uživatele. Volání modelu můžete naplánovat na pozadí, například pro noční sumarizaci, periodickou klasifikaci, monitorování nebo jakoukoli jinou úlohu, která se má odehrát bez lidské interakce.

import { Agent } from "agents";

export class DigestAgent extends Agent {
	async onStart() {
		this.schedule("0 8 * * *", "generateDailyDigest", {});
	}

	async generateDailyDigest() {
		const articles = this.sql`
			SELECT title, body FROM articles
			WHERE created_at > datetime('now', '-1 day')`;

		const workersai = createWorkersAI({ binding: this.env.AI });
		const { text } = await generateText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			prompt: `Summarize these articles:\n${articles.map((a) => a.title + ": " + a.body).join("\n\n")}`,
		});

		this.sql`INSERT INTO digests (summary, created_at)
			VALUES (${text}, ${Date.now()})`;

		this.broadcast(JSON.stringify({ type: "digest", summary: text }));
	}
}

import { Agent } from "agents";

export class DigestAgent extends Agent<Env> {
	async onStart() {
		this.schedule("0 8 * * *", "generateDailyDigest", {});
	}

	async generateDailyDigest() {
		const articles = this.sql<{ title: string; body: string }>`
			SELECT title, body FROM articles
			WHERE created_at > datetime('now', '-1 day')`;

		const workersai = createWorkersAI({ binding: this.env.AI });
		const { text } = await generateText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			prompt: `Summarize these articles:\n${articles.map((a) => a.title + ": " + a.body).join("\n\n")}`,
		});

		this.sql`INSERT INTO digests (summary, created_at)
			VALUES (${text}, ${Date.now()})`;

		this.broadcast(JSON.stringify({ type: "digest", summary: text }));
	}
}

Pipeline s více modely

Protože Agent udržuje stav napříč jednotlivými voláními, můžete v jedné metodě zřetězit více modelů, například rychlý model pro klasifikaci, model pro uvažování pro plánování a embedding model pro vyhledávání, aniž byste mezi jednotlivými kroky ztratili kontext.

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

export class TriageAgent extends Agent {
	async triage(ticket) {
		const workersai = createWorkersAI({ binding: this.env.AI });

		const { text: category } = await generateText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			prompt: `Classify this support ticket into one of: billing, technical, account. Ticket: ${ticket}`,
		});

		const { embedding } = await embed({
			model: workersai("@cf/baai/bge-base-en-v1.5"),
			value: ticket,
		});
		const similar = await this.env.VECTOR_DB.query(embedding, { topK: 5 });

		const { text: response } = await generateText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			prompt: `Draft a response for this ${category} ticket. Similar resolved tickets: ${JSON.stringify(similar)}. Ticket: ${ticket}`,
		});

		this.sql`INSERT INTO tickets (content, category, response, created_at)
			VALUES (${ticket}, ${category}, ${response}, ${Date.now()})`;

		return { category, response };
	}
}

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

export class TriageAgent extends Agent<Env> {
	async triage(ticket: string) {
		const workersai = createWorkersAI({ binding: this.env.AI });

		const { text: category } = await generateText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			prompt: `Classify this support ticket into one of: billing, technical, account. Ticket: ${ticket}`,
		});

		const { embedding } = await embed({
			model: workersai("@cf/baai/bge-base-en-v1.5"),
			value: ticket,
		});
		const similar = await this.env.VECTOR_DB.query(embedding, { topK: 5 });

		const { text: response } = await generateText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			prompt: `Draft a response for this ${category} ticket. Similar resolved tickets: ${JSON.stringify(similar)}. Ticket: ${ticket}`,
		});

		this.sql`INSERT INTO tickets (content, category, response, created_at)
			VALUES (${ticket}, ${category}, ${response}, ${Date.now()})`;

		return { category, response };
	}
}

Každý mezivýsledek zůstává v paměti Agenta po celou dobu trvání metody a konečný výsledek se pro budoucí použití ukládá do SQL.

Cachování a kontrola nákladů

Trvalé úložiště znamená, že můžete ukládat odpovědi modelu do mezipaměti a vyhnout se zbytečným voláním. To je užitečné zejména u nákladných operací, jako jsou embeddingy nebo dlouhé řetězce uvažování.

import { Agent } from "agents";

export class CachingAgent extends Agent {
	async cachedGenerate(prompt) {
		const cached = this.sql`
			SELECT response FROM llm_cache WHERE prompt = ${prompt}`;

		if (cached.length > 0) {
			return cached[0].response;
		}

		const workersai = createWorkersAI({ binding: this.env.AI });
		const { text } = await generateText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			prompt,
		});

		this.sql`INSERT INTO llm_cache (prompt, response, created_at)
			VALUES (${prompt}, ${text}, ${Date.now()})`;

		return text;
	}
}

import { Agent } from "agents";

export class CachingAgent extends Agent<Env> {
	async cachedGenerate(prompt: string) {
		const cached = this.sql<{ response: string }>`
			SELECT response FROM llm_cache WHERE prompt = ${prompt}`;

		if (cached.length > 0) {
			return cached[0].response;
		}

		const workersai = createWorkersAI({ binding: this.env.AI });
		const { text } = await generateText({
			model: workersai("@cf/zai-org/glm-4.7-flash"),
			prompt,
		});

		this.sql`INSERT INTO llm_cache (prompt, response, created_at)
			VALUES (${prompt}, ${text}, ${Date.now()})`;

		return text;
	}
}

Pro cachování na úrovni poskytovatele a správu omezení rychlosti napříč více agenty použijte AI Gateway.

Volání LLM

Stav jako kontext

Přežití odpojení

Autonomní volání modelu

Pipeline s více modely

Cachování a kontrola nákladů

Další kroky

Používání modelů AI

Chat agenti

Ukládání a synchronizace stavu

Plánování úloh