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

> Set up A2UI with ease. Discover the essential prerequisites including Node.js v18+, Python 3.9+, uv, and a Gemini API key for LLM-driven UI generation.

- Repository: [Google/A2UI](https://github.com/google/A2UI)
- Tags: getting-started
- Published: 2026-03-13

---

**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`](https://github.com/google/A2UI/blob/main/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:

```bash

# 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`](https://github.com/google/A2UI/blob/main/docs/quickstart.md), `uv` handles dependency locking and virtual environment creation without manual `venv` management:

```bash

# 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:

```bash
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:

```bash
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`](https://github.com/google/A2UI/blob/main/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`](https://github.com/google/A2UI/blob/main/samples/client/lit/package.json)—follow standard npm workflows. After installing Node.js, fetch client-side dependencies and launch the dev server:

```bash
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`](https://github.com/google/A2UI/blob/main/samples/client/lit/package.json), builds the renderers, starts the Python agent, and launches the development server:

```bash

# 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`](https://github.com/google/A2UI/blob/main/renderers/web_core/src/v0_9/index.ts) and [`renderers/lit/src/index.ts`](https://github.com/google/A2UI/blob/main/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`](https://github.com/google/A2UI/blob/main/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`](https://github.com/google/A2UI/blob/main/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`](https://github.com/google/A2UI/blob/main/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`](https://github.com/google/A2UI/blob/main/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`](https://github.com/google/A2UI/blob/main/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.