A2UI — Agent to UI

A2UI lets the Agent describe UI structure through declarative JSON. The frontend renders it as native React components inline in the chat area. When users interact with components (e.g., clicking buttons), events are dispatched back to the Agent for follow-up processing.

How It Works

Basic Usage

The Agent calls the render_ui tool with a components array:

render_ui(components=[
    {
        "type": "Card",
        "title": "Current Plan",
        "children": [
            {"type": "PlanBadge", "plan": "pro"},
            {"type": "Text", "content": "Valid until 2026-08-01"},
            {"type": "Button", "label": "Upgrade Plan", "action": "upgrade", "variant": "primary"}
        ]
    }
])

The tool result contains an a2ui field. When StageGroup detects this field, it renders the A2UIRenderer component.

Component Catalog

Layout Components

Row

Arranges children horizontally.

Prop	Type	Description
`gap`	`number`	Spacing between children (px), default 8
`align`	`"start" \| "center" \| "end"`	Vertical alignment
`children`	`Component[]`	Child components

Column

Arranges children vertically.

Prop	Type	Description
`gap`	`number`	Spacing between children (px), default 8
`children`	`Component[]`	Child components

Card

Container with title and border.

Prop	Type	Description
`title`	`string?`	Card title
`subtitle`	`string?`	Subtitle
`children`	`Component[]`	Card content

Content Components

Text

Text display with Markdown support.

Prop	Type	Description
`content`	`string`	Text content (Markdown supported)
`size`	`"sm" \| "md" \| "lg"`	Font size, default `"md"`
`weight`	`"normal" \| "medium" \| "bold"`	Font weight
`color`	`"default" \| "muted" \| "success" \| "warning" \| "error"`	Semantic color

Image

Image display.

Prop	Type	Description
`src`	`string`	Image URL
`alt`	`string?`	Alt text
`width`	`number?`	Width (px)
`height`	`number?`	Height (px)

Divider

Horizontal separator.

Prop	Type	Description
`label`	`string?`	Text in the middle of the divider

Badge

Label/badge.

Prop	Type	Description
`text`	`string`	Badge text
`variant`	`"default" \| "success" \| "warning" \| "error" \| "info"`	Style variant

List

List display.

Prop	Type	Description
`items`	`string[]`	List items
`ordered`	`boolean`	Whether ordered, default `false`

Table

Table display.

Prop	Type	Description
`columns`	`{key: string, label: string}[]`	Column definitions
`rows`	`Record<string, string>[]`	Row data
`compact`	`boolean`	Compact mode, default `false`

Interactive Components

Button

Clickable button that triggers an Action callback.

Prop	Type	Description
`label`	`string`	Button text
`action`	`string`	Action identifier sent back on click
`variant`	`"primary" \| "secondary" \| "destructive" \| "ghost"`	Button style
`disabled`	`boolean`	Whether disabled
`payload`	`Record<string, any>?`	Additional data sent with the action

Profy Business Components

ExpertCard

Expert information card.

Prop	Type	Description
`identifier`	`string`	Expert identifier
`name`	`string`	Expert name
`avatar`	`string?`	Avatar URL
`description`	`string?`	Short description

CreditDisplay

Credit balance display.

Prop	Type	Description
`balance`	`number`	Current balance
`unit`	`string`	Unit text, default “credits”

PlanBadge

Subscription plan badge.

Prop	Type	Description
`plan`	`"free" \| "starter" \| "pro" \| "flagship" \| "team"`	Plan code

StatusIndicator

Status indicator.

Prop	Type	Description
`status`	`"active" \| "inactive" \| "pending" \| "error"`	Status
`label`	`string`	Status text

PricingTable

Pricing comparison table.

Prop	Type	Description
`plans`	`{name, price, features[], highlighted?}[]`	Plan list
`action`	`string?`	CTA button action

ProgressBar

Progress bar.

Prop	Type	Description
`value`	`number`	Current value (0-100)
`label`	`string?`	Progress label
`color`	`"default" \| "success" \| "warning" \| "error"`	Color

Action Handling

When a user clicks a Button with an action prop, the frontend dispatches the event to the Agent:

{
  "type": "a2ui_action",
  "action": "upgrade",
  "payload": {"plan": "pro"},
  "componentPath": "card.0.button.2"
}

The Agent reads this action in its next reasoning turn and can respond accordingly (e.g., navigate to payment, update displayed content).

Examples

Plan Comparison

render_ui(components=[
    {"type": "Text", "content": "Choose your plan", "size": "lg", "weight": "bold"},
    {
        "type": "PricingTable",
        "plans": [
            {"name": "Free", "price": "0", "features": ["100 credits/day", "Basic models"]},
            {"name": "Pro", "price": "$49/mo", "features": ["5000 credits/mo", "All models", "Priority"], "highlighted": True},
            {"name": "Flagship", "price": "$199/mo", "features": ["20000 credits/mo", "All models", "Dedicated support"]}
        ],
        "action": "select_plan"
    }
])

Status Dashboard

render_ui(components=[
    {
        "type": "Card",
        "title": "Account Overview",
        "children": [
            {
                "type": "Row",
                "gap": 16,
                "children": [
                    {"type": "CreditDisplay", "balance": 4520},
                    {"type": "PlanBadge", "plan": "pro"},
                    {"type": "StatusIndicator", "status": "active", "label": "Subscription active"}
                ]
            },
            {"type": "Divider"},
            {"type": "ProgressBar", "value": 68, "label": "Monthly usage 68%"},
            {
                "type": "Row",
                "gap": 8,
                "children": [
                    {"type": "Button", "label": "Top Up", "action": "recharge", "variant": "primary"},
                    {"type": "Button", "label": "View Details", "action": "view_detail", "variant": "ghost"}
                ]
            }
        ]
    }
])

Action Confirmation

render_ui(components=[
    {
        "type": "Card",
        "title": "Confirm Action",
        "children": [
            {"type": "Text", "content": "About to delete expert 'Financial Advisor'. This cannot be undone.", "color": "warning"},
            {
                "type": "Row",
                "gap": 8,
                "align": "end",
                "children": [
                    {"type": "Button", "label": "Cancel", "action": "cancel", "variant": "ghost"},
                    {"type": "Button", "label": "Delete", "action": "confirm_delete", "variant": "destructive", "payload": {"identifier": "financial-advisor"}}
                ]
            }
        ]
    }
])

Best Practices

Prefer A2UI over Inline Visualization when displaying structured data (tables, lists, status) — A2UI components are more consistent and performant
Keep component trees shallow — no more than 3 levels of nesting
Use snake_case for action names — e.g., confirm_delete, select_plan, making them easy for the Agent to parse
Use payload for context — Button’s payload field carries additional data the Agent needs, avoiding positional inference
Group with Cards — logically related components belong in the same Card for visual coherence
Choose Inline Visualization when you need freeform drawing/Canvas/WebGL — A2UI only supports predefined components

​A2UI — Agent to UI

​How It Works

​Basic Usage

​Component Catalog

​Layout Components

​Row

​Column

​Card

​Content Components

​Text

​Image

​Divider

​Badge

​List

​Table

​Interactive Components

​Button

​Profy Business Components

​ExpertCard

​CreditDisplay

​PlanBadge

​StatusIndicator

​PricingTable

​ProgressBar

​Action Handling

​Examples

​Plan Comparison

​Status Dashboard

​Action Confirmation

​Best Practices