# Threads
URL: /docs/runtimes/concepts/threads

Single-thread, cloud, and custom-database thread management.

Every assistant-ui runtime starts with a single in-memory thread. Multi-thread support is added through one of three mechanisms depending on which runtime you are using and where you want threads to live.

## Single thread (default) \[#single-thread-default]

With no thread configuration, the runtime renders one thread that resets when the page reloads. Fine for prototypes, demos, and stateless interactions.

If you only want session persistence (single thread, durable across reloads), provide a [history adapter](/docs/runtimes/concepts/adapters#history-adapter) instead of going to multi-thread.

## Multi-thread paths \[#multi-thread-paths]

Three options. Choose based on what you want to own.

| Path                           | Runtime                               | Who owns thread metadata | Best for                                             |
| ------------------------------ | ------------------------------------- | ------------------------ | ---------------------------------------------------- |
| AssistantCloud                 | LocalRuntime and adapters built on it | assistant-cloud          | You want it managed; auth, sync, persistence handled |
| RemoteThreadListRuntime        | LocalRuntime and adapters built on it | Your database            | You have your own backend and want full control      |
| ExternalStoreThreadListAdapter | ExternalStoreRuntime only             | Your store               | You keep state in redux, zustand, etc.               |

## AssistantCloud \[#assistantcloud]

`AssistantCloud` is the managed multi-thread service. Pass an instance to `useLocalRuntime` (or any adapter built on it) and threads, persistence, sync, and titles are handled for you.

```tsx
import { useLocalRuntime } from "@assistant-ui/react";
import { AssistantCloud } from "assistant-cloud";

const cloud = new AssistantCloud({
  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL,
  anonymous: true,
});

const runtime = useLocalRuntime(modelAdapter, { cloud });
```

Framework adapters take `cloud` directly:

```tsx
const runtime = useChatRuntime({ cloud });
const runtime = useLangGraphRuntime({ cloud /* stream, load, ... */ });
const runtime = useAdkRuntime({ cloud, stream });
```

See the [cloud documentation](/docs/cloud) for setup, auth, and self-host options.

## RemoteThreadListRuntime (custom database) \[#remotethreadlistruntime-custom-database]

`useRemoteThreadListRuntime` lets you back the thread list with any database while keeping the per-thread runtime simple. You provide a `RemoteThreadListAdapter` describing how to list, create, rename, archive, and delete threads.

Works with any `LocalRuntime`-based runtime, including framework adapters that build on it (`react-ai-sdk`, `react-google-adk`, `react-a2a`, `useDataStreamRuntime`).

```tsx title="app/MyProvider.tsx"
"use client";

import {
  AssistantRuntimeProvider,
  useLocalRuntime,
  useRemoteThreadListRuntime,
  type RemoteThreadListAdapter,
} from "@assistant-ui/react";
import { createAssistantStream } from "assistant-stream";
import { modelAdapter } from "./model-adapter";

const adapter: RemoteThreadListAdapter = {
  async list() {
    const threads = await fetch("/api/threads").then((r) => r.json());
    return {
      threads: threads.map((t: any) => ({
        status: t.archived ? "archived" : "regular",
        remoteId: t.id,
        title: t.title,
      })),
    };
  },
  async initialize(localId) {
    const t = await fetch("/api/threads", {
      method: "POST",
      body: JSON.stringify({ localId }),
    }).then((r) => r.json());
    return { remoteId: t.id };
  },
  async rename(remoteId, title) {
    await fetch(`/api/threads/${remoteId}`, {
      method: "PATCH",
      body: JSON.stringify({ title }),
    });
  },
  async archive(remoteId) {
    await fetch(`/api/threads/${remoteId}/archive`, { method: "POST" });
  },
  async unarchive(remoteId) {
    await fetch(`/api/threads/${remoteId}/unarchive`, { method: "POST" });
  },
  async delete(remoteId) {
    await fetch(`/api/threads/${remoteId}`, { method: "DELETE" });
  },
  async fetch(remoteId) {
    const t = await fetch(`/api/threads/${remoteId}`).then((r) => r.json());
    return {
      status: t.archived ? "archived" : "regular",
      remoteId: t.id,
      title: t.title,
    };
  },
  async generateTitle(remoteId, messages) {
    return createAssistantStream(async (controller) => {
      const { title } = await fetch(`/api/threads/${remoteId}/title`, {
        method: "POST",
        body: JSON.stringify({ messages }),
      }).then((r) => r.json());
      controller.appendText(title);
    });
  },
};

export function MyProvider({ children }: { children: React.ReactNode }) {
  const runtime = useRemoteThreadListRuntime({
    runtimeHook: () => useLocalRuntime(modelAdapter),
    adapter,
  });
  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}
```

### Persisting messages with `unstable_Provider` \[#persisting-messages-with-unstable\_provider]

`RemoteThreadListAdapter` only manages thread metadata. To persist messages within each thread, expose a thread-scoped history adapter via the optional `unstable_Provider`:

```tsx
import {
  RuntimeAdapterProvider,
  useAui,
  type ThreadHistoryAdapter,
} from "@assistant-ui/react";
import { useMemo } from "react";

const adapterWithHistory: RemoteThreadListAdapter = {
  // ...metadata methods above...
  unstable_Provider({ children }) {
    const aui = useAui();
    const history = useMemo<ThreadHistoryAdapter>(
      () => ({
        async load() {
          const { remoteId } = aui.threadListItem().getState();
          if (!remoteId) return { messages: [] };
          const rows = await fetch(
            `/api/threads/${remoteId}/messages`,
          ).then((r) => r.json());
          return { messages: rows.map(toThreadMessage) };
        },
        async append({ message, parentId }) {
          const { remoteId } = await aui.threadListItem().initialize();
          await fetch(`/api/threads/${remoteId}/messages`, {
            method: "POST",
            body: JSON.stringify({ message, parentId }),
          });
        },
      }),
      [aui],
    );
    return (
      <RuntimeAdapterProvider adapters={{ history }}>
        {children}
      </RuntimeAdapterProvider>
    );
  },
};
```

<Callout type="warn">
  `unstable_Provider` must render `children` synchronously on first commit. Do not gate `children` behind a loading state, suspense, or `useEffect`. If you need to load data before the thread is usable, do it inside an always-rendered child (for example via the history adapter), not by withholding `children`.
</Callout>

### Avoiding the first-message race \[#avoiding-the-first-message-race]

`append` may be called before the thread record exists in your backend. Always await `aui.threadListItem().initialize()` before writing:

```ts
async append({ message, parentId }) {
  const { remoteId } = await aui.threadListItem().initialize();
  await saveMessage(remoteId, parentId, message);
}
```

`initialize()` is safe to call multiple times. It always resolves to the same `remoteId` for the active thread.

### Reloading after async authentication \[#reloading-after-async-authentication]

If your adapter depends on a user that resolves asynchronously (oidc, `next-auth`, `better-auth`), the initial `list()` may run before the user is available. Call `aui.threads().reload()` after auth completes:

```tsx
function ReloadOnAuth() {
  const aui = useAui();
  const { isLoading, user } = useAuth();
  useEffect(() => {
    if (!isLoading && user) aui.threads().reload();
  }, [isLoading, user?.id]);
  return null;
}
```

`reload()` discards in-flight responses from superseded calls, so it is safe to invoke on every auth transition.

### Adapter contract \[#adapter-contract]

<ParametersTable
  type="RemoteThreadListAdapter"
  parameters="[
{
name: &#x22;list&#x22;,
type: &#x22;() => Promise<{ threads: RemoteThreadMetadata[] }>&#x22;,
description:
&#x22;Hydrate threads on mount. Each thread must include status and remoteId; title, externalId, and custom are optional.&#x22;,
required: true,
},
{
name: &#x22;initialize&#x22;,
type: &#x22;(localId: string) => Promise<{ remoteId: string; externalId?: string }>&#x22;,
description:
&#x22;Create a new remote record when the user starts a conversation. Return the canonical ids.&#x22;,
required: true,
},
{
name: &#x22;rename&#x22;,
type: &#x22;(remoteId: string, title: string) => Promise<void>&#x22;,
description: &#x22;Persist title changes from the UI.&#x22;,
required: true,
},
{
name: &#x22;archive&#x22;,
type: &#x22;(remoteId: string) => Promise<void>&#x22;,
description: &#x22;Mark thread archived.&#x22;,
required: true,
},
{
name: &#x22;unarchive&#x22;,
type: &#x22;(remoteId: string) => Promise<void>&#x22;,
description: &#x22;Restore an archived thread.&#x22;,
required: true,
},
{
name: &#x22;delete&#x22;,
type: &#x22;(remoteId: string) => Promise<void>&#x22;,
description: &#x22;Permanently remove the thread.&#x22;,
required: true,
},
{
name: &#x22;fetch&#x22;,
type: &#x22;(threadId: string) => Promise<RemoteThreadMetadata>&#x22;,
description: &#x22;Fetch metadata for a single thread when switching.&#x22;,
required: true,
},
{
name: &#x22;generateTitle&#x22;,
type: &#x22;(remoteId: string, messages: readonly ThreadMessage[]) => Promise<AssistantStream>&#x22;,
description:
&#x22;Stream a title back. Use createAssistantStream and controller.appendText.&#x22;,
required: true,
},
{
name: &#x22;unstable_Provider&#x22;,
type: &#x22;ComponentType<PropsWithChildren>&#x22;,
description:
&#x22;Optional wrapper rendered around each active thread. Inject thread-scoped adapters (history, attachments) here.&#x22;,
},
]"
/>

### Custom metadata \[#custom-metadata]

`RemoteThreadMetadata` includes an optional `custom?: Record<string, unknown>` slot for backend-specific fields (timestamps, owner ids, workspace ids, tags, model name). Whatever you return from `list()` and `fetch()` flows through to the thread list item state and is reachable from any UI primitive via `useAuiState`.

```ts
type MyThreadMetadata = RemoteThreadMetadata & {
  readonly custom: {
    readonly createdAt: string;
    readonly ownerId: string;
  };
};
```

```tsx
import { useAuiState } from "@assistant-ui/react";

function ThreadListItemMeta() {
  const custom = useAuiState(
    (s) => s.threadListItem.custom as MyThreadMetadata["custom"] | undefined,
  );
  return (
    <span>
      {custom?.ownerId} · {custom?.createdAt}
    </span>
  );
}
```

`custom` is preserved across `rename`, `archive`, `unarchive`, and `generateTitle`. To mutate it, return updated values from a subsequent `fetch()` or call `runtime.threads.reload()`.

## ExternalStoreThreadListAdapter \[#externalstorethreadlistadapter]

For `ExternalStoreRuntime` users only. Wires multi-thread support into an external state store.

```tsx
const threadListAdapter: ExternalStoreThreadListAdapter = {
  threadId: currentThreadId,
  threads: threadList.filter((t) => t.status === "regular"),
  archivedThreads: threadList.filter((t) => t.status === "archived"),
  onSwitchToNewThread: () => {
    /* create + switch */
  },
  onSwitchToThread: (id) => setCurrentThreadId(id),
  onRename: (id, title) => {
    /* update */
  },
  onArchive: (id) => {
    /* archive */
  },
  onUnarchive: (id) => {
    /* unarchive */
  },
  onDelete: (id) => {
    /* delete */
  },
};

const runtime = useExternalStoreRuntime({
  messages: threads.get(currentThreadId) ?? [],
  setMessages: (messages) =>
    setThreads((m) => new Map(m).set(currentThreadId, messages)),
  onNew,
  adapters: { threadList: threadListAdapter },
});
```

Unlike `RemoteThreadListAdapter`, this adapter is synchronous and inline. You keep thread metadata and messages in your own store; the runtime just renders what you provide.

<Callout type="warn">
  The runtime's `currentThreadId` and your store's selected thread must stay in sync. Mismatched thread ids cause messages to appear in the wrong thread or vanish entirely. Centralize thread id state in a context, never in component-local state.
</Callout>

## Choosing \[#choosing]

Ask three questions in order:

1. **Do you want it managed?** Use `AssistantCloud`. You do not write database code.
2. **Do you have your own backend?** Use `RemoteThreadListRuntime` if you are on `LocalRuntime` (or any adapter built on it). You implement the adapter, you own the data.
3. **Are you on `ExternalStoreRuntime`?** Use `ExternalStoreThreadListAdapter`. Threads live in your store next to messages.

## Related \[#related]

<Cards>
  <Card title="Adapters" description="The shared adapter contracts (attachments, history, speech, feedback)." href="/docs/runtimes/concepts/adapters" />

  <Card title="Architecture" description="The three-layer runtime model and how threads flow through it." href="/docs/runtimes/concepts/architecture" />

  <Card title="AssistantCloud" description="The managed multi-thread service." href="/docs/cloud" />
</Cards>