Prerequisites for A2UI: Complete Setup Guide for the Framework-Agnostic UI Format

To run A2UI, you need Node.js v18+ for client-side renderers, Python 3.9+ with the uv package manager for agent backends, and a Gemini API key for LLM-driven UI generation.

A2UI is a framework-agnostic, declarative UI format that enables LLM-driven agents to generate rich user interfaces. Because the project spans both agent-side Python code and client-side TypeScript renderers, installing the google/A2UI repository requires satisfying runtime dependencies for both halves of the pipeline.

Core Runtime Requirements

A2UI operates on a split architecture: agent generation (backend) produces UI JSON via LLM prompts, while client renderers (frontend) transform that JSON into native components. Each side carries distinct prerequisites.

Node.js v18 or Newer

All web-based renderers—including the Lit, React, Markdown, and Web-Core implementations—are authored in TypeScript and compiled via npm. The repository's build scripts and dev servers depend on Node.js features introduced in version 18.

In samples/client/lit/package.json, the npm scripts rely on Node's module resolution and ESM support that stabilized in the v18 LTS cycle. Install Node via your package manager and verify the version:

# macOS (Homebrew)

brew install node@18

# Verify installation

node --version   # → v18.x.x or higher

Python 3.9+ and the uv Package Manager

The sample agents (such as the restaurant-finder demo in samples/agent/adk/restaurant_finder/) utilize the Agent Development Kit (ADK) and the A2A protocol, which require Python 3.9 or newer. The project adopts uv as its standard Python package manager for reproducible, lightweight environments.

As documented in docs/quickstart.md, uv handles dependency locking and virtual environment creation without manual venv management:

# Install uv (Unix/macOS)

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

# Verify installation

uv --version   # → 0.xx.x

Navigate to an agent sample and sync dependencies:

cd samples/agent/adk/restaurant_finder
uv sync          # Reads pyproject.toml and installs locked dependencies

Gemini API Key

A2UI agents generate UI JSON by prompting Google's Gemini models. You must obtain an API key from Google AI Studio and expose it as an environment variable. The agent-side code in samples/agent/adk/restaurant_finder/ reads GEMINI_API_KEY at runtime to authenticate LLM requests.

Export the key before running any agent:

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

Optional Development Tools

While the core prerequisites above are mandatory for full-stack operation, specific tooling enhances the development experience.

Inspector UI (Node.js)

The Inspector is a developer-only visualization tool located in tools/inspector/ that helps debug A2UI responses. According to tools/inspector/README.md, this utility requires Node.js to serve its local interface. It does not ship to production but aids in inspecting the JSON payloads exchanged between agents and renderers.

Lit Client Demo (npm)

The Lit renderer and its accompanying sample client—defined in samples/client/lit/package.json—follow standard npm workflows. After installing Node.js, fetch client-side dependencies and launch the dev server:

npm install
npm run dev

Running the Complete Demo

The repository provides an orchestrated command that validates all prerequisites simultaneously. The demo:all script, defined in samples/client/lit/package.json, builds the renderers, starts the Python agent, and launches the development server:

# From repository root

npm install
npm run demo:all

This script bridges the two runtimes: the Python agent (using uv run . internally) generates A2UI JSON via the Gemini API, while the Node.js dev server renders that JSON through the Web-Core and Lit renderers found in renderers/web_core/src/v0_9/index.ts and renderers/lit/src/index.ts.

Summary

• Node.js v18+ is required for all TypeScript-based renderers and client samples.
• Python 3.9+ and the uv package manager power the agent-side ADK samples.
• Gemini API key is mandatory for LLM-driven UI generation; set via GEMINI_API_KEY.
• The Inspector tool (optional) requires Node.js for local debugging.
• Run npm run demo:all from the repository root to validate the complete setup.

Frequently Asked Questions

Does A2UI require a specific operating system?

No. The prerequisites are runtime-based rather than OS-specific. Node.js v18+ and Python 3.9+ are available on macOS, Linux, and Windows. The uv installer provides platform-specific binaries for all major operating systems, and the npm scripts in samples/client/lit/package.json run cross-platform.

Can I use a different Python package manager instead of uv?

While technically possible, the quick-start documentation in docs/quickstart.md and the sample configurations in samples/agent/adk/restaurant_finder/ are optimized for uv. The repository's automated scripts rely on uv sync and uv run commands. Using pip or Poetry requires manual translation of the dependency specifications in pyproject.toml.

Is the Gemini API key used by the client-side renderers?

No. The Gemini API key is consumed only by the agent-side Python code. Client renderers—such as those in renderers/web_core/src/v0_9/index.ts—receive pre-generated A2UI JSON and have no LLM dependencies. The key never leaves the backend, maintaining a clean separation between message generation and message rendering.

What Node.js version is tested in CI?

The repository targets Node.js v18 as its minimum supported version, as specified in the top-level README.md prerequisite section. While newer versions (v20, v22) typically work, v18 is the baseline for compatibility guarantees across all web renderers including the React and Markdown variants.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}