<AgentInterface> props

AgentInterface from @openuidev/react-ui is the only chat component you mount. It owns the full layout — sidebar, thread list, composer, routing, and the workspace rail — and you configure all of it through AgentInterfaceProps. This page is the complete prop reference, grouped by what each prop controls, with links to the relevant concept and how-to pages for each area.

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(), which 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 is rendered — both durable artifacts (dashboards, reports, presentations, apps) and the inline 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 Artifacts and 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 are user-defined organization for the artifact browser — they are orthogonal to 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. See Artifacts.

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

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} />;

components

Override the message components directly: { AssistantMessage?, UserMessage? }. Message rendering precedence is components > componentLibrary > built-in default — 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 meaningful 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} />;

Children

children is where composition happens. Pass the compound statics on AgentInterface — slots (AgentInterface.Sidebar, .Welcome, .Composer, .Workspace, …), primitives (AgentInterface.SidebarItem, .ThreadList, .Messages, …), 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, generate a report, 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.