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 runtime built on useExternalStoreRuntime stores a copy of its settled messages through that history adapter, as LangGraph, LangChain and ADK describes. 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,
  scopeId: workspace.id,
  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 it from @assistant-ui/core/react; @assistant-ui/react does not export it.

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

const adapter = useCloudThreadListAdapter({
  cloud,
  scopeId: workspace.id,
  sdk: { name: "@acme/chat", version: "1.0.0" },
  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 hook keeps the latest callbacks without rebuilding the adapter. Its identity is keyed by the Cloud instance and scopeId, so changing create or delete does not replace the list, while changing cloud or scopeId does. Keep one Cloud instance for the lifetime of a scope and reload the remote list after publishing a replacement adapter.

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. AG-UI stores its final agent state in metadata.unstable_state, activity values as agui-activity/<type> data parts, and A2UI present calls with artifact.a2ui. A2A stores the same A2UI calls and its artifacts in metadata.custom.a2a.artifacts, without bytes from inline files. See Stored message formats.

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, userMessageId, persistenceError }) 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, message supplies status and timing that the stored format may not carry, userMessageId is the local ID of the user message that started the run, and persistenceError is the error of a failed append or update for the turn, which reports a completed turn as persistence_error. The cloud adapter resolves userMessageId through persistence, awaiting a pending append before sending user_message_id. An unmapped or failed append omits the field; a scope change during the wait drops the report. Omit userMessageId for a prompt you are deleting, because telemetry delivery is asynchronous.

What CloudMessagePersistence guarantees

Troubleshooting