Runtime API

The runtime API allows you to interact with the runtime in a standardized way. This API is used internaly by the components. You can also use it to build your own UI components or functionality.

AssistantRuntime

The AssistantRuntime is the root runtime.

`useAssistantRuntime`

import { useAssistantRuntime } from "@assistant-ui/react";
 
const runtime = useAssistantRuntime();

AssistantRuntime

thread:

ThreadRuntime

The currently selected main thread.

threadList:

ThreadListRuntime

The thread manager, to rename, archive and delete threads.

switchToNewThread:

() => void

Switch to a new thread.

switchToThread:

(threadId: string) => void

Switch to a thread.

registerModelConfigProvider:

(provider: ModelConfigProvider) => Unsubscribe

Register a model config provider. Model config providers are configuration such as system message, temperature, etc. that are set in the frontend.

Tool UI Registry

The tool UI registry is used to display custom UI for tool calls, enabling generative UI.

`useToolUIs`

import { useToolUIs } from "@assistant-ui/react";
 
const toolUIs = useToolUIs();
const webSearchToolUI = useToolUIs((m) => m.getToolUI("web_search"));

AssistantToolUIsState

getToolUI:

(toolName: string) => ToolCallContentPartComponent | null

Get the tool UI configured for a given tool name.

setToolUI:

(toolName: string, render: ToolCallContentPartComponent) => Unsubscribe

Registers a tool UI for a given tool name. Returns an unsubscribe function to remove the tool UI.

ThreadListRuntime

`threadList`

import { useAssistantRuntime } from "@assistant-ui/react";
 
const threadListRuntime = useAssistantRuntime().threadList;

ThreadListRuntime

getState:

() => ThreadListState

subscribe:

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

mainThreadListItem:

ThreadListItemRuntime

getThreadListItemById:

(threadId: string) => ThreadListItemRuntime

getThreadListItemByIndex:

(idx: number) => ThreadListItemRuntime

getThreadListArchivedItemByIndex:

(idx: number) => ThreadListItemRuntime

`useThreadList`

import { useThreadList } from "@assistant-ui/react";
 
const threadList = useThreadList();
const threads = useThreadList((m) => m.threads);

ThreadListItemRuntime

`useThreadListItemRuntime`

import { useThreadListItemRuntime } from "@assistant-ui/react";
 
const threadListItemRuntime = useThreadListItemRuntime();

ThreadListItemRuntime

path:

ThreadListItemRuntimePath

getState:

() => ThreadListItemState

switchTo:

() => Promise<void>

rename:

(newTitle: string) => Promise<void>

archive:

() => Promise<void>

unarchive:

() => Promise<void>

delete:

() => Promise<void>

subscribe:

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

unstable_on:

(event: ThreadListItemEventType, callback: () => void) => Unsubscribe

`useThreadListItem`

import { useThreadListItem } from "@assistant-ui/react";
 
const threadListItem = useThreadListItem();
const title = useThreadListItem((m) => m.title);

ThreadListItemState

isMain:

boolean

id:

string

threadId:

string

state:

"archived" | "regular" | "new" | "deleted"

title?:

string | undefined

Thread Context

`useThreadRuntime`

import { useThreadRuntime } from "@assistant-ui/react";
 
const thread = useThreadRuntime();

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

subscribe:

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

cancelRun:

() => void

getModelConfig:

() => ModelConfig

export:

() => ExportedMessageRepository

import:

(repository: ExportedMessageRepository) => void

getMesssageByIndex:

(idx: number) => MessageRuntime

getMesssageById:

(messageId: string) => MessageRuntime

stopSpeaking:

() => void

unstable_on:

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

`useThread`

import { useThread } from "@assistant-ui/react";
 
const thread = useThread();
const isRunning = useThread((m) => m.isRunning);

ThreadState

threadId:

string

The thread ID.

metadata:

ThreadListItemState

The thread metadata.

isDisabled:

boolean

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

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.

suggestions:

readonly ThreadSuggestion[]

Follow up message suggestions to show the user.

extras:

unknown

Custom extra information provided by the runtime.

speech:

SpeechState | undefined

`useThreadMessages`

import { useThreadMessages } from "@assistant-ui/react";
 
const messages = useThreadMessages();
const firstMessage = useThreadMessages((m) => m[0]);

ThreadMessagesState

messages:

readonly ThreadMessage[]

The messages in the thread.

`useThreadComposer`

import { useThreadComposer } from "@assistant-ui/react";
 
const composer = useThreadComposer();
const text = useThreadComposer((m) => m.text);

ComposerState

text:

string

The current text of the composer.

setText:

(text: string) => void

A function to set the text of the composer.

attachments:

readonly Attachment[]

The current attachments of the composer.

addAttachment:

(attachment: Attachment) => void

A function to add an attachment to the composer.

removeAttachment:

(attachmentId: string) => void

A function to remove an attachment from the composer.

reset:

() => void

A function to reset the composer.

canCancel:

true

Whether the composer can be canceled.

isEditing:

true

Whether the composer is in edit mode.

send:

() => void

A function to send the message.

cancel:

() => void

A function to cancel the run.

focus:

() => void

A function to focus the composer.

onFocus:

(listener: () => void) => Unsubscribe

A function to subscribe to focus events.

`useThreadViewport`

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:

() => void

A function to scroll to the bottom.

onScrollToBottom:

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

A function to subscribe to scroll to bottom events.

Message Context

`useMessage`

import { useMessage } from "@assistant-ui/react";
 
const { message } = useMessage();
const message = useMessage((m) => m.message);

MessageState

message:

Readonly<ThreadMessage>

The current message.

parentId:

string | null

The parent message id.

branches:

readonly string[]

The branches for the message.

isLast:

boolean

Whether the message is the last in the thread.

`useMessageUtils`

import { useMessageUtils } from "@assistant-ui/react";
 
const messageUtils = useMessageUtils();
const isCopied = useMessageUtils((m) => m.isCopied);

MessageUtilsState

isCopied:

boolean

Whether the message is copied.

setIsCopied:

(value: boolean) => void

A function to set the is copied.

isHovering:

boolean

Whether the message is being hovered.

setIsHovering:

(value: boolean) => void

A function to set the is hovering.

isSpeaking:

boolean

Whether the message is currently being spoken.

stopSpeaking:

() => void

A function to stop the message from being spoken.

addUtterance:

(utterance: SpeechSynthesisAdapter.Utterance) => void

A function to add a speech utterance.

`useEditComposer`

import { useEditComposer } from "@assistant-ui/react";
 
const editComposer = useEditComposer();
const text = useEditComposer((m) => m.text);

EditComposerState

text:

string

The current text of the composer.

setText:

(text: string) => void

A function to set the text of the composer.

attachments:

readonly Attachment[]

The current attachments of the composer.

addAttachment:

(attachment: Attachment) => void

A function to add an attachment to the composer.

removeAttachment:

(attachmentId: string) => void

A function to remove an attachment from the composer.

reset:

() => void

A function to reset the composer.

canCancel:

boolean

Whether the composer can be canceled.

isEditing:

boolean

Whether the composer is in edit mode.

edit:

() => void

A function to enter edit mode.

send:

() => void

A function to send the message.

cancel:

() => void

A function to exit the edit mode.

Content Part Context

`useContentPart`

import { useContentPart } from "@assistant-ui/react";
 
const part = useContentPart();
const part = useContentPart.getState();
 
const status = useContentPart((m) => m.status);
const status = useContentPart.getState().status;

ContentPartState

part:

Readonly<ContentPartState>

The current content part.

status:

MessageStatus

The current content part status.

MessageStatus

type:

'running' | 'requires-action' | 'complete' | 'incomplete'

The status.

finish-reason?:

The finish reason if the status is 'incomplete'.

error?:

unknown

The error object if the status is 'error'.

Composer Context

Grabs the nearest composer state (either the edit composer or the thread's new message composer).

`useComposer`

import { useComposer } from "@assistant-ui/react";
 
const composer = useComposer();
const text = useComposer((m) => m.text);

Attachment Context

Grabs the attachment state (either the composer or message attachment).

`useAttachment`

import { useAttachment } from "@assistant-ui/react";
 
const { attachment } = useAttachment();
const attachment = useAttachment((m) => m.attachment);

`useComposerAttachment` (Composer)

import { useComposerAttachment } from "@assistant-ui/react";
 
const { attachment } = useComposerAttachment();
const attachment = useComposerAttachment((m) => m.attachment);

ComposerAttachmentState

attachment:

ComposerAttachment

The current composer attachment.

`useMessageAttachment` (Message)

import { useMessageAttachment } from "@assistant-ui/react";
 
const { attachment } = useMessageAttachment();
const attachment = useMessageAttachment((m) => m.attachment);

MessageAttachmentState

attachment:

MessageAttachment

The current message attachment.