ThreadRuntime

Runtime for thread state, messages, and viewport management.

`useThreadRuntime`

Get the thread runtime object:

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

const thread = useThreadRuntime();

ThreadRuntime

pathrequired: ThreadRuntimePath

The selector for the thread runtime.

composerrequired: ThreadComposerRuntime

The thread composer runtime.

getStaterequired: () => ThreadState

Gets a snapshot of the thread state.

appendrequired: (message: CreateAppendMessage) => void

Append a new message to the thread.

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

unstable_resumeRunrequired: (config: CreateResumeRunConfig) => void

Resume a run with the given configuration.

exportExternalStaterequired: () => 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.

importExternalStaterequired: (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_loadExternalStaterequired: (state: any) => void

Load external state into the thread.

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

cancelRunrequired: () => void

getModelContextrequired: () => ModelContext

getModelConfigrequired: () => ModelContext

exportrequired: () => ExportedMessageRepository

importrequired: (repository: ExportedMessageRepository) => void

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

Reset the thread with optional initial messages.

getMessageByIndexrequired: (idx: number) => MessageRuntime

getMessageByIdrequired: (messageId: string) => MessageRuntime

stopSpeakingrequired: () => void

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

`useThread`

Access the thread state directly:

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

const thread = useThread();
const isRunning = useThread((m) => m.isRunning);
const isLoading = useThread((m) => m.isLoading);

ThreadState

threadIdrequired: string

The thread ID.

metadatarequired: ThreadListItemState

The thread metadata.

isDisabledrequired: boolean

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

isLoadingrequired: boolean

Whether the thread is loading its history.

isRunningrequired: boolean

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

capabilitiesrequired: RuntimeCapabilities

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

messagesrequired: readonly ThreadMessage[]

The messages in the currently selected branch of the thread.

staterequired: ReadonlyJSONValue

The thread state.

suggestionsrequired: readonly ThreadSuggestion[]

Follow up message suggestions to show the user.

extrasrequired: unknown

Custom extra information provided by the runtime.

speechrequired: SpeechState | 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

isAtBottomrequired: boolean

Whether the thread is at the bottom.

scrollToBottomrequired: () => void

A function to scroll to the bottom.

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

A function to subscribe to scroll to bottom events.