Custom thread list

useCloudThreadListRuntime puts Assistant Cloud's thread list around a per-thread runtime hook. Use it when your runtime does not have a cloud option, including AG-UI and A2A, or when you need to control the backend thread lifecycle yourself.

The hook gives the runtime Cloud threads and the history, attachment and feedback adapters as defaults; an adapter the wrapped runtime supplies itself is kept. A direct adapter is available when you need the list without the wrapper runtime.

Wrap a per-thread runtime

import { useCloudThreadListRuntime } from "@assistant-ui/react";

const runtime = useCloudThreadListRuntime({
  cloud,
  runtimeHook: useMyThreadRuntime,
  create: async () => ({ externalId: await backend.createThread() }),
  delete: async (cloudThreadId) => {
    const { external_id } = await cloud.threads.get(cloudThreadId);
    if (external_id) await backend.deleteThread(external_id);
  },
});

The wrapper always enables nested runtimes with allowNesting: true. It has no sdk or onThreadIdChange option. Use the lower-level adapter if you need an SDK identity, and use the remote-thread-list layer directly if your application needs an id change callback.

Use the adapter directly

useCloudThreadListAdapter creates a React-stable adapter. createCloudThreadListAdapter creates the same adapter outside a React hook and can receive either its options or a function that returns current options.

import { useCloudThreadListAdapter } from "@assistant-ui/react";

const adapter = useCloudThreadListAdapter({
  cloud,
  sdk: { name: "@acme/chat", version: "1.0.0" },
  create: async () => ({ externalId: await backend.createThread() }),
  delete: async (threadId) => backend.deleteThread(threadId),
});

The hook keeps the latest callbacks without rebuilding the adapter. Its memo key is the Cloud instance only, so changing create or delete does not replace the list, while changing cloud does. Keep one Cloud instance for the lifetime of the list, and create a new adapter if you replace it.

What the adapter calls

The adapter maps Cloud metadata to custom only when that metadata is an object. See Threads for the stored thread fields and Thread titles for title generation.

Use AG-UI or A2A

AG-UI and A2A do not create a Cloud adapter themselves. Place either per-thread runtime inside useCloudThreadListRuntime to give it Cloud threads, message history, attachments, feedback, engagement events and reports read from stored assistant messages.

import { useCloudThreadListRuntime } from "@assistant-ui/react";
import { useAgUiRuntime } from "@assistant-ui/react-ag-ui";

const runtime = useCloudThreadListRuntime({
  cloud,
  runtimeHook: () => useAgUiRuntime({ agent }),
});

import { useCloudThreadListRuntime } from "@assistant-ui/react";
import { useA2ARuntime } from "@assistant-ui/react-a2a";

const runtime = useCloudThreadListRuntime({
  cloud,
  runtimeHook: () => useA2ARuntime({ client }),
});

Add create and delete when either protocol has a corresponding backend conversation to create or remove.

Persist another message format

ThreadHistoryAdapter.withFormat(adapter) is the seam for a runtime whose messages are not aui/v0. Pass it a MessageFormatAdapter, then use createFormattedPersistence with CloudMessagePersistence when you need the same behavior outside the default Cloud history adapter.

import {
  CloudMessagePersistence,
  createFormattedPersistence,
} from "assistant-cloud";

const persistence = createFormattedPersistence(
  new CloudMessagePersistence(cloud),
  messageFormat,
);

withFormat returns load, append, optional update, optional delete and reportTelemetry. Call reportTelemetry(items, { durationMs, stepTimestamps, message }) after the response settles to build a run report from the encoded items and the source thread message. durationMs supplies the run duration, stepTimestamps supplies { start_ms, end_ms } for each step, and message supplies status and timing that the stored format may not carry.

What CloudMessagePersistence guarantees

Troubleshooting