Cloudflare Agents

Use agents/chat-sdk when you run Chat SDK inside a Cloudflare Agent. It provides a Chat SDK StateAdapter that stores subscriptions, locks, queues, dedupe keys, thread and channel state, callback metadata, transcripts, and thread history in Durable Object SQLite. Each state shard is a ChatSdkStateAgent sub-agent under your ingress Agent.

Use it with any Chat SDK adapter — Telegram, Slack, Discord, Teams, or Google Chat.

Install

Quick start

Create a parent Agent that owns your Chat SDK runtime and pass createChatSdkState() as the state option. Export ChatSdkStateAgent from your Worker entry point so sub-agent routing can resolve it.

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

When createChatSdkState() runs inside an Agent lifecycle method or request handler, it uses the current Agent as the parent (via getCurrentAgent()) and creates state shards with this.subAgent().

Wrangler configuration

Add the parent Agent to your Durable Object migration and enable nodejs_compat:

{
  "compatibility_date": "2026-07-02",
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "class_name": "MessengerAgent", "name": "MessengerAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MessengerAgent"] }]
}

compatibility_date = "2026-07-02"
compatibility_flags = ["nodejs_compat"]

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

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

State sharding

By default, state is sharded by the first two colon-separated segments of a thread-like key. For example, telegram:-100123:456 and telegram:-100123:789 share the shard telegram:-100123.

The default key sharder recognizes these Chat SDK key prefixes:

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

Unknown keys use the adapter's default shard name, default.

Custom sharding

Use shardKey to control how thread IDs map to state sub-agent names, and keyShard for non-thread-shaped keys that should still route to a provider-specific shard:

const state = createChatSdkState({
  shardKey(threadId) {
    return threadId.split(":").slice(0, 2).join(":");
  },
  keyShard(key) {
    if (!key.startsWith("dedupe:telegram:")) {
      return undefined;
    }

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

Returning undefined from keyShard falls back to the built-in key sharder and then to the default shard.

Configuration

What is stored

The adapter implements the full Chat SDK StateAdapter interface:

• Subscriptions for thread.subscribe() and thread.unsubscribe().
• Locks for per-thread or per-channel concurrency.
• Pending message queues for queue, debounce, and burst concurrency strategies.
• Generic key-value cache entries with optional TTL.
• Append-only lists with max-length trimming and list-level TTL refresh.

Chat SDK features built on these primitives include message deduplication, thread and channel state, persistent thread history (for adapters that opt in to persistThreadHistory), callback URL token storage, modal context storage, and cross-platform transcripts.

Cleanup behavior

TTL reads are strict: expired locks, cache values, queue entries, and list entries are ignored or deleted before they are returned.

Physical cleanup is lazy. ChatSdkStateAgent schedules one cleanup callback for the earliest known expiry and reschedules after cleanup runs. This keeps idle shards quiet while preventing expired rows from accumulating indefinitely.

API

createChatSdkState(options)

Creates a Chat SDK StateAdapter backed by a ChatSdkStateAgent sub-agent. Options are optional — the defaults resolve the parent from getCurrentAgent() and shard by thread-like key prefixes.

ChatSdkStateAgent

The sub-agent class that stores state in SQLite. Export it from your Worker entry point so the runtime can create it:

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

Example

• GitHub
• Chat SDK messenger example — a Telegram messenger bot with Chat SDK state in sub-agents, burst/debounce concurrency, and AI replies running in managed fibers.
• Cloudflare Agents docs

Feature support