Local runtime

useLocalRuntime runs your own chat model adapter, whatever protocol your backend speaks. Given a cloud, it gains the full Assistant Cloud integration: a remote thread list, persisted messages, automatic titles, run reports, engagement events, feedback and attachments. useDataStreamRuntime forwards the same local-runtime options, including cloud, so it uses the same thread list and adapters.

Setup

"use client";

import { useMemo } from "react";
import {
  AssistantCloud,
  AssistantRuntimeProvider,
  useLocalRuntime,
  type ChatModelAdapter,
} from "@assistant-ui/react";
import { ThreadList } from "@/components/assistant-ui/elements/thread-list.aui";
import { Thread } from "@/components/assistant-ui/elements/thread.aui";

const adapter: ChatModelAdapter = {
  async *run({ messages, abortSignal }) {
    const response = await fetch("/api/chat", {
      method: "POST",
      body: JSON.stringify({ messages }),
      signal: abortSignal,
    });
    const reader = response.body!.getReader();
    const decoder = new TextDecoder();
    let text = "";
    for (;;) {
      const { value, done } = await reader.read();
      if (done) break;
      text += decoder.decode(value, { stream: true });
      yield { content: [{ type: "text", text }] };
    }
  },
};

async function getToken() {
  // Return a user token from your auth provider.
  return "...";
}

export default function ChatPage() {
  const cloud = useMemo(
    () =>
      new AssistantCloud({
        baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
        authToken: getToken,
      }),
    [],
  );
  const runtime = useLocalRuntime(adapter, { cloud });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <div className="grid h-dvh grid-cols-[240px_1fr]">
        <ThreadList />
        <Thread />
      </div>
    </AssistantRuntimeProvider>
  );
}

On Next.js, useLocalRuntime(adapter) with NEXT_PUBLIC_ASSISTANT_BASE_URL set and no cloud uses an anonymous client, like the AI SDK runtime. On Vite, React Router and TanStack Start construct the client from import.meta.env.VITE_ASSISTANT_BASE_URL and pass it; on React Native and Ink construct the client from assistant-cloud and pass it.

What the cloud adds

useDataStreamRuntime first separates its data-stream options from local-runtime options, then passes the latter to useLocalRuntime. Supplying cloud therefore gives a data-stream runtime the same remote list, aui/v0 history, reporting, engagement, feedback and attachment adapters.

Store local messages as aui/v0

The cloud stores local-runtime history under format: "aui/v0". A row contains an assistant, user or system message, its status, content and metadata. The server supplies the top-level id and creation time when it reads the row back.

See Stored message formats for the complete aui/v0 shape.

Report a local run

Status and outcome come from the assistant message state. An incomplete message with an error becomes an error report; a complete message can use its finish reason for outcomes such as aborted, length or content_filter. First-token time is reported when the message carries metadata.timing. This path sends no run duration or step timing.

yield {
  content: [{ type: "text", text }],
  metadata: {
    custom: { modelId: "gpt-6-luna", provider: "openai", traceId },
    unstable_state: null,
  },
};

A run waiting for tool approval has requires-action status. Its message is persisted when the run pauses and updated after it resumes, but its telemetry extractor returns no report while it is paused. The terminal assistant message is the one reported.

The extractor reads only assistant messages. It keeps an incomplete status as incomplete and treats every other eligible status as completed. It reports tool calls with arguments, results and ids, but aui/v0 tool calls have no tool source. It concatenates text parts into output text capped at 50,000 characters, and sums usage from message steps without turning an absent counter into zero.

Compose the thread list yourself

Use custom thread list when your runtime has no cloud option or when its backend owns a separate thread id. useCloudThreadListRuntime wraps one per-thread runtime hook with the cloud list and its default adapters:

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

useAgUiRuntime and useA2ARuntime can be the runtimeHook. They read history and attachment adapters from this context, so they gain the cloud list, title action, aui/v0 persistence, engagement, feedback, attachments and reports 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 }),
});

For a custom stored-message shape, use ThreadHistoryAdapter.withFormat with a message-format adapter. The formatted persistence handles cloud id mapping and parent chaining, and its reportTelemetry method sends the stored items, duration, step timestamps and thread message as one report.

Troubleshooting