A2UI — Agent to UI

A2UI lets an Expert describe an interface as declarative JSON, which the frontend renders as native React components inline in the conversation — no iframe, no HTML strings, so it matches the product’s own design system exactly. It ships with the profy-visualize plugin under the tool name render_ui. It runs in parallel with visualize (free-form HTML / Canvas / WebGL): use A2UI for “data + layout”, use visualize for custom rendering logic.

Current boundary: A2UI is a display surface, not an interaction loop. A button click dispatches a profy:a2ui-action window event, but nothing in the codebase listens for it — the click never reaches the Expert and never triggers another turn.So: using A2UI to present (comparison tables, status panels, result summaries) is reliable; using it as a “click to continue” confirmation mechanism is not. When you need confirmation, have the Expert ask in text or use the human-in-the-loop path.

Wire protocol

render_ui takes a component array and returns an a2ui payload; the frontend StageGroup detects that field and renders it through A2uiSurfaceCard.

{
  "a2ui": {
    "messages": [
      {
        "version": "0.9.1",
        "type": "createSurface",
        "surfaceId": "<uuid4>",
        "components": [ /* component tree */ ]
      }
    ],
    "surfaceId": "<uuid4>"
  },
  "status": "rendered"
}

Field	Meaning
`version`	Protocol version, currently pinned at 0.9.1
`type`	`createSurface` (initialise) or `updateSurface` (replace the whole tree)
`surfaceId`	Auto-generated uuid4 when omitted; also used as the card’s title text
`messages`	With multiple messages only the last one takes effect (last-write-wins, v1 semantics)

The shape of a component node

This is the easiest thing to get wrong — properties must live under props, not flattened onto the node:

✓ Correct
{
  "type": "Button",
  "props": { "label": "Upgrade plan", "action": "upgrade", "variant": "secondary" }
}

✗ Wrong (flattened properties)
{ "type": "Button", "label": "Upgrade plan", "action": "upgrade" }
  → The renderer reads from props and finds no label
  → You get a button literally labelled "Button", carrying no action

A node has three optional fields: props (property map), children (child components), actions (action definitions).

The only input validation

render_ui validates exactly one thing: every component, recursively, has a type field. Missing it rejects the whole call:

{
  "error": "Invalid component structure",
  "details": ["components[0].children[1]: missing required `type` field"]
}

Beyond that, property names and types are not validated. A wrong property name raises no error — it silently renders as blank or as the default. That is the single most useful fact when debugging an A2UI surface.

Component catalog (16)

Property names below are the fields the renderer actually reads.

Layout

Component	Props read	Behaviour
`Row`	`gap`, `align`	Horizontal flex, wraps
`Column`	`gap`	Vertical flex
`Card`	`title`	Renders a header only when `title` is present; no subtitle support
`Divider`	none	A separator line; any props are ignored

gap only recognises 0 / 1 / 2 / 3 / 4 / 6 / 8 (Tailwind spacing steps); any other number falls back to 3. So gap: 16 does not produce 16px — it produces the default. align recognises center, end (or bottom) and stretch; anything else falls back to start.

Content

Component	Props read	Behaviour
`Text`	`content`, `variant`, `weight`	`variant: "heading"` renders an h3, `"caption"` renders small muted text, anything else a body paragraph
`Image`	`src`, `alt`, `width`, `height`	Renders nothing without `src`; hides itself on load error rather than showing a broken image
`Badge`	`label`, `variant`	Variants recognised: `secondary`, `destructive`, `outline`; anything else is default
`List`	`ordered`	`true` renders `<ol>`, otherwise `<ul>`; entries come from `ListItem` children
`ListItem`	`content`	A single list entry
`Table`	`headers`, `rows`	`headers` is a string array and `rows` is a 2-D string array

Text’s weight recognises bold, semibold and medium; anything else stays normal. Note there is no code variant — passing it renders body text.

Interactive

Component	Props read	Behaviour
`Button`	`label`, `action`, `variant`	Without `label` it shows the literal “Button”; without `action` the click does nothing at all

Variants recognised: secondary, destructive, outline. Both primary and ghost fall through to the default style (visually equivalent to primary). Button size is fixed at sm.

Profy business components

Component	Props read	Behaviour
`ExpertCard`	`name`, `avatar`, `description`, `rating`	`rating` renders as 5 stars (rounded, capped at 5); a failed avatar hides itself
`CreditDisplay`	`amount`, `label`	Thousands-separated number with `label` as a small suffix
`PlanBadge`	`planCode`	Displays the code text itself; colours known for `free`, `pro`, `advanced`, `flagship`, `team`, everything else outline
`StatusIndicator`	`status`, `label`	Dot colours for `active`, `success`, `warning`, `error`, `inactive`, `pending`, otherwise grey; falls back to showing the status string when `label` is absent
`PricingTable`	`plans`	Uses the union of keys across plan objects as headers and `String()`s every value into a cell

PricingTable cannot highlight a recommended tier, and it will not expand a features array into a bullet list — arrays are String()d into a,b,c on one line. For a good-looking feature comparison, hand-building a Table gives you more control.

What happens with an unknown component

When the renderer has no entry for a type, it renders a dashed box reading Unknown component: <type> and still renders that node’s children — it never crashes the surface. So a dashed box means a typo or a component that doesn’t exist (for example ProgressBar, which is not in the catalog).

Worked examples

Account status panel

render_ui(components=[
    {
        "type": "Card",
        "props": {"title": "Account overview"},
        "children": [
            {
                "type": "Row",
                "props": {"gap": 4, "align": "center"},
                "children": [
                    {"type": "CreditDisplay", "props": {"amount": 4520, "label": "credits"}},
                    {"type": "PlanBadge", "props": {"planCode": "pro"}},
                    {"type": "StatusIndicator", "props": {"status": "active", "label": "Subscription active"}},
                ],
            },
            {"type": "Divider"},
            {"type": "Text", "props": {"content": "68% of this month used", "variant": "caption"}},
        ],
    }
])

Data table

Note the shape of headers and rows — this is where people trip:

render_ui(components=[
    {
        "type": "Table",
        "props": {
            "headers": ["Model", "Billing unit", "Use case"],
            "rows": [
                ["Text model", "token_split", "Chat, writing, analysis"],
                ["Image model", "per_call", "Posters, illustrations"],
                ["Video model", "duration_second", "Clips, motion"],
            ],
        },
    }
])

List

render_ui(components=[
    {
        "type": "Card",
        "props": {"title": "Findings from this check"},
        "children": [
            {
                "type": "List",
                "props": {"ordered": True},
                "children": [
                    {"type": "ListItem", "props": {"content": "3 links point to deleted pages"}},
                    {"type": "ListItem", "props": {"content": "1 cover image has no alt text"}},
                ],
            }
        ],
    }
])

Key numbers

Item	Value
Component types	16 (4 layout + 6 content + 1 interactive + 5 business)
Protocol version	0.9.1
Usable `gap` steps	7 (0 / 1 / 2 / 3 / 4 / 6 / 8), everything else falls back to 3
Recognised button variants	3 (secondary / destructive / outline), everything else is default
Star ceiling	5 (ExpertCard ratings above 5 are capped)
Validated input rules	1 (every component needs `type`)
Messages that take effect	The last 1 (earlier ones are overwritten)

Failures and fixes

Symptom	Cause	Fix
Clicking a button does nothing	The action event currently has no listener; A2UI is a display surface	Ask in text when you need a decision
A dashed `Unknown component` box	A typo, or a component outside the catalog (e.g. `ProgressBar`)	Check against the 16 names above
The button reads literally “Button”	Properties were flattened instead of nested	Move every property into `props`
The table is empty	Wrong shape for `headers` / `rows` (objects instead of a 2-D string array)	Use `headers: string[]` and `rows: string[][]`
A badge has no text	Used `text` instead of `label`	Rename to `label`
The plan badge always shows free	Used `plan` instead of `planCode`	Rename to `planCode`
Credits render as 0	Used `balance` instead of `amount`	Rename to `amount`
Spacing doesn’t match expectations	`gap` was outside the supported steps	Use 0/1/2/3/4/6/8
The whole call returns an error	A component is missing `type`	Read the path in `details`, e.g. `components[0].children[1]`
The image slot is blank	`src` is empty, or the image failed to load and hid itself	Check the URL is reachable

The component guide shown to the model has known drift from the renderer. Several property names in the A2UI prompt (Badge’s color, Table’s columns, PlanBadge’s plan, CreditDisplay’s unit) don’t match the fields the renderer reads, and its examples flatten props. Because render_ui only validates type, this drift raises no error — it silently renders as blank or default.So when an A2UI panel looks under-filled, check the property names on this page first rather than suspecting the underlying data.

Best practices

Always nest properties under props — this is the number-one source of silent failure.
Use Card as the top-level container so related components form one visual unit.
Keep nesting under three levels; deep layouts are fragile and hard to read.
Present with it, don’t interact through it — ask in text when a decision is needed.
Go to visualize for charts, 3D and animation; A2UI has only these 16 predefined components.
Follow a surface with a sentence of summary — A2UI is additive, not a replacement for explanation.

Verified 2026-08-12. Sources: apps/web/src/lib/a2ui/{definitions.ts,renderers.tsx}, apps/web/src/components/agent/chat-area/card/A2uiSurfaceCard.tsx, packages/types/src/a2ui.ts, services/agent-runtime/src/plugins/builtin/visualize/tools/render_ui.py.

Visualize plugin

Free-form HTML / Canvas / WebGL surfaces

Plugin catalog

The full inventory of 28 built-in plugins

Get Started

Core Concepts

Guides

Platform & Account

Deep Dive

A2UI (Agent to UI)

A2UI — Agent to UI

Wire protocol

The shape of a component node

The only input validation

Component catalog (16)

Layout

Content

Interactive

Profy business components

What happens with an unknown component

Worked examples

Account status panel

Data table

List

Key numbers

Failures and fixes

Best practices

Visualize plugin

Plugin catalog

​A2UI — Agent to UI

​Wire protocol

​The shape of a component node

​The only input validation

​Component catalog (16)

​Layout

​Content

​Interactive

​Profy business components

​What happens with an unknown component

​Worked examples

​Account status panel

​Data table

​List

​Key numbers

​Failures and fixes

​Best practices

​Related

Visualize plugin

Plugin catalog

A2UI — Agent to UI

Wire protocol

The shape of a component node

The only input validation

Component catalog (16)

Layout

Content

Interactive

Profy business components

What happens with an unknown component

Worked examples

Account status panel

Data table

List

Key numbers

Failures and fixes

Best practices

Related