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

Chat SDK

Используйте agents/chat-sdk при запуске Chat SDK ↗ внутри агента. Первой вспомогательной функцией для интеграции является Chat SDK StateAdapter который хранит состояние в дочерних агентах Agents.

Адаптер хранит подписки, блокировки, очереди, ключи дедупликации, состояние треда, состояние канала, метаданные колбэков, списки транскриптов и историю треда Chat SDK в Durable Object SQLite. Каждый шард состояния, это ChatSdkStateAgent дочерний агент под вашим входным (ingress) Agent.

Установите оба пакета в Worker, на котором размещён ваш messenger ingress:

npm i agents chat

agents/chat-sdk предоставляет устойчивое состояние для Chat SDK. Используйте его с любым адаптером Chat SDK, например Telegram, Slack, Discord, Teams или Google Chat.

Создайте родительский Agent, который владеет вашим рантаймом Chat SDK. Передайте createChatSdkState() как Chat SDK state опцию.

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

Добавьте родительский Agent в миграцию 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"

Экспортировать ChatSdkStateAgent из точки входа вашего Worker, чтобы маршрутизация к дочерним агентам могла его найти. Когда createChatSdkState() вызывается внутри метода жизненного цикла Agent или обработчика запроса, он использует текущий Agent как родительский и создаёт шарды состояния с this.subAgent().

По умолчанию состояние Chat SDK делится на шарды по первым двум сегментам, разделённым двоеточием, в ключе, похожем на идентификатор треда.

Например, telegram:-100123:456 и telegram:-100123:789 используют один и тот же шард состояния, telegram:-100123.

Стандартный key sharder распознаёт следующие префиксы ключей Chat SDK:

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

Для неизвестных ключей используется имя шарда адаптера по умолчанию, default.

Используйте shardKey чтобы управлять тем, как ID потоков сопоставляются с именами дочерних агентов состояния:

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

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

Используйте keyShard когда адаптер хранит ключи, не имеющие формы thread, которые всё равно должны маршрутизироваться к шарду конкретного провайдера:

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

Возврат undefined переключается на встроенный key sharder, а затем на shard по умолчанию.

Создаёт Chat SDK StateAdapter на основе ChatSdkStateAgent дочерний агент.

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

Варианты:

Класс дочернего агента, который хранит состояние в SQLite. Экспортируйте его из точки входа Worker, чтобы runtime мог его создать.

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

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

Конкретный StateAdapter реализацию, возвращённую createChatSdkState(). Большинству приложений не нужно создавать его экземпляр напрямую.

Адаптер реализует полный Chat SDK StateAdapter интерфейс:

• Подписки на thread.subscribe() и thread.unsubscribe().
• Блокировки для параллелизма по потокам или каналам.
• Очереди ожидающих сообщений для queue, debounce, а также burst стратегии параллелизма.
• Обычные записи кеша типа ключ-значение с опциональным TTL.
• Списки только для добавления с обрезкой по максимальной длине и обновлением TTL на уровне списка.

Среди функций Chat SDK, построенных на этих примитивах:

• Дедупликация сообщений.
• Состояние потока и канала.
• Постоянная история треда для адаптеров, которые подключают persistThreadHistory.
• Хранение токена URL обратного вызова.
• Модальное хранилище контекста.
• Расшифровки для разных платформ.

Чтение TTL выполняется строго: истёкшие блокировки, значения кэша, записи очереди и элементы списка игнорируются или удаляются до того, как будут возвращены.

Физическая очистка выполняется лениво. ChatSdkStateAgent планирует один callback очистки на самый ранний известный срок истечения и перепланирует его после выполнения очистки. Это избавляет неактивные шарды от лишней нагрузки, не позволяя истёкшим строкам накапливаться бесконечно.