<AgentInterface> props

AgentInterface from @openuidev/react-ui is the only chat component you mount. It owns the layout: sidebar, thread list, composer, routing, and the workspace rail. You configure all of it through AgentInterfaceProps. This page lists every prop, grouped by what it controls.

The only required prop is llm. Everything else is optional and falls back to a sensible default.

At a glance

The rest of this page explains each group.

Adapters

These two props connect AgentInterface to your backend. They are independent channels: llm produces replies, storage persists threads and artifacts.

llm is a ChatLLM, usually built with fetchLLM(). fetchLLM() POSTs { threadId, messages } to your route and parses the streamed response. See Conversations for the model, and the Adapters & formats reference for the full ChatLLM / fetchLLM() surface and the stream adapters that parse each provider's stream.

storage is a ChatStorage: { thread: ThreadStorage; artifact?: ArtifactStorage }. Omit it and conversations live only in memory: a page refresh clears everything. Build one with restStorage(), or implement the interfaces yourself. The full adapter interfaces (ChatLLM, ChatStorage, ThreadStorage, ArtifactStorage, fetchLLM, restStorage) are in the Adapters & formats reference.

Rendering

These props control how the assistant's output renders: artifacts such as dashboards and apps, and the message body.

artifactRenderers

Each entry is built with defineArtifactRenderer and links a tool name (or names) to a preview (inline in the message) and an actual (full view in the workspace panel or a full-page artifact view). The registry indexes by both toolName and type. See the defineArtifactRenderer reference.

import { AgentInterface, defineArtifactRenderer } from "@openuidev/react-ui";

const codeArtifact = defineArtifactRenderer({
  type: "code_artifact",
  toolName: "create_code_artifact",
  parser: (raw, ctx) => /* ... */ null,
  preview: (props, controls) => /* ... */ null,
  actual: (props, controls) => /* ... */ null,
});

<AgentInterface llm={llm} artifactRenderers={[codeArtifact]} />;

artifactCategories

Categories group artifacts in the artifact browser. They do not depend on whether an artifact is static or live. Each is { name: string; filter: { type: string[] } }. Without categories, the sidebar shows a single "Artifacts" item; with them, one item per category.

<AgentInterface
  llm={llm}
  storage={storage}
  artifactCategories={[
    { name: "Code", filter: { type: ["code_artifact"] } },
    { name: "Dashboards", filter: { type: ["dashboard"] } },
  ]}
/>

componentLibrary

Pass a library (e.g. openuiLibrary from @openuidev/react-ui/genui-lib) to enable Generative UI: the LLM renders rich, interactive components inline in chat messages, beyond markdown. This is distinct from artifacts (durable outputs in panels and pages). See Generative UI.

import { AgentInterface } from "@openuidev/react-ui";
import { openuiLibrary } from "@openuidev/react-ui/genui-lib";

<AgentInterface llm={llm} componentLibrary={openuiLibrary} />;

onAction

AgentInterface handles two actions of Generative UI components itself: @ToAssistant sends a new user message and @OpenUrl opens the link in a new tab. Those never reach onAction. onAction receives the other actions, such as the custom actions your componentLibrary defines.

<AgentInterface
  llm={llm}
  componentLibrary={library}
  onAction={(event) => {
    if (event.type === "CopyToClipboard") {
      void navigator.clipboard.writeText(String(event.params.text));
    }
  }}
/>

onAction is only called for messages that AgentInterface renders from componentLibrary. When you pass components.AssistantMessage, it is not called. Pass onAction to the Renderer in your component instead.

components

Override the message components directly: { AssistantMessage?, ToolCallTimeline?, UserMessage? }. Message rendering precedence is components > componentLibrary > built-in default, so an explicit components entry always wins. See Message rendering.

Theme

Set disableThemeProvider to true when AgentInterface is mounted inside an app that already wraps it in a compatible theme provider, to avoid nesting two.

Branding

These feed the default SidebarHeader and MobileHeader. To go further, replace those slots. See Sidebar.

Starters

Conversation starters are the suggested prompts shown on the welcome screen and in the composer.

Each starter is { displayText: string; prompt: string; icon?: ReactNode }. displayText is the label on the suggestion chip and prompt is the message sent when it is clicked. These props set the defaults for the Welcome and Composer slots; either slot can also take its own starters / starterVariant. See Welcome & starters.

Routing

AgentInterface has a built-in router. undefined is the thread view; non-undefined paths select Routes and the artifact browser.

Controlled mode is chosen by the presence of onNavigate, not by path !== undefined, because undefined is a valid path (the thread view). In controlled mode, drive path from your own router and update it inside onNavigate. In uncontrolled mode, set an initial route with defaultPath and let the component manage navigation internally.

Controlled consumers must round-trip the reserved artifact-browser paths (artifacts/{category} and artifacts/{category}/{id}), which are matched before your own AgentInterface.Route entries. Read the current route and navigate from anywhere inside the component with the useNav() hook (from @openuidev/react-ui).

// Uncontrolled: open on a specific route at mount.
<AgentInterface llm={llm} defaultPath="settings" />;

// Controlled: drive the route from your own state/router.
<AgentInterface llm={llm} path={path} onNavigate={setPath} />;

Scrolling

Children

children is where composition happens. Pass the compound statics on AgentInterface: slots (AgentInterface.Sidebar, .Welcome, .Composer, .Workspace, and so on), primitives (AgentInterface.SidebarItem, .ThreadList, .Messages, and so on), and AgentInterface.Route for multi-page content. Slots not provided fall back to their built-in defaults. See the Components reference.

<AgentInterface llm={llm}>
  <AgentInterface.Welcome
    title="What can I help with?"
    description="Ask about your data or build a dashboard."
  />
  <AgentInterface.Route path="settings">
    <SettingsPanel />
  </AgentInterface.Route>
</AgentInterface>

Related references

• Adapters & formats: ChatLLM, ChatStorage, ThreadStorage, ArtifactStorage, fetchLLM, restStorage, the stream adapters, and the message formats used to build llm and storage.
• defineArtifactRenderer: the shape of each artifactRenderers entry.
• Hooks: useNav, useThread, useArtifactStorage, and the rest.
• Components: the slots and primitives you pass as children.