Skip to main content
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

1

Open Agent Settings

Navigate to Agents > Select your agent > Settings
2

Find Generative UI Section

Scroll to the Generative UI card
3

Enable and Configure

  • Toggle Enabled on
  • Select a Catalog (Noorle Extended is recommended)
  • Optionally add Guidance text
  • Click Save

​
Catalog Selection

CatalogIDComponents
Noorle Extended (default)a2ui.noorle.dev:catalog_1_0Standard A2UI 0.9 + Noorle components (Progress, Status, CodeBlock, DataTable, Chart, Form, ApprovalForm, Accordion)
Standard A2UI 0.9a2ui.dev:standard_catalog_0_9_0Display (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: 
{
  "component": "NoorleProgress",
  "label": {"path": "/task/name"},
  "value": {"path": "/task/progress"},
  "max": 100
}
The agent can then update the data model separately: 
{
  "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