Generative UI from ADK Agents with the A2UI Protocol: Messages and Samples
Learn how A2UI lets an agent return interactive UI as JSON, how it differs from AG-UI, and how to run the Google ADK restaurant finder sample locally.
This article is published in English.
Sources: Agent to UI Protocol (A2UI) with Agent Development Kit (ADK)
Four protocols come up repeatedly when agents are wired into real applications: MCP, A2A, A2UI and AG-UI. AG-UI links a front-end application to an agent backend, and it pairs well with Google's Agent Development Kit (ADK). The focus here is A2UI, a neighbor with a confusingly similar name, and how to drive it from an ADK agent.
What A2UI is
A2UI is a generative-UI protocol from Google. It lets AI agents produce rich, interactive interfaces that can show up on web, mobile and desktop. Say a user asks, "What are some good restaurants in New York?" The agent can do more than return a text list. It can also return a description of a UI, and a renderer on the client side turns that description into an interactive display of the restaurants.
The core concepts are documented at a2ui.org, and the essentials fit in a few paragraphs.
Four message types
Everything an agent sends is JSON, and there are only four kinds of message:
createSurfacemakes a new surface and says which component catalog it uses.updateComponentsadds or changes UI components inside a surface.updateDataModelchanges application state.deleteSurfaceremoves a surface.
Together they describe both the interface and the data behind it:
{
"version": "v0.9",
"createSurface": {
"surfaceId": "main",
"catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
}
}
{
"version": "v0.9",
"updateComponents": {
"surfaceId": "main",
"components": [...]
}
}
{
"version": "v0.9",
"updateDataModel": {
"surfaceId": "main",
"path": "/user",
"value": { "name": "Alice" }
}
}
The component catalog
A2UI ships a standard catalog, grouped by purpose:
- Layout: Row, Column and List, which arrange other components
- Display: Text, Image, Icon, Video and Divider, which present information
- Interactive: Button, TextField, CheckBox, DateTimeInput and Slider, which take input
- Container: Card, Tabs and Modal, which group content
The documentation's component reference holds the full gallery with examples.
A booking conversation, message by message
The restaurant booking example from the docs shows the lifecycle well.
First the agent creates a surface:
{
"version": "v0.9",
"createSurface": {
"surfaceId": "booking",
"catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json"
}
}
Second, it defines the structure of the UI:
{
"version": "v0.9",
"updateComponents": {
"surfaceId": "booking",
"components": [
{
"id": "root",
"component": "Column",
"children": ["header", "guests-field", "submit-btn"]
},
{
"id": "header",
"component": "Text",
"text": "Confirm Reservation",
"variant": "h1"
},
{
"id": "guests-field",
"component": "TextField",
"label": "Guests",
"value": { "path": "/reservation/guests" }
},
{
"id": "submit-btn",
"component": "Button",
"child": "submit-text",
"variant": "primary",
"action": {
"event": {
"name": "confirm",
"context": {
"details": { "path": "/reservation" }
}
}
}
}
]
}
}
Third, it fills in the data:
{
"version": "v0.9",
"updateDataModel": {
"surfaceId": "booking",
"path": "/reservation",
"value": {
"datetime": "2025-12-16T19:00:00Z",
"guests": "2"
}
}
}
Fourth, the user changes the guest count to 3, and the client updates /reservation/guests on its own. Fifth, the user presses Confirm, and the client sends an action back:
{
"version": "v0.9",
"action": {
"name": "confirm",
"surfaceId": "booking",
"context": {
"details": {
"datetime": "2025-12-16T19:00:00Z",
"guests": "3"
}
}
}
}
Sixth, the agent responds, either by updating the UI again or by closing the surface:
{
"version": "v0.9",
"deleteSurface": { "surfaceId": "booking" }
}
Transport and rendering
A2UI doesn't care how messages travel, since anything able to carry JSON works. A2A and AG-UI are supported as transports today, while REST, WebSockets and SSE are planned or proposed. The transports page of the docs lists what's current.
Once the agent has produced the JSON, a renderer converts it into native components. On the web, Lit and Angular renderers exist, and Flutter's GenUI SDK covers mobile, desktop and web. The renderers page keeps the maintained list.
A2UI and AG-UI side by side
The names are close, and the jobs are different but complementary. AG-UI is the connection between a user-facing app and the agentic backend. A2UI is a declarative spec that agents use to return UI widgets inside their responses.
Trying the samples
The A2UI repository includes ADK agent samples that can be generated and rendered locally. Clone it first:
git clone https://github.com/google/a2ui.git
cd a2ui
Set a Gemini API key:
export GEMINI_API_KEY="your_gemini_api_key_here"
Each sample has a server part (the agent) and a client part (the renderer), and both need to be running. The ADK agent samples live in the adk folder under samples/agent, and the client renderers in samples/client.
Restaurant finder
From the samples/client/lit folder, a single command launches the demo:
npm run demo:restaurant
Open http://localhost:5173/?app=restaurant and start prompting, for instance "Top 5 Chinese restaurants in New York". The agent generates the UI and the client renders it:
The logs show the raw A2UI JSON the agent sent:
[REST] LiteLLM completion() model= gemini-2.5-flash; provider = gemini
[REST] INFO:agent:Event from runner: model_version='gemini-2.5-flash' content=Content(
[REST] parts=[
[REST] Part(
[REST] text="""<a2ui-json>
[REST] [
[REST] {
[REST] "beginRendering": {
[REST] "surfaceId": "default",
[REST] "root": "root-column",
[REST] "styles": {
[REST] "primaryColor": "#FF0000",
[REST] "font": "Roboto"
[REST] }
[REST] }
[REST] },
[REST] {
[REST] "surfaceUpdate": {
[REST] "surfaceId": "default",
[REST] "components": [
[REST] {
[REST] "id": "root-column",
[REST] "component": {
[REST] "Column": {
[REST] "children": {
[REST] "explicitList": [
[REST] "title-heading",
[REST] "item-list"
[REST] ]
[REST] }
[REST] }
[REST] }
[REST] },
...
What happens inside
The agent code sits in samples/agent/adk/restaurant_finder. prompt_builder.py shows how the prompt is built so that the agent answers in A2UI. The role description begins with a firm instruction that the final output must be an A2UI JSON response:
ROLE_DESCRIPTION = (
"You are a helpful restaurant finding assistant. Your final output MUST be a a2ui"
" UI JSON response."
)
UI_DESCRIPTION = """
- If the query is for a list of restaurants, use the restaurant data you have already received from the `get_restaurants` tool to populate the `dataModelUpdate.contents` array (e.g., as a `valueMap` for the "items" key).
- If the number of restaurants is 5 or fewer, you MUST use the `SINGLE_COLUMN_LIST_EXAMPLE` template.
- If the number of restaurants is more than 5, you MUST use the `TWO_COLUMN_LIST_EXAMPLE` template.
- If the query is to book a restaurant (e.g., "USER_WANTS_TO_BOOK..."), you MUST use the `BOOKING_FORM_EXAMPLE` template.
- If the query is a booking submission (e.g., "User submitted a booking..."), you MUST use the `CONFIRMATION_EXAMPLE` template.
"""
The A2uiSchemaManager class loads component catalogs and produces system prompts that coach the model on valid A2UI JSON. Calling generate_system_prompt blends the role description of the agent with the schema and a few worked examples, which leaves the model with precise formatting guidance:
version = VERSION_0_9
restaurant_prompt = A2uiSchemaManager(
version,
catalogs=[
BasicCatalog.get_config(
version=version,
examples_path=f"examples/{version}",
)
],
schema_modifiers=[remove_strict_validation],
).generate_system_prompt(
role_description=ROLE_DESCRIPTION,
ui_description=UI_DESCRIPTION,
include_schema=True,
include_examples=True,
validate_examples=True,
)
agent.py then creates the agent with that system prompt:
return LlmAgent(
model=LiteLlm(model=LITELLM_MODEL),
name="restaurant_agent",
description="An agent that finds restaurants and helps book tables.",
instruction=instruction,
tools=[get_restaurants],
)
After the agent emits JSON, it should be validated against the A2UI schema before streaming to the client:
# --- Validation Steps ---
# Check if it validates against the A2UI_SCHEMA
# This will raise jsonschema.exceptions.ValidationError if it fails
logger.info(
"--- RestaurantAgent.stream: Validating against A2UI_SCHEMA... ---"
)
selected_catalog.validator.validate(parsed_json_data)
The ADK documentation has an A2UI integration page with more detail. On the client side, renderers/lit holds the Lit implementation that takes the generated JSON and renders it.
Tools for getting started
CopilotKit publishes an A2UI starter template, plus an A2UI Composer for experimenting with components.
Useful places to keep reading are the A2UI protocol docs and specification, the GitHub repository, Google's announcement post on agent-driven interfaces, the ADK integration page, the CopilotKit Composer and starter, and a couple of YouTube talks on agents building UI in real time.