Overview: How A2UI Works
A2UI lets an AI agent describe an interactive UI as a stream of JSON messages that a client app renders with its own native widgets. Below you’ll find the mechanics on each side of the connection, how they fit together, and one request traced from the user’s prompt to a button tap.
Generating UI
On the server, you configure the A2UI Agent SDK with a component catalog (catalog.json) that describes the UI components and functions available to render on your client. From that catalog, the SDK’s skill generator produces an A2UI skill containing prompt instructions and grammar rules. Your agent code and LLM runtime sit outside the SDK: they take the generated A2UI skill alongside your domain tools (such as a flight search API), call the model, and pass its UI output to the SDK’s compiler. The compiler parses and validates the content against the catalog, then sends layout (updateComponents) and data (updateDataModel) messages over a transport such as AG-UI, A2A, MCP, or WebSockets.
On the client, your app hosts an A2UI Renderer, which draws the UI with native platform widgets inside a region of your screen called a surface. Controls bound to the surface’s data model update state locally as the user interacts with them, and user triggers such as button taps send action messages back to the agent.
While this page focuses on generating UI at request time, A2UI content can also be authored in advance and sent as a static payload (for example, returned from an MCP server via an agent to a client), following a traditional server-driven UI pattern.
A2UI Architecture & Pipeline Overview
catalog.json: the UI components and functions available to render on the client.
Your APIs and data, such as flight search and booking.
Turns the catalog into an A2UI skill with prompt instructions and grammar rules.
Parses model output, checks it against the catalog, and emits wire messages.
Calls your tools and the model (GenAI SDK, ADK, A2A, Anthropic, OpenAI, LangChain), then hands the model's UI output to the compiler.
updateComponents ↓ updateDataModel ↑ action The screen, navigation, and chat. Everything outside the surface is yours.
Draws the surface with native widgets. Bound values update locally; taps send action messages.
In the diagram above, purple marks your server-side agent code, blue marks your client app, and the teal dashed outlines mark the A2UI libraries on each side (the Agent SDK on the server and the Renderer on the client).
Step-by-step generation
The rest of this page traces a flight-booking request through each stage of the pipeline: defining the catalog, generating the skill, prompting the model, compiling and validating the output, rendering the surface on the client, and handling user actions.
Define the catalog
You define the components and functions your client can render in catalog.json. A travel app might pair the basic catalog with domain components such as FlightCard. Each component declares its properties with JSON Schema, so the Agent SDK can validate that the model only emits components and properties the client knows how to draw:
{ "protocolVersion": "1.0", "catalogId": "https://example.com/catalogs/travel/v1/catalog.json", "components": { "FlightCard": { "type": "object", "description": "Displays a flight segment with fare and passenger count.", "properties": { "component": {"const": "FlightCard"}, "flightNumber": { "$ref": "common_types.json#/$defs/DynamicString", "description": "IATA flight designator, such as 'LH 454'." } // ... origin, destination, price, passengers }, "required": ["component", "flightNumber", "origin", "destination", "price", "passengers"] } // ... other components and functions }}{ "catalogId": "https://example.com/catalogs/travel/v0_9/catalog.json", "components": { "FlightCard": { "type": "object", "allOf": [ {"$ref": "https://a2ui.org/specification/v0_9/common_types.json#/$defs/ComponentCommon"}, { "type": "object", "description": "Displays a flight segment with fare and passenger count.", "properties": { "component": {"const": "FlightCard"}, "flightNumber": { "$ref": "https://a2ui.org/specification/v0_9/common_types.json#/$defs/DynamicString", "description": "IATA flight designator, such as 'LH 454'." } // ... origin, destination, price, passengers }, "required": ["component", "flightNumber", "origin", "destination", "price", "passengers"] } ], "unevaluatedProperties": false } // ... other components and functions }}Generate the skill
From catalog.json, the Agent SDK’s skill generator builds an A2UI skill containing grammar rules for the chosen inference format (such as Express) together with component and function signatures derived directly from your catalog:
---name: a2uidescription: Generates interactive user interface components for user requests.---
# A2UI Express DSL Output Contract
You must output the user interface using A2UI Express.
IMPORTANT: You MUST always surround the entire A2UI Express block with the literal sentinel tags `<a2ui>` and `</a2ui>`...
## Grammar Rules
1. Component constructors can be assigned to variables or nested inline inside parent component arguments: ... Keyword arguments (`param=value`) and positional arguments with `_` placeholders are supported....6. Data bindings: prefix absolute paths in the data model with '$', e.g., $/user/firstName....
## Positional Component Signatures...• FlightCard(flightNumber, origin, destination, price, passengers) - Description: Displays a flight segment with fare and passenger count. - flightNumber: IATA flight designator, such as 'LH 454'. ...Prompt the model
The user types a request in the client app:
“Berlin to San Francisco today, and two tickets back on Oct 19.”
Your agent then:
- Calls its domain tools, for example
searchFlights(from: "BER", to: "SFO", date: "2026-10-12"), to get flights and prices. - Decides that a form with passenger counts is more useful here than a paragraph of text.
- Loads the generated A2UI skill and prompts the model with the flight data.
Compile and validate the output
The model streams its answer. Instead of writing wire JSON directly, it can use a compact inference format such as Express:
<a2ui>$/outbound/pax = 1$/outbound/price = 455$/return/pax = 2$/return/price = 970
root = Card(Column([ FlightCard(flightNumber="LH 454", origin="BER", destination="SFO", price=$/outbound/price, passengers=$/outbound/pax), FlightCard(flightNumber="UA 901", origin="SFO", destination="BER", price=$/return/price, passengers=$/return/pax), Button(Text("Confirm booking"), variant="primary", action=Event("confirm_booking", {outboundPax: $/outbound/pax, returnPax: $/return/pax}))]))</a2ui>The Agent SDK compiler processes the stream as it arrives:
- Parses incoming tokens into an intermediate representation.
- Validates that each component exists in the catalog and that its properties match the schema, reporting invalid output as soon as it appears.
- Emits the wire messages:
createSurfaceopens the surface on the client,updateComponentssends the validated component list, andupdateDataModelsends the initial data values.
Messages on the wire
The tabs below show the createSurface, updateComponents, and updateDataModel messages for this example. Component IDs are chosen by the compiler; the ones here are for readability.
Surface creation message, defined by CreateSurfaceMessage (shown separately from updateComponents and updateDataModel below to illustrate each message type; in v1.0, the compiler can also inline initial components and dataModel inside createSurface):
{ "version": "1.0", "createSurface": { "surfaceId": "flight-booking-surface", "catalogId": "https://example.com/catalogs/travel/v1/catalog.json" }}Layout message, defined by UpdateComponentsMessage:
{ "version": "1.0", "updateComponents": { "surfaceId": "flight-booking-surface", "components": [ {"id": "root", "component": "Card", "child": "layout_col"}, { "id": "layout_col", "component": "Column", "children": ["flight_outbound", "flight_return", "submit_btn"] }, { "id": "flight_outbound", "component": "FlightCard", "flightNumber": "LH 454", "origin": "BER", "destination": "SFO", "price": {"@path": "/outbound/price"}, "passengers": {"@path": "/outbound/pax"} }, { "id": "flight_return", "component": "FlightCard", "flightNumber": "UA 901", "origin": "SFO", "destination": "BER", "price": {"@path": "/return/price"}, "passengers": {"@path": "/return/pax"} }, {"id": "submit_label", "component": "Text", "text": "Confirm booking"}, { "id": "submit_btn", "component": "Button", "child": "submit_label", "variant": "primary", "action": { "event": { "name": "confirm_booking", "context": { "outboundPax": {"@path": "/outbound/pax"}, "returnPax": {"@path": "/return/pax"} } } } } ] }}Data message, defined by UpdateDataModelMessage:
{ "version": "1.0", "updateDataModel": { "surfaceId": "flight-booking-surface", "path": "/", "value": { "outbound": {"pax": 1, "price": 455}, "return": {"pax": 2, "price": 970} } }}Surface creation message, defined by CreateSurfaceMessage:
{ "version": "v0.9", "createSurface": { "surfaceId": "flight-booking-surface", "catalogId": "https://example.com/catalogs/travel/v0_9/catalog.json" }}Layout message, defined by UpdateComponentsMessage:
{ "version": "v0.9", "updateComponents": { "surfaceId": "flight-booking-surface", "components": [ {"id": "root", "component": "Card", "child": "layout_col"}, { "id": "layout_col", "component": "Column", "children": ["flight_outbound", "flight_return", "submit_btn"] }, { "id": "flight_outbound", "component": "FlightCard", "flightNumber": "LH 454", "origin": "BER", "destination": "SFO", "price": {"path": "/outbound/price"}, "passengers": {"path": "/outbound/pax"} }, { "id": "flight_return", "component": "FlightCard", "flightNumber": "UA 901", "origin": "SFO", "destination": "BER", "price": {"path": "/return/price"}, "passengers": {"path": "/return/pax"} }, {"id": "submit_label", "component": "Text", "text": "Confirm booking"}, { "id": "submit_btn", "component": "Button", "child": "submit_label", "variant": "primary", "action": { "event": { "name": "confirm_booking", "context": { "outboundPax": {"path": "/outbound/pax"}, "returnPax": {"path": "/return/pax"} } } } } ] }}Data message, defined by UpdateDataModelMessage:
{ "version": "v0.9", "updateDataModel": { "surfaceId": "flight-booking-surface", "path": "/", "value": { "outbound": {"pax": 1, "price": 455}, "return": {"pax": 2, "price": 970} } }}Render on the client
The client receives createSurface, updateComponents, and updateDataModel over its transport (for example AG-UI, A2A, MCP, or a WebSocket), and the A2UI Renderer:
- Creates the surface identified by
surfaceIdand stores the initial values in its data model. - Resolves the flat component list and data model into a hierarchical node layer starting at
root, following eachchildandchildrenID and binding path references (such as/outbound/pax) to their values in the data model. - Builds the native widgets from that node tree and subscribes each widget to updates on its bound properties.
At this point, the client’s node layer joins the component hierarchy with the resolved values from the data model. Card (root) wraps Column (layout_col), which contains the two FlightCard nodes with their bound prices and passenger counts alongside Button (submit_btn) and its Text label:
Surface ("flight-booking-surface")└── Card ("root") └── Column ("layout_col") ├── FlightCard ("flight_outbound") │ flightNumber: "LH 454" │ origin: "BER" │ destination: "SFO" │ price: 455 ← /outbound/price │ passengers: 1 ← /outbound/pax ├── FlightCard ("flight_return") │ flightNumber: "UA 901" │ origin: "SFO" │ destination: "BER" │ price: 970 ← /return/price │ passengers: 2 ← /return/pax └── Button ("submit_btn") │ variant: "primary" │ action: event "confirm_booking" │ outboundPax: 1 ← /outbound/pax │ returnPax: 2 ← /return/pax └── Text ("submit_label") text: "Confirm booking"Handle user actions
Once the surface is rendered, the renderer handles local state edits on the client and sends explicit user triggers back to the agent:
- When the user taps
+on the outboundFlightCardto raise the passenger count to2,FlightCardwrites2directly to/outbound/paxin the surface’s data model. Every node bound to/outbound/paxupdates in place, and nothing is sent to the agent. - When the user taps Confirm booking, the renderer triggers the
Buttonnode’s action, resolves itscontextpaths against the current data model, and sends anactionmessage to the agent.
The action message for this example, after the user raised the outbound count to 2:
Defined by renderer_to_agent.json:
{ "version": "1.0", "action": { "name": "confirm_booking", "surfaceId": "flight-booking-surface", "sourceComponentId": "submit_btn", "timestamp": "2026-10-12T08:30:00Z", "context": {"outboundPax": 2, "returnPax": 2} }}Defined by client_to_server.json:
{ "version": "v0.9", "action": { "name": "confirm_booking", "surfaceId": "flight-booking-surface", "sourceComponentId": "submit_btn", "timestamp": "2026-10-12T08:30:00Z", "context": {"outboundPax": 2, "returnPax": 2} }}