How A2UI Lets AI Agents Speak UI Language for Safe, Dynamic Interfaces

Background and Challenges

Traditional AI agents rely on text or voice, which works for simple queries but becomes inefficient for complex enterprise tasks that require multiple parameters (e.g., restaurant reservation). Re‑entering the dialogue for each parameter leads to long, error‑prone interactions. The core problem is enabling an agent to describe a UI directly instead of conducting a long conversation.

A2UI Protocol Overview

A2UI (Agent‑to‑User Interface) is a declarative, safety‑first protocol that lets an AI agent describe UI layout and components using a flat JSON list. The agent sends a {"surfaceUpdate":{...}} message containing component IDs, types (e.g., Text, DateTimeInput, Button) and data bindings. The front‑end renders the UI from this blueprint using a pre‑approved component catalog, preventing execution of arbitrary code.

{
  "surfaceUpdate": {
    "surfaceId": "main",
    "components": [
      {"id": "header", "component": {"Text": {"text": {"literalString": "预订餐厅桌位"}, "usageHint": "h1"}}},
      {"id": "date_input", "component": {"DateTimeInput": {"label": {"literalString": "选择日期和时间"}, "value": {"path": "/reservation/datetime"}, "enableDate": true, "enableTime": true}}},
      {"id": "confirm_btn", "component": {"Button": {"child": "confirm_text", "action": {"name": "confirm_reservation"}, "primary": true}}},
      {"id": "confirm_text", "component": {"Text": {"text": {"literalString": "确认预订"}}}}
    ]
  }
}

Core Design Principles

Safe declarative design : Only data, never executable code, is transmitted.

Component catalog : All renderable UI elements must be registered in a whitelist, preventing XSS or code‑injection attacks.

LLM‑friendly flat JSON : A flat list enables large language models to generate UI incrementally and stream updates.

Cross‑platform portability : The same JSON can be rendered as native components on Web, Flutter, iOS, etc.

Data binding : UI fields bind to a dataModel so that updates can be sent separately without re‑sending the whole UI tree.

Workflow Example: Restaurant Reservation

A user asks the agent to book a table for two. Instead of a multi‑turn text dialogue, the agent emits a surfaceUpdate describing a form with a title, a date‑time picker, and a confirm button. The front‑end renders the form immediately.

When the user fills the form and clicks confirm, the front‑end sends a userAction message back to the agent:

{
  "userAction": {
    "name": "confirm",
    "surfaceId": "main",
    "context": {"details": {"datetime": "2025-12-16T19:00:00Z"}}
  }
}

The agent processes the action, performs the reservation, and can optionally send a success UI or request additional information, all using the same A2UI format.

Relation to AG‑UI and CopilotKit

AG‑UI (Agent‑User Interaction Protocol) defines the bidirectional event stream that transports messages such as surfaceUpdate, beginRendering, and userAction. A2UI defines the payload (the UI description) while AG‑UI defines how that payload is reliably streamed. CopilotKit implements AG‑UI and provides a ready‑made renderer for A2UI JSON, as well as an A2UI Composer tool that visually builds UI and outputs the corresponding JSON.

Protocol Stack and Future Outlook

A2UI, AG‑UI, MCP, and A2A form a layered stack for enterprise‑grade AI agents: MCP fetches data, A2A coordinates external agents, AG‑UI synchronises state, and A2UI renders the final interactive UI. The ecosystem is still early (v0.8 preview) but promises to make AI agents capable of “expressing UI” rather than just “talking”.