## Installation [#installation]
### CDN (via `react-lang`) [#cdn-via-react-lang]
If your app uses [`@openuidev/react-lang`](/docs/api-reference/react-lang), the widget shows up automatically in development.
### Package Installation [#package-installation]
Install the package and render `
The backend can route model requests through the [Gateway](/docs/gateway) to correct invalid OpenUI Lang and fall back to another provider when a model provider is unavailable.
## Set up the backend [#set-up-the-backend]
## 1. Create a component library [#1-create-a-component-library]
Create a library containing the components the model can use:
```tsx title="src/lib/openui.tsx"
import { createLibrary } from "@openuidev/react-lang";
import { Chart, Metric, Stack } from "./components";
export const library = createLibrary({
root: "Stack",
components: [Stack, Metric, Chart],
});
```
Learn more about defining components in the [OpenUI Lang documentation](/docs/openui-lang/defining-components).
## 2. Export the library specification [#2-export-the-library-specification]
Use the OpenUI CLI to serialize the component library for your server:
```bash
npx @openuidev/cli@latest generate src/lib/openui.tsx --spec --out src/lib/openui.spec.json
```
The generated specification describes the available components and their properties. Regenerate it whenever the component library changes.
## 3. Create an inference API key [#3-create-an-inference-api-key]
Create an inference key in the [Thesys Console](https://console.thesys.dev/keys), then add it to your server environment:
```bash
THESYS_API_KEY=sk-th-your-key-here
```
Keep this key on the server and never expose it to browser code.
## 4. Choose a generation endpoint [#4-choose-a-generation-endpoint]
Both endpoints accept a system prompt generated from the exported library specification.
### Generate [#generate]
The user describes what they want. Your backend sends the request to an LLM along with a system prompt that includes your component library and tool descriptions. The LLM responds with openui-lang code, a compact declarative format that describes the UI layout, data sources, and interactions.
### Execute [#execute]
The Renderer parses the generated code. When it encounters a `Query("list_tickets")`, the runtime calls your tool directly, no LLM roundtrip. When the user clicks a button that triggers `@Run(createResult)`, the runtime executes the mutation against your tool. When a `$variable` changes from a dropdown, all dependent queries re-fetch automatically.
The LLM generated the wiring. The runtime executes it.
1. **System prompt includes OpenUI Lang spec**: Your backend appends the generated component library prompt alongside your system prompt, instructing the LLM to respond in OpenUI Lang instead of plain text or JSON.
2. **LLM generates OpenUI Lang**: Instead of returning markdown, the model outputs a compact, line-oriented syntax (e.g., `root = Stack([chart])`) constrained to your component library.
3. **Streaming render**: On the client, the `
OpenUI Lang connects to your backend through **tools**. A tool is any function your server
exposes (a database query, an API call, a calculation). The LLM generates `Query` and `Mutation`
statements that call these tools. The runtime executes them directly and feeds the results into your UI.
## Reading data with Query [#reading-data-with-query]
```text
data = Query("list_tickets", {}, {rows: []})
```
What each argument means:
1. `"list_tickets"` - the tool name (matches what your server exposes)
2. `{}` - arguments to pass to the tool
3. `{rows: []}` - default value (what renders before the tool responds)
The default value is important - it lets the UI render immediately while data loads.
## Using Query results [#using-query-results]
Query results are just data. Access fields with dot notation:
```text
tbl = Table([Col("Title", data.rows.title), Col("Status", data.rows.status)])
chart = LineChart(data.rows.day, [Series("Views", data.rows.views)])
```
`data.rows.title` extracts the `title` field from every row - like a column pluck.
### Reactive queries [#reactive-queries]
Pass a `$variable` in the query args - the query re-runs when the variable changes:
```text
$days = "7"
data = Query("analytics", {days: $days}, {rows: []})
filter = Select("days", $days, [SelectItem("7", "7 days"), SelectItem("30", "30 days")])
```
User picks "30" → `$days` updates → Query re-fetches with `{days: "30"}` → chart updates.
### Auto-refresh [#auto-refresh]
Add a fourth argument for periodic refresh (in seconds):
```text
health = Query("get_server_health", {}, {cpu: 0, memory: 0}, 30)
```
This re-fetches every 30 seconds - great for monitoring dashboards.
## Writing data with Mutation [#writing-data-with-mutation]
```text
createResult = Mutation("create_ticket", {title: $title, priority: $priority})
```
Mutations are NOT executed on page load. They only run when triggered by `@Run`:
```text
submitBtn = Button("Create", Action([@Run(createResult), @Run(tickets), @Reset($title)]))
```
This button does three things in order:
1. `@Run(createResult)` - executes the mutation (creates the ticket)
2. `@Run(tickets)` - re-fetches the tickets query (refreshes the table)
3. `@Reset($title)` - clears the form
### Error handling [#error-handling]
Check `result.status` for mutation feedback:
```text
createResult.status == "error" ? Callout("error", "Failed", createResult.error) : null
createResult.status == "success" ? Callout("success", "Created", "Ticket added.") : null
```
## How tools connect to the runtime [#how-tools-connect-to-the-runtime]
The Renderer accepts a `toolProvider` prop that handles tool execution. Pass a function map or an [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) client:
```tsx
// Function map
{recipe.imageUrl?.startsWith("https://") && (
// eslint-disable-next-line @next/next/no-img-element
(event.currentTarget.hidden = true)}
style={{ display: "block", width: "100%", height: "100%", objectFit: "cover" }}
/>
)}
{recipe.time}
Serves {recipe.servings}
{recipe.title}
Ingredients
-
{recipe.ingredients.map((ingredient) => (
- {ingredient} ))}
When a `$variable` changes:
1. All inputs bound to it update their display
2. All `Query` calls that reference it in their args re-fetch
3. All expressions that reference it re-evaluate
4. The UI re-renders with new values
No event listeners. No useEffect. No wiring. Just declare and reference.
# Reliability
> Build reliable LLM-generated interfaces by measuring, reducing, and correcting generation errors.
Source: https://www.openui.com/docs/openui-lang/reliability
Generative UI turns LLM output directly into interfaces that users see and interact with. The model receives a description of the available components and their properties, then generates an interface that follows that contract. Most generations follow it correctly, but an LLM can occasionally invent a component, use an unsupported value, leave a reference unresolved, or stop before completing the interface.
In our [**Reliability benchmark**](/blog/generative-ui-benchmark), every tested format, including OpenUI, A2UI, and json-render, produced incomplete generations. OpenUI completed 92.9% of the evaluated tasks and produced only 2 blank screens across 1,104 runs, but it was not error-free. Even its strongest model pairing reached 99.5%, not 100%.
## Improving reliability [#improving-reliability]
There are four main ways to improve the reliability of LLM-generated interfaces:
* **Simplify the component schema.** Use distinct component names, clear descriptions, focused properties, and unambiguous enum values. Remove overlapping components and group related ones with `componentGroups`. See [Defining Components](/docs/openui-lang/defining-components).
* **Refine the system prompt.** Add targeted rules for recurring errors and provide valid examples for combinations the model finds difficult. In our benchmark, a single rule improved one model's completion rate by 13 percentage points, while an incorrect example caused double-digit regressions. See [System Prompts](/docs/openui-lang/system-prompts).
* **Evaluate model selection.** Test models using your own component library and representative prompts. Run each prompt multiple times and compare reliability alongside latency and cost.
* **Validate and correct generated output.** We recommend [Gateway](/docs/gateway) for correction during streaming, provider fallbacks, and automatic Reliability Monitoring. If you keep your existing inference setup, use [Autofix](/docs/autofix) to fix invalid generations.
Measure reliability before and after making these changes so you can identify the right intervention and verify that it worked.
## Measure reliability [#measure-reliability]
LLM generations are nondeterministic. The same model can produce different output for the same prompt, and an interface that rendered correctly once may contain errors on another attempt. Reliability therefore needs to be measured across representative prompts and repeated generations.
### During development [#during-development]
OpenUI DevTools shows the errors captured while OpenUI parses and renders the generated interface. Each entry includes an error summary and additional details, such as the error code, affected component, or statement when available.
This helps identify failures that might otherwise be missed when the rest of the interface still renders. Test representative prompts during development and run important prompts multiple times.
Use these findings to prioritize improvements to your component library, system prompt, and model selection.
## Accessing conversations [#accessing-conversations]
To build your own thread switcher or history view, read the data with hooks instead of touching storage. `useThread` selects from the current thread; `useThreadList` selects from all threads.
```tsx
import { useThread, useThreadList } from "@openuidev/react-ui";
function ChatCount() {
const count = useThreadList((s) => s.threads.length);
return 
## A custom tool timeline [#a-custom-tool-timeline]
`ToolCallTimeline` mounts as soon as the first tool activity appears, before the answer. It receives live updates for the whole turn and replaces the built-in timeline. It remains available after the turn finishes.
The exported `ToolCallTimelineComponent` type defines its props:
| Prop | Type | Meaning |
| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------ |
| `activities` | `ToolActivity[]` | The turn's tool calls paired with their available results and current statuses. |
| `steps` | `TimelineStep[]` | Ordered rows: `{ type: "text", id, text }` or `{ type: "activity", activity }`. |
| `isLast` | `boolean` | Whether this turn is currently live. It is `false` for completed turns, including the most recent one. |
| `awaitingResponse` | `boolean` | Whether the turn is live and its answer has not started, includes the delay after tool results arrive. |
This example starts collapsed and updates its tool count as activities arrive:
```tsx
import {
AgentInterface,
MarkDownRenderer,
TimelineEntry,
type ToolCallTimelineComponent,
} from "@openuidev/react-ui";
const ResearchSteps: ToolCallTimelineComponent = ({ activities, steps, isLast }) => (
## Wire items to pages [#wire-items-to-pages]
A navigating item only changes the route. Pair it with a `Route` to render something there.
```tsx
# Introduction
> A complete React SDK for building streaming agent interfaces with OpenUI Lang.
Source: https://www.openui.com/docs/agent/getting-started/introduction
Agent Interface is OpenUI's optional React SDK for teams that want a complete chat surface instead of integrating the renderer into assistant-ui, CopilotKit, or a custom message UI.
It provides conversation layout, threads, streaming messages, tool activity, and generated OpenUI components in one customizable interface. OpenUI Lang remains the interchange format, and you can connect Agent Interface to your existing agent backend.
## When to use Agent Interface [#when-to-use-agent-interface]
Choose Agent Interface when you want OpenUI to provide the complete agent UI shell. If an application already has a conversation framework, follow the [Build Agents guides](/docs/build-agents) to add the OpenUI Lang renderer instead.
## The integration boundary [#the-integration-boundary]
`