---
title: Cloudflare Agents
description: Vendor-official state adapter for Chat SDK backed by Cloudflare Agents. Stores subscriptions, locks, queues, dedupe keys, thread and channel state, transcripts, and message history in Durable Object SQLite via ChatSdkStateAgent sub-agents.
tagline: State adapter for Chat SDK that persists subscriptions, locks, queues, and history in Durable Object SQLite, sharded across Cloudflare Agents sub-agents, with no Redis or external database.
package: agents
---

# Cloudflare Agents



## Install

<PackageInstall package="agents chat" />

## Quick start

Import the adapter from `agents/chat-sdk` when you run [Chat SDK](https://chat-sdk.dev) inside a [Cloudflare Agent](https://developers.cloudflare.com/agents/). Each state shard is a `ChatSdkStateAgent` sub-agent under your ingress Agent, and the adapter works with any Chat SDK platform adapter, including Telegram, Slack, Discord, Teams, and Google Chat.

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.

```typescript title="src/index.ts" lineNumbers
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 gets the current Agent from `getCurrentAgent()`, uses it as the parent, and creates state shards with `this.subAgent()`.

## Configuration

Pass these options to `createChatSdkState()`. All of them are optional:

<TypeTable
  type={{
  parent: {
    type: "Agent",
    description:
      "Parent Agent that calls `subAgent()` to create state shards. Defaults to the current Agent from `getCurrentAgent()`.",
  },
  agent: {
    type: "typeof ChatSdkStateAgent",
    description:
      "Custom subclass of `ChatSdkStateAgent`. Defaults to `ChatSdkStateAgent`.",
  },
  name: {
    type: "string",
    default: '"default"',
    description: "Default shard name for keys that cannot be mapped.",
  },
  shardKey: {
    type: "(threadId: string) => string",
    description: "Maps Chat SDK thread IDs and lock keys to a shard name.",
  },
  keyShard: {
    type: "(key: string) => string | undefined",
    description:
      "Maps generic Chat SDK cache or list keys to a shard name. Return `undefined` to fall back to the built-in sharder.",
  },
}}
/>

## Wrangler configuration

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

```jsonc title="wrangler.jsonc"
{
  "compatibility_date": "2026-07-02",
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "class_name": "MessengerAgent", "name": "MessengerAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MessengerAgent"] }]
}
```

```toml title="wrangler.toml"
compatibility_date = "2026-07-02"
compatibility_flags = ["nodejs_compat"]

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

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

## Data model

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 builds message deduplication, thread and channel state, callback URL token storage, modal context storage, and cross-platform transcripts on these primitives. Persistent thread history uses them too, for adapters that opt in to `persistThreadHistory`.

## 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`.

Telegram Business threads (`telegram:biz:{connectionId}:{chatId}`) all share the shard `telegram:biz` under this rule. Use a custom `shardKey` that keeps the connection ID if you expect many business conversations.

### 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:

```typescript
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.

## 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, so idle shards stay quiet and expired rows don't accumulate.

## API

### `createChatSdkState(options)`

Creates a Chat SDK `StateAdapter` backed by a `ChatSdkStateAgent` sub-agent. With no options, it resolves the parent from `getCurrentAgent()` and shards by thread-like key prefixes. See [Configuration](#configuration) for the full option list.

### `ChatSdkStateAgent`

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

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

## Feature support

<FeatureSupport />

## Resources

* [GitHub](https://github.com/cloudflare/agents)
* [Chat SDK messenger example](https://github.com/cloudflare/agents/tree/main/examples/chat-sdk-messenger): a Telegram messenger bot with Chat SDK state in sub-agents, burst/debounce concurrency, and AI replies running in managed fibers.
* [Cloudflare Agents docs](https://developers.cloudflare.com/agents/runtime/communication/chat-sdk/)