> ## Documentation Index
> Fetch the complete documentation index at: https://noorle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Generative UI

> Configure agents to render interactive UI components in responses.

Generative UI lets agents render rich interface components — progress bars, tables, charts, forms, and more — directly in their responses. This guide covers how to enable and configure it.

## How to Enable

<Steps>
  <Step title="Open Agent Settings">
    Navigate to **Agents** > Select your agent > **Settings**
  </Step>

  <Step title="Find Generative UI Section">
    Scroll to the **Generative UI** card
  </Step>

  <Step title="Enable and Configure">
    * Toggle **Enabled** on
    * Select a **Catalog** (Noorle Extended is recommended)
    * Optionally add **Guidance** text
    * Click **Save**
  </Step>
</Steps>

## Catalog Selection

| Catalog                       | ID                                | Components                                                                                                                                                                        |
| ----------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Noorle Extended** (default) | `a2ui.noorle.dev:catalog_1_0`     | Standard A2UI 0.9 + Noorle components (Progress, Status, CodeBlock, DataTable, Chart, Form, ApprovalForm, Accordion)                                                              |
| **Standard A2UI 0.9**         | `a2ui.dev:standard_catalog_0_9_0` | Display (Text, Image, Icon, Video, AudioPlayer), Layout (Row, Column, List, Card, Tabs, Divider, Modal), Input (Button, CheckBox, TextField, DateTimeInput, ChoicePicker, Slider) |

Choose **Noorle Extended** when you need data tables, charts, progress indicators, or approval forms. Choose **Standard A2UI 0.9** for maximum compatibility with other A2UI-supporting clients.

## Custom Guidance

The **Guidance** field lets you instruct the agent on when and how to use UI components. This text is appended to the A2UI protocol instructions in the agent's system prompt.

**Example guidance:**

```
Use NoorleDataTable for any results with 3+ rows of structured data.
Use NoorleChart (type: bar) for comparisons between items.
Always show NoorleProgress for tasks that take more than a few seconds.
Use NoorleApprovalForm when the user needs to confirm a destructive action.
```

Maximum length: 2,000 characters.

## Noorle Extended Components

### NoorleProgress

Progress bar with label and percentage value. Useful for showing task completion.

### NoorleStatus

Status indicator with variants: `success`, `error`, `warning`, `info`, `loading`. Good for showing operation results at a glance.

### NoorleCodeBlock

Syntax-highlighted code display. Supports language detection.

### NoorleDataTable

Structured data table with defined columns and rows. Best for search results, lists, and tabular data.

### NoorleChart

Data visualization supporting: `line`, `bar`, `pie`, `doughnut`, `area`, `scatter`. Ideal for comparisons and trends.

### NoorleForm

Dynamic form with multiple field types. Supports status tracking through the lifecycle: `pending` → `submitted` → `success` or `error`. The agent can update the form's status and message in place after processing.

### NoorleApprovalForm

Human-in-the-loop approval component. Supports status: `pending` → `approved` or `rejected`. Use for confirming important actions before the agent proceeds.

## How the Agent Creates UI

When Generative UI is enabled, the agent receives protocol instructions in its system prompt. During a response, the agent emits JSON messages to create and update UI surfaces.

**Typical flow:**

1. Agent creates a surface with `createSurface` (includes catalog ID)
2. Agent adds components via `updateComponents` (must include a `root` component)
3. User interacts (clicks button, submits form)
4. Agent receives the action and can update components or data model
5. Agent deletes surface when done (optional)

### User Actions

When users interact with components (click a button, submit a form), the action is sent back to the agent as:

```
[User Action] name: <action_name>, surface: <surface_id>,
  component: <component_id>, context: {<resolved data>}
```

The agent can then respond accordingly — updating the UI, performing actions, or continuing the conversation.

## Data Binding

Components can reference values from a shared data model using path syntax:

```json theme={null}
{
  "component": "NoorleProgress",
  "label": {"path": "/task/name"},
  "value": {"path": "/task/progress"},
  "max": 100
}
```

The agent can then update the data model separately:

```json theme={null}
{
  "updateDataModel": {
    "surfaceId": "task-abc",
    "path": "/task/progress",
    "op": "replace",
    "value": 75
  }
}
```

This causes the progress bar to update reactively without replacing the component.

## Best Practices

### Use UI for Complex Outputs

Text is fine for simple answers. Use Generative UI when the response involves structured data, status tracking, or user interaction.

### Keep Surfaces Focused

Each surface should serve one purpose. Create separate surfaces for different concerns (status display vs. action panel).

### Complete Status Cycles

For NoorleForm and NoorleApprovalForm, always update the status after processing. Never leave a form in `submitted` state — update to `success` or `error`.

### Provide Guidance

Custom guidance helps the agent make better decisions about when to use UI components vs. plain text.

## Limitations

* Generative UI requires a frontend that supports the A2UI protocol (the Noorle Console supports it)
* MCP gateway connections do not render UI components
* Components are not persisted — they exist only during the active conversation

## Next Steps

* [Generative UI Concepts](/docs/learn/concepts/generative-ui)
* [Creating Agents](/docs/run/agents/creating-an-agent)
* [System Prompts](/docs/run/agents/system-prompts)