ThreadRuntime

Runtime for thread state, messages, and viewport management.

`useAui` (Thread Actions)

Access thread actions via useAui:

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

const aui = useAui();
aui.thread().cancelRun();
aui.thread().append({ role: "user", content: [{ type: "text", text: "Hello" }] });

ThreadRuntime

path: ThreadRuntimePath

The selector for the thread runtime.

composer: ThreadComposerRuntime

The thread composer runtime.

getState: () => ThreadState

Gets a snapshot of the thread state.

append: (message: CreateAppendMessage) => void

Append a new message to the thread.

startRun: { (parentId: string | null): void; (config: CreateStartRunConfig): void; }

resumeRun: (config: CreateResumeRunConfig) => void

Resume a run with the given configuration.

unstable_resumeRununstable: (config: CreateResumeRunConfig) => void

exportExternalState: () => any

Export the thread state in the external store format. For AI SDK runtimes, this returns the AI SDK message format. For other runtimes, this may return different formats or throw an error.

importExternalState: (state: any) => void

Import thread state from the external store format. For AI SDK runtimes, this accepts AI SDK messages. For other runtimes, this may accept different formats or throw an error.

unstable_loadExternalStateunstable: (state: any) => void

Load external state into the thread.

subscribe: (callback: () => void) => Unsubscribe

cancelRun: () => void

getModelContext: () => ModelContext

getModelConfig: () => ModelContext

export: () => ExportedMessageRepository

import: (repository: ExportedMessageRepository) => void

reset: (initialMessages?: readonly ThreadMessageLike[] | undefined) => void

Reset the thread with optional initial messages.

getMessageByIndex: (idx: number) => MessageRuntime

getMessageById: (messageId: string) => MessageRuntime

stopSpeaking: () => void

connectVoice: () => void

disconnectVoice: () => void

getVoiceVolume: () => number

subscribeVoiceVolume: (callback: () => void) => Unsubscribe

muteVoice: () => void

unmuteVoice: () => void

unstable_onunstable: (event: ThreadRuntimeEventType, callback: () => void) => Unsubscribe

`useAuiState` (Thread State)

Access the thread state reactively:

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

const isRunning = useAuiState((s) => s.thread.isRunning);
const isLoading = useAuiState((s) => s.thread.isLoading);
const messages = useAuiState((s) => s.thread.messages);

ThreadState

threadId: string

The thread ID.

metadata: ThreadListItemState

The thread metadata.

isDisabled: boolean

Whether the thread is disabled. Disabled threads cannot receive new messages.

isLoading: boolean

Whether the thread is loading its history.

isRunning: boolean

Whether the thread is running. A thread is considered running when there is an active stream connection to the backend.

capabilities: RuntimeCapabilities

The capabilities of the thread, such as whether the thread supports editing, branch switching, etc.

messages: readonly ThreadMessage[]

The messages in the currently selected branch of the thread.

state: ReadonlyJSONValue

The thread state.

suggestions: readonly ThreadSuggestion[]

Follow up message suggestions to show the user.

extras: unknown

Custom extra information provided by the runtime.

speech: SpeechState | undefined

voice: VoiceSessionState | undefined

`useThreadViewport`

Manage thread viewport state (e.g., scrolling):

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

const threadViewport = useThreadViewport();
const isAtBottom = useThreadViewport((m) => m.isAtBottom);

ThreadViewportState

isAtBottom: boolean

Whether the thread is at the bottom.

scrollToBottom: (config?: { behavior?: ScrollBehavior }) => void

A function to scroll to the bottom.

onScrollToBottom: (callback: ({ behavior }: { behavior: ScrollBehavior }) => void) => Unsubscribe

A function to subscribe to scroll to bottom events.

turnAnchor: "top" | "bottom"

Controls scroll anchoring: "top" anchors user messages at top, "bottom" is classic behavior.

height: { viewport: number; inset: number; userMessage: number }

Raw height values from registered elements: total viewport height, total content inset height (footer, anchor message, etc.), and height of the anchor user message.

registerViewport: () => SizeHandle

registerContentInset: () => SizeHandle

registerUserMessageHeight: () => SizeHandle

useAui (Thread Actions)

useAuiState (Thread State)

useThreadViewport

`useAui` (Thread Actions)

`useAuiState` (Thread State)

`useThreadViewport`