assistant-ui Runtime

SkillCommunication

Gives your agent a guide for building chat interfaces with assistant-ui, covering runtimes, state access, and message handling.

Available today. Use it from your connected AI after setup.

No other account needed.

Connect ahel once, and every AI you use reads what you have installed.

Then ask your AI: use the assistant-ui Runtime skill

About this capability

Guide for assistant-ui runtime system and state management. Use when working with runtimes, accessing state, or managing thread/message data.

What this skill tells your AI

The instructions your AI receives, as published by compozy/compozy in .agents/skills/assistant-ui/assistant-ui-runtime/SKILL.md and read by ahel’s review.

Always consult assistant-ui.com/llms.txt for latest API.

References

./references/local-runtime.md -- useLocalRuntime deep dive
./references/external-store.md -- useExternalStoreRuntime deep dive
./references/thread-list.md -- Thread list management
./references/state-hooks.md -- State access hooks
./references/types.md -- Type definitions

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 onClick={() => api.thread().append({
        role: "user",
        content: [{ type: "text", text: "Hello!" }],
      })}>
        Send
      </button>
      {isRunning && (
        <button onClick={() => api.thread().cancelRun()}>Cancel</button>
      )}
    </div>
  );
}

Thread Operations

const api = useAui();
const thread = api.thread();

// Append message
thread.append({ role: "user", content: [{ type: "text", text: "Hello" }] });

// Cancel generation
thread.cancelRun();

// Get current state
const state = thread.getState();  // { messages, isRunning, ... }

Message Operations

const message = api.thread().message(0);  // By index

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 }

Quick Reference

// Get messages
const messages = useAuiState(s => s.thread.messages);

// Check running state
const isRunning = useAuiState(s => s.thread.isRunning);

// Append message
api.thread().append({ role: "user", content: [{ type: "text", text: "Hi" }] });

// Cancel generation
api.thread().cancelRun();

// Edit message
api.thread().message(index).edit({ ... });

// Reload message
api.thread().message(index).reload();