A2UI Protocol

Chat-in-Bio uses the A2UI (Agent-to-UI) protocol v0.8 to render rich, interactive UI components inline within chat messages — cards, buttons, forms, images, and more.

What is A2UI?

A2UI is a declarative UI protocol designed for AI agents. Instead of the LLM generating HTML or markdown, it produces structured component definitions that a client-side renderer turns into real UI.

Key properties:

• Declarative — components are data, not code. No script execution.
• Adjacency-list model — components reference children by ID, forming a tree.
• Protocol-based — server sends structured messages; any renderer can consume them.
• Streaming-friendly — components can be sent incrementally.

Message sequence

A complete A2UI surface consists of two messages:

1. surfaceUpdate

Declares the surface and its component tree:

{
  "surfaceUpdate": {
    "surfaceId": "events-list",
    "components": [
      {"id": "t1", "component": {"Text": {"text": "Upcoming Events", "variant": "h2"}}},
      {"id": "b1", "component": {"Button": {"label": "RSVP", "action": "rsvp", "context": {"event_id": "123"}}}},
      {"id": "col1", "component": {"Column": {"children": ["t1", "b1"]}}}
    ]
  }
}

2. beginRendering

Signals the client to render, specifying the root component:

{
  "beginRendering": {
    "surfaceId": "events-list",
    "root": "col1"
  }
}

Component model

Each component is a node with:

• id — unique identifier within the surface
• component — a single-key object where the key is the component type and the value contains its properties

Layout components (Column, Row, Card, List) reference children by their IDs, forming a tree from the adjacency list.

Why A2UI over raw HTML/Markdown?

Concern	Raw HTML	Markdown	A2UI
Safety	XSS risk	Limited interactivity	Safe by design — declarative only
Interactivity	Needs JS injection	None	Built-in actions (buttons, forms)
Consistency	Varies by renderer	Limited styling	Themed, consistent rendering
Streaming	Fragile partial HTML	Works	First-class incremental updates
LLM reliability	Frequent syntax errors	Good	Tools build components, not the LLM

How Chat-in-Bio uses A2UI

The LLM never generates A2UI directly. Instead:

1. The LLM decides which tools to call (intent routing)
2. Tools contain deterministic Python code that builds A2UI components
3. The SurfaceManager collects components across tool calls
4. After the agent finishes, surfaces are flushed as protocol messages

This means:

• UI is always well-formed (no parsing errors)
• Complex layouts are reliable (not dependent on LLM output quality)
• The LLM focuses on what it's good at: understanding intent