Runtime options

Reference for the runtime's API surface. Start with quickstart if you have not already.

useAgUiRuntime options

Adapter slots

Loading conversation history

If your backend exposes the persisted AG-UI messages of a conversation (for example a GET /agents/state endpoint), use fromAgUiMessages to convert them to assistant-ui messages and return them from the history adapter so the thread is restored on page load:

import { fromAgUiMessages } from "@assistant-ui/react-ag-ui";
import { ExportedMessageRepository } from "@assistant-ui/react";

const runtime = useAgUiRuntime({
  agent,
  adapters: {
    history: {
      async load() {
        const { messages } = await fetch("/agents/state").then((r) => r.json());
        return ExportedMessageRepository.fromArray(fromAgUiMessages(messages));
      },
      async append({ message }) {
        // persist the newly sent message on your backend
      },
    },
  },
});

Messages sent during the session are always forwarded to the agent through the run input, independent of append. A no-op append is therefore only safe when your backend already persists the conversation on its own; otherwise those messages are gone on the next page load.

fromAgUiMessages accepts an optional second argument: pass { showThinking: false } to match a runtime configured with showThinking: false, so imported reasoning messages are dropped at conversion time, the same way a live run never stores them.

fromAgUiMessages reconstructs the text, reasoning, and tool calls of each message. Multimodal user input (image, audio, video, and document parts, as well as legacy binary parts) is restored as attachments on the user message, so a backend that persists multimodal messages shows them again on reload and re-sends them on the next run. Legacy binary parts that only reference a file id are not restored.

Thread list (experimental)

UseAgUiThreadListAdapter lets you back the thread list with your own state.

const runtime = useAgUiRuntime({
  agent,
  adapters: {
    threadList: {
      threadId: currentThreadId,
      onSwitchToNewThread: async () => {
        setCurrentThreadId(await createThread());
      },
      onSwitchToThread: async (id) => {
        const { messages, state } = await loadThread(id);
        setCurrentThreadId(id);
        return { messages, state };
      },
    },
  },
});

Interrupts (experimental)

When the agent emits RUN_FINISHED with outcome = { type: "interrupt", interrupts: [...] }, the active assistant message is marked requires-action with reason: "interrupt" and the Interrupt[] payload is written to metadata.custom.agui.interrupts. Render an approval / input UI from there.

useAgUiRuntime returns an AgUiAssistantRuntime with two extra methods:

responses must address every open interrupt; missing entries, unknown ids, or expired interrupts (expiresAt) reject before any network call. Each entry is { interruptId, status: "resolved" | "cancelled", payload? }. The next RunAgentInput carries resume: ResumeEntry[].

const runtime = useAgUiRuntime({ agent });
const pending = runtime.unstable_getPendingInterrupts();

await runtime.unstable_submitInterruptResponses(
  pending.map((i) => ({
    interruptId: i.id,
    status: "resolved",
    payload: { approved: true },
  })),
);

Supported events

The runtime parses the AG-UI event stream and maps each event type to assistant-ui state.

Feature support

Related