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

Chat SDK

Použijte agents/chat-sdk když spustíte Chat SDK ↗ uvnitř agenta. První integrační pomocná funkce je Chat SDK StateAdapter která ukládá stav v podřízených agentech Agents.

Adaptér ukládá odběry, zámky, fronty, klíče pro deduplikaci, stav vlákna, stav kanálu, metadata callbacků, seznamy přepisů a historii vláken Chat SDK do Durable Object SQLite. Každý shard stavu je ChatSdkStateAgent podřízeného agenta pod svým vstupním Agentem.

Nainstalujte oba balíčky do Workeru, který hostuje váš messenger ingress:

npm i agents chat

agents/chat-sdk poskytuje trvalý stav pro Chat SDK. Použijte ho s libovolným adaptérem Chat SDK, například Telegram, Slack, Discord, Teams nebo Google Chat.

Vytvořte nadřazeného Agenta, který vlastní váš runtime Chat SDK. Předejte createChatSdkState() jako Chat SDK state možnost.

import { Agent } from "agents";
import { createChatSdkState } from "agents/chat-sdk";
import { Chat } from "chat";
import { createTelegramAdapter } from "@chat-adapter/telegram";

export { ChatSdkStateAgent } from "agents/chat-sdk";

export class MessengerAgent extends Agent {
	chat;

	onStart() {
		const telegram = createTelegramAdapter({
			botToken: this.env.TELEGRAM_BOT_TOKEN,
			mode: "webhook",
			userName: "my_bot",
		});

		this.chat = new Chat({
			adapters: { telegram },
			userName: "my_bot",
			state: createChatSdkState(),
			concurrency: { strategy: "burst", debounceMs: 600 },
		});
	}
}

import { Agent } from "agents";
import { createChatSdkState } from "agents/chat-sdk";
import { Chat } from "chat";
import { createTelegramAdapter } from "@chat-adapter/telegram";

export { ChatSdkStateAgent } from "agents/chat-sdk";

export class MessengerAgent extends Agent<Env> {
	private chat!: Chat;

	onStart() {
		const telegram = createTelegramAdapter({
			botToken: this.env.TELEGRAM_BOT_TOKEN,
			mode: "webhook",
			userName: "my_bot",
		});

		this.chat = new Chat({
			adapters: { telegram },
			userName: "my_bot",
			state: createChatSdkState(),
			concurrency: { strategy: "burst", debounceMs: 600 },
		});
	}
}

Přidejte nadřazený Agent do migrace Durable Object:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  // Set this to today's date
  "compatibility_date": "2026-08-28",
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "durable_objects": {
    "bindings": [
      {
        "class_name": "MessengerAgent",
        "name": "MessengerAgent"
      }
    ]
  },
  "migrations": [
    {
      "new_sqlite_classes": [
        "MessengerAgent"
      ],
      "tag": "v1"
    }
  ]
}

# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = ["nodejs_compat"]

[[durable_objects.bindings]]
class_name = "MessengerAgent"
name = "MessengerAgent"

[[migrations]]
new_sqlite_classes = ["MessengerAgent"]
tag = "v1"

Export ChatSdkStateAgent z vstupního bodu vašeho Workeru, aby ho směrování sub-agenta mohlo přeložit. Když createChatSdkState() se volá uvnitř metody životního cyklu Agent nebo handleru požadavku, použije aktuální Agent jako nadřazený a vytvoří stavové shardy s this.subAgent().

Ve výchozím nastavení je stav Chat SDK shardován podle prvních dvou segmentů oddělených dvojtečkou v klíči podobném vláknu.

Například telegram:-100123:456 a telegram:-100123:789 sdílejí stejný shard stavu, telegram:-100123.

Výchozí key sharder rozpoznává tyto předpony klíčů Chat SDK:

• thread-state:
• channel-state:
• msg-history:
• transcripts:user:

Neznámé klíče používají výchozí název shardu adaptéru, default.

Použijte shardKey pro řízení toho, jak se ID vláken mapují na názvy stavových podřízených agentů:

const state = createChatSdkState({
	shardKey(threadId) {
		return threadId.split(":").slice(0, 2).join(":");
	},
});

const state = createChatSdkState({
	shardKey(threadId) {
		return threadId.split(":").slice(0, 2).join(":");
	},
});

Použijte keyShard když adaptér ukládá klíče, jejichž tvar neodpovídá vláknu, ale přesto by se měly směrovat na shard specifický pro poskytovatele:

const state = createChatSdkState({
	keyShard(key) {
		if (!key.startsWith("dedupe:telegram:")) {
			return undefined;
		}

		const chatId = key.slice("dedupe:telegram:".length).split(":")[0];
		return chatId ? `telegram:${chatId}` : undefined;
	},
});

const state = createChatSdkState({
	keyShard(key) {
		if (!key.startsWith("dedupe:telegram:")) {
			return undefined;
		}

		const chatId = key.slice("dedupe:telegram:".length).split(":")[0];
		return chatId ? `telegram:${chatId}` : undefined;
	},
});

Vracení undefined se vrátí k vestavěnému key sharderu a poté k výchozímu shardu.

Vytvoří Chat SDK StateAdapter podporovaný ChatSdkStateAgent podřízeného agenta.

import { createChatSdkState } from "agents/chat-sdk";

export { ChatSdkStateAgent } from "agents/chat-sdk";

const state = createChatSdkState({
	// parent: this // Optional. Defaults to the current Agent from getCurrentAgent().
});

import { createChatSdkState } from "agents/chat-sdk";

export { ChatSdkStateAgent } from "agents/chat-sdk";

const state = createChatSdkState({
	// parent: this // Optional. Defaults to the current Agent from getCurrentAgent().
});

Možnosti:

Třída sub-agenta, která ukládá stav do SQLite. Exportujte ji ze vstupního bodu Workeru, aby ji runtime mohl vytvořit.

export { ChatSdkStateAgent } from "agents/chat-sdk";

export { ChatSdkStateAgent } from "agents/chat-sdk";

Konkrétní StateAdapter implementaci vrácenou createChatSdkState(). Většina aplikací nepotřebuje vytvářet jeho instanci přímo.

Adaptér implementuje kompletní Chat SDK StateAdapter rozhraní:

• Odběry pro thread.subscribe() a thread.unsubscribe().
• Zámky pro souběžnost na úrovni vlákna nebo kanálu.
• Fronty čekajících zpráv pro queue, debounce, a burst strategie souběžnosti.
• Obecné položky mezipaměti typu klíč-hodnota s volitelným TTL.
• Seznamy pouze pro připojování s omezením maximální délky a obnovou TTL na úrovni seznamu.

Mezi funkce Chat SDK postavené na těchto primitivech patří:

• Deduplikace zpráv.
• Stav vlákna a kanálu.
• Trvalá historie vlákna pro adaptéry, které se přihlásí k persistThreadHistory.
• Ukládání tokenu v callback URL.
• Úložiště kontextu Modal.
• Přepisy napříč platformami.

Čtení TTL jsou přísná: vypršené zámky, hodnoty mezipaměti, položky fronty a položky seznamu jsou před vrácením ignorovány nebo smazány.

Fyzické čištění probíhá líně. ChatSdkStateAgent naplánuje jeden callback pro vyčištění k nejbližší známé expiraci a po jeho spuštění naplánuje další. Neaktivní shardy tak zůstávají v klidu a zároveň se zabraňuje neomezenému hromadění expirovaných řádků.