assistant-ui Runtime
Always consult assistant-ui.com/llms.txt for the latest API.
References
Runtime Hierarchy
AssistantRuntime
├── ThreadListRuntime (thread management)
│ ├── ThreadListItemRuntime (per-thread item)
│ └── ...
└── ThreadRuntime (current thread)
├── ComposerRuntime (input state)
└── MessageRuntime[] (per-message)
└── MessagePartRuntime[] (per-content-part)
State Access (Modern API)
import { useAui, useAuiState, useAuiEvent } from "@assistant-ui/react";
function ChatControls() {
const api = useAui();
const messages = useAuiState(s => s.thread.messages);
const isRunning = useAuiState(s => s.thread.isRunning);
useAuiEvent("composer.send", (e) => {
console.log("Sent in thread:", e.threadId);
});
return (
<div>
<button => api.thread().append({
role: "user",
content: [{ type: "text", text: "Hello!" }],
})}>
Send
</button>
{isRunning && (
<button => api.thread().cancelRun()}>Cancel</button>
)}
</div>
);
}
Thread Operations
const api = useAui();
const thread = api.thread();
thread.append({ role: "user", content: [{ type: "text", text: "Hello" }] });
thread.cancelRun();
const state = thread.getState(); // { messages, isRunning, ... }
Message Operations
const message = api.thread().message(0);
message.edit({ role: "user", content: [{ type: "text", text: "Updated" }] });
message.reload();
Events
useAuiEvent("thread.runStart", () => {});
useAuiEvent("thread.runEnd", () => {});
useAuiEvent("composer.send", ({ threadId }) => {
console.log("Sent in thread:", threadId);
});
useAuiEvent("thread.modelContextUpdate", () => {});
Capabilities
const caps = useAuiState(s => s.thread.capabilities);
// { cancel, edit, reload, copy, speak, attachments }
Common Gotchas
"Cannot read property of undefined"
- Ensure hooks are called inside
AssistantRuntimeProvider
State not updating
- Use selectors with
useAuiState to prevent unnecessary re-renders
Messages array empty
- Check runtime is configured
- Verify API response format
1---2name: runtime3description: Guide to the assistant-ui runtime system, single-thread state, and the imperative runtime API in @assistant-ui/react. Use when creating a runtime (useLocalRuntime with a ChatModelAdapter, useExternalStoreRuntime for Redux/Zustand, useRemoteThreadListRuntime), wiring AssistantRuntimeProvider, or reading/mutating thread, message, and composer state and events. Covers the unified hooks useAui, useAuiState, useAuiEvent (composer.send, thread.runStart, thread.runEnd), legacy hooks (useAssistantRuntime, useThreadRuntime, useMessageRuntime, useComposerRuntime, useThread, useThreadMessages), the AssistantRuntime/ThreadRuntime/MessageRuntime/ComposerRuntime hierarchy, thread operations (append, cancelRun, message().edit/reload), capabilities, and types (ThreadMessage, MessagePart, MessageStatus, ChatModelRunResult). Use for provider "Cannot read property of undefined" errors or state not updating. For multi-thread list UI and switching between conversations use thread-list instead.4license: MIT5---67# assistant-ui Runtime89**Always consult [assistant-ui.com/llms.txt](https://www.assistant-ui.com/llms.txt) for the latest API.**1011## References1213- [./references/local-runtime.md](./references/local-runtime.md) -- useLocalRuntime deep dive14- [./references/external-store.md](./references/external-store.md) -- useExternalStoreRuntime deep dive15- [./references/thread-list.md](./references/thread-list.md) -- Thread list management16- [./references/state-hooks.md](./references/state-hooks.md) -- State access hooks17- [./references/types.md](./references/types.md) -- Type definitions18- [./references/adapters.md](./references/adapters.md) -- Attachment, speech, dictation, suggestion, and history adapters19- [./references/voice.md](./references/voice.md) -- Realtime voice chat20- [./references/runtime-concepts.md](./references/runtime-concepts.md) -- Stability policy, transport runtime, message timing2122## Runtime Hierarchy2324```25AssistantRuntime26├── ThreadListRuntime (thread management)27│ ├── ThreadListItemRuntime (per-thread item)28│ └── ...29└── ThreadRuntime (current thread)30 ├── ComposerRuntime (input state)31 └── MessageRuntime[] (per-message)32 └── MessagePartRuntime[] (per-content-part)33```3435## State Access (Modern API)3637```tsx38import { useAui, useAuiState, useAuiEvent } from "@assistant-ui/react";3940function ChatControls() {41 const api = useAui();42 const messages = useAuiState(s => s.thread.messages);43 const isRunning = useAuiState(s => s.thread.isRunning);4445 useAuiEvent("composer.send", (e) => {46 console.log("Sent in thread:", e.threadId);47 });4849 return (50 <div>51 <button onClick={() => api.thread().append({52 role: "user",53 content: [{ type: "text", text: "Hello!" }],54 })}>55 Send56 </button>57 {isRunning && (58 <button onClick={() => api.thread().cancelRun()}>Cancel</button>59 )}60 </div>61 );62}63```6465## Thread Operations6667```tsx68const api = useAui();69const thread = api.thread();7071thread.append({ role: "user", content: [{ type: "text", text: "Hello" }] });7273thread.cancelRun();7475const state = thread.getState(); // { messages, isRunning, ... }76```7778## Message Operations7980```tsx81const message = api.thread().message(0);8283message.edit({ role: "user", content: [{ type: "text", text: "Updated" }] });84message.reload();85```8687## Events8889```tsx90useAuiEvent("thread.runStart", () => {});91useAuiEvent("thread.runEnd", () => {});92useAuiEvent("composer.send", ({ threadId }) => {93 console.log("Sent in thread:", threadId);94});95useAuiEvent("thread.modelContextUpdate", () => {});96```9798## Capabilities99100```tsx101const caps = useAuiState(s => s.thread.capabilities);102// { cancel, edit, reload, copy, speak, attachments }103```104105## Common Gotchas106107**"Cannot read property of undefined"**108- Ensure hooks are called inside `AssistantRuntimeProvider`109110**State not updating**111- Use selectors with `useAuiState` to prevent unnecessary re-renders112113**Messages array empty**114- Check runtime is configured115- Verify API response format
diamitani