A2UI Quickstart: Run the Restaurant Finder Demo

A2UI’s restaurant finder demo is the fastest way to experience agent-generated UI end-to-end. In a single yarn demo:restaurant command you’ll have a Gemini-powered Python agent streaming A2UI JSON messages into a Lit web renderer in your browser — no prior knowledge of the protocol required. This guide walks through every step and explains what’s happening at each stage.

What You’ll Build

By the end of this quickstart you’ll have:

A running Lit web app with the A2UI renderer wired up and ready.
A live Gemini ADK agent that generates dynamic reservation UIs on demand.
An interactive restaurant finder that demonstrates form generation, time selection, and confirmation flows — all driven by A2UI JSON messages.
A clear mental model of how A2UI messages flow from agent to browser.

Prerequisites

This demo runs an A2A agent that calls the Gemini API using your API key. Always review agent code before running it in production environments. The agent source is at samples/agent/adk/restaurant_finder/.

Make sure you have the following installed before proceeding:

Requirement	Version	Notes
Node.js	18 or later	Must have Corepack available
uv	Latest	Python package manager used to run the agent backend
Gemini API key	—	Free key from Google AI Studio

Step-by-Step Installation

Clone the Repository

git clone https://github.com/a2ui-project/a2ui.git
cd a2ui

Set Your Gemini API Key

Export your key as an environment variable. The Python agent reads it at startup:

export GEMINI_API_KEY="your_gemini_api_key_here"

To verify the key is set correctly:

echo $GEMINI_API_KEY

Navigate to the Lit Client Directory

The demo launcher lives in the Lit client samples directory:

cd samples/client/lit

Enable Corepack and Install Dependencies

A2UI uses Corepack to pin Yarn to the correct version per workspace. Enable it before running yarn install:

corepack enable
yarn install

macOS Homebrew users: If you previously installed yarn or pnpm via Homebrew, unlink them first so Corepack can manage versions per-project:

brew unlink yarn pnpm
brew install corepack
corepack enable

Corepack and Yarn workspaces are only required within the A2UI repository itself. For your own projects outside this repository, use any package manager you prefer (npm, pnpm, etc.).

Launch the Demo

A single command builds the renderer, starts the Python agent, and opens your browser:

yarn demo:restaurant

Internally, this command:

Builds the A2UI Lit renderer
Starts the A2A restaurant finder agent (Python + uv)
Launches the Vite development server
Opens your browser at http://localhost:5173

If you see ERR_CONNECTION_REFUSED when the browser first opens, don’t panic — this is a known race condition (#587). The web app starts faster than the Python backend. Wait a few seconds and refresh the page.

Try the Demo

In the web app, type any of these prompts to see A2UI in action:

“Book a table for 2” — the agent generates a reservation form with date picker, guest count, and a confirm button.
“Find Italian restaurants near me” — watch dynamic search results populate as cards.
“What are your hours?” — observe how the same agent produces a completely different UI layout for a different intent.

What’s Happening Under the Hood

When you send a message in the web app, the following pipeline runs:

┌─────────────┐         ┌──────────────┐         ┌────────────────┐
│   You Type  │────────>│ A2A Agent    │────────>│  Gemini API    │
│  a Message  │         │  (Python)    │         │  (LLM)         │
└─────────────┘         └──────────────┘         └────────────────┘
                               │                         │
                               │   Generates A2UI JSON   │
                               │<────────────────────────┘
                               │
                               │  Streams JSONL messages
                               v
                        ┌──────────────┐
                        │   Web App    │
                        │ (A2UI Lit    │
                        │  Renderer)   │
                        └──────────────┘
                               │
                               │  Renders native components
                               v
                        ┌──────────────┐
                        │   Your UI    │
                        └──────────────┘

You send a message in the browser.
The A2A agent (Python) receives it and forwards the conversation to Gemini.
Gemini generates A2UI JSON messages describing the UI to render.
The A2A agent streams those messages back to the browser as JSONL.
The A2UI Lit renderer parses each message and instantiates native web components.
You see the UI appear progressively as messages arrive.

Anatomy of the A2UI Messages

Here’s a representative sample of what the agent sends. Two version tabs are shown — the demo uses v0.9:

v0.9 (Stable)
v0.8 (Legacy)

1. Create the surface and declare the catalog:

{
  "version": "v0.9.1",
  "createSurface": {
    "surfaceId": "main",
    "catalogId": "https://a2ui.org/specification/v0_9_1/catalogs/basic/catalog.json"
  }
}

2. Define the UI components (streamed as a flat list):

{
  "version": "v0.9.1",
  "updateComponents": {
    "surfaceId": "main",
    "components": [
      { "id": "header",      "component": "Text",          "text": "Book Your Table", "variant": "h1" },
      { "id": "date-picker", "component": "DateTimeInput", "label": "Select Date",
        "value": { "path": "/reservation/date" }, "enableDate": true },
      { "id": "submit-text", "component": "Text",          "text": "Confirm Reservation" },
      { "id": "submit-btn",  "component": "Button",        "child": "submit-text",
        "variant": "primary", "action": { "event": { "name": "confirm_booking" } } }
    ]
  }
}

3. Populate the data model:

{
  "version": "v0.9.1",
  "updateDataModel": {
    "surfaceId": "main",
    "path": "/reservation",
    "value": { "date": "2025-12-15", "time": "19:00", "guests": 2 }
  }
}

Note: createSurface replaces the old beginRendering. Components use a flat "component": "Text" format instead of nested objects. All messages include a version field.

1. Define UI structure:

{
  "surfaceUpdate": {
    "surfaceId": "main",
    "components": [
      { "id": "header",      "component": { "Text": { "text": { "literalString": "Book Your Table" }, "usageHint": "h1" } } },
      { "id": "date-picker", "component": { "DateTimeInput": { "label": { "literalString": "Select Date" },
          "value": { "path": "/reservation/date" }, "enableDate": true } } },
      { "id": "submit-text", "component": { "Text": { "text": { "literalString": "Confirm Reservation" } } } },
      { "id": "submit-btn",  "component": { "Button": { "child": "submit-text",
          "action": { "name": "confirm_booking" } } } }
    ]
  }
}

2. Populate data:

{
  "dataModelUpdate": {
    "surfaceId": "main",
    "contents": [
      { "key": "reservation", "valueMap": [
        { "key": "date",   "valueString": "2025-12-15" },
        { "key": "time",   "valueString": "19:00" },
        { "key": "guests", "valueInt": 2 }
      ]}
    ]
  }
}

3. Signal render:

{ "beginRendering": { "surfaceId": "main", "root": "header" } }

Notice how readable and regular the JSON is. LLMs generate this format naturally as structured output, and it’s safe to transmit and render because no code ever executes on the client.

Manual Two-Terminal Approach

If you prefer to run the agent and client in separate terminals (useful for debugging or inspecting agent output directly): Terminal 1 — Start the agent:

cd samples/agent/adk/restaurant_finder
uv run .

Terminal 2 — Start the client:

cd samples/client/lit/shell
yarn dev

Open http://localhost:5173 in your browser once both processes are running.

Exploring Other Demos

Other Framework Renderers

The repository ships client samples for additional frameworks alongside Lit:

Angular: samples/client/angular
React: samples/client/react

Other Ways to Get Started

If the restaurant finder demo isn’t the right starting point for your use case, A2UI offers three more entry points:

AG-UI / CopilotKit

Use CopilotKit to connect any agent framework (ADK, LangGraph, CrewAI, Mastra) to A2UI over AG-UI. Start with npx copilotkit@latest init.

A2UI Composer

Generate A2UI JSON from a visual editor and paste it directly into any agent prompt. No install required — live in your browser.

A2UI Theater

Step through pre-built A2UI streaming scenarios across Lit, React, and Angular renderers. No install required.

Widget Builder

Interactively build individual A2UI widgets and export the JSON for use in your agent prompts.

Troubleshooting

Port 5173 is already in use

The Vite dev server automatically tries the next available port. Check the terminal output for the actual URL after startup.

API key errors

Verify the key is exported: echo $GEMINI_API_KEY
Confirm it’s a valid Gemini key from Google AI Studio
Re-export if necessary: export GEMINI_API_KEY="your_key"

uv: command not found

Install uv and verify the installation:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version

Then confirm Python 3.10+ is available:

python3 --version

ERR_CONNECTION_REFUSED on startup

This is a known race condition (#587). The browser opens before the Python agent is fully ready. Wait a few seconds and refresh the page.

Still having issues?

Check GitHub Issues for known problems.
Review samples/client/lit/README.md for renderer-specific notes.
Join the community discussions on GitHub.

Where to Look in the Code

What	Path
Python A2A agent	`samples/agent/adk/restaurant_finder/`
Lit web client	`samples/client/lit/`
A2UI Lit renderer	`renderers/lit/`
Framework-agnostic core	`renderers/web_core/`

What’s Next?

Core Concepts

Understand surfaces, components, data binding, and catalogs — the four building blocks of every A2UI application.

Set Up Your Own Client

Integrate the A2UI renderer into your own web or mobile application.

Build an Agent

Create an agent that generates A2UI responses using your LLM and framework of choice.

Message Reference

Dive into the full technical specification for all A2UI message types.

Get Started

Client Integration

Agent Development

Building Renderers

Ecosystem

A2UI Quickstart: Run the Restaurant Finder Demo

What You’ll Build

Prerequisites

Step-by-Step Installation

What’s Happening Under the Hood

Anatomy of the A2UI Messages

Manual Two-Terminal Approach

Exploring Other Demos

Other Framework Renderers

Other Ways to Get Started

AG-UI / CopilotKit

A2UI Composer

A2UI Theater

Widget Builder

Troubleshooting

Where to Look in the Code

What’s Next?

Core Concepts

Set Up Your Own Client

Build an Agent

Message Reference

Build docs developers (and LLMs) love

Get Started

Client Integration

Agent Development

Building Renderers

Ecosystem

Documentation Index

​What You’ll Build

​Prerequisites

​Step-by-Step Installation

​What’s Happening Under the Hood

​Anatomy of the A2UI Messages

​Manual Two-Terminal Approach

​Exploring Other Demos

​Other Framework Renderers

​Other Ways to Get Started

AG-UI / CopilotKit

A2UI Composer

A2UI Theater

Widget Builder

​Troubleshooting

​Where to Look in the Code

​What’s Next?

Core Concepts

Set Up Your Own Client

Build an Agent

Message Reference

Build docs developers (and LLMs) love

What You’ll Build

Prerequisites

Step-by-Step Installation

What’s Happening Under the Hood

Anatomy of the A2UI Messages

Manual Two-Terminal Approach

Exploring Other Demos

Other Framework Renderers

Other Ways to Get Started

Troubleshooting

Where to Look in the Code

What’s Next?