# A2UI: Agent-to-User Interface

A2UI is an open-source project, complete with a format
optimized for representing updatable agent-generated
UIs and an initial set of renderers, that allows agents
to generate or populate rich user interfaces.

<img src="docs/assets/a2ui_gallery_examples.png" alt="Gallery of A2UI components" height="400">

_A gallery of A2UI rendered cards, showing a variety of UI compositions that A2UI can achieve._

## ⚠️ Status: Early stage public preview

> **Note:** A2UI is currently in **v0.8 (Public Preview)**. The specification and
> implementations are functional but are still evolving. We are opening the project to
> foster collaboration, gather feedback, and solicit contributions (e.g., on client renderers).
> Expect changes.

## Summary

Generative AI excels at creating text and code, but agents can struggle to
present rich, interactive interfaces to users, especially when those agents
are remote or running across trust boundaries.

**A2UI** is an open standard and set of libraries that allows agents to
"speak UI." Agents send a declarative JSON format describing the _intent_ of
the UI. The client application then renders this using its own native
component library (Flutter, Angular, Lit, etc.).

This approach ensures that agent-generated UIs are
**safe like data, but expressive like code**.

## Repositories

The A2UI project is distributed across several repositories in the `a2ui-project` organization:

| Repository                                           | Description                                                               |
| :--------------------------------------------------- | :------------------------------------------------------------------------ |
| [a2ui](https://github.com/a2ui-project/a2ui)         | Protocol specification, JSON schemas, and main documentation (this repo). |
| [web-core](https://github.com/a2ui-project/web-core) | Core web libraries and standard components.                               |
| [angular](https://github.com/a2ui-project/angular)   | Angular renderer for A2UI.                                                |
| [lit](https://github.com/a2ui-project/lit)           | Lit renderer for A2UI.                                                    |
| [react](https://github.com/a2ui-project/react)       | React renderer for A2UI.                                                  |
| [samples](https://github.com/a2ui-project/samples)   | Example applications and usage demonstrations.                            |
| [composer](https://github.com/a2ui-project/composer) | Visual editor for authoring A2UI payloads.                                |

## High-level philosophy

A2UI was designed to address the specific challenges of interoperable,
cross-platform, generative or template-based UI responses from agents.

The project's core philosophies:

- **Security first**: Running arbitrary code generated by an LLM may present a
  security risk. A2UI is a declarative data format, not executable
  code. Your client application maintains a "catalog" of trusted, pre-approved
  UI components (e.g., Card, Button, TextField), and the agent can only request
  to render components from that catalog.
- **LLM-friendly and incrementally updatable**: The UI is represented as a flat
  list of components with ID references which is easy for LLMs to generate
  incrementally, allowing for progressive rendering and a responsive user
  experience. An agent can efficiently make incremental changes to the UI based
  on new user requests as the conversation progresses.
- **Framework-agnostic and portable**: A2UI separates the UI structure from
  the UI implementation. The agent sends a description of the component tree
  and its associated data model. Your client application is responsible for
  mapping these abstract descriptions to its native widgets—be it web components,
  Flutter widgets, React components, SwiftUI views or something else entirely.
  The same A2UI JSON payload from an agent can be rendered on multiple different
  clients built on top of different frameworks.
- **Flexibility**: A2UI also features an open registry pattern that allows
  developers to map server-side types to custom client implementations, from
  native mobile widgets to React components. By registering a "Smart Wrapper,"
  you can connect any existing UI component—including secure iframe containers
  for legacy content—to A2UI's data binding and event system. Crucially, this
  places security firmly in the developer's hands, enabling them to enforce
  strict sandboxing policies and "trust ladders" directly within their custom
  component logic rather than relying solely on the core system.

## Use cases

Some of the use cases include:

- **Dynamic Data Collection:** An agent generates a bespoke form (date pickers,
  sliders, inputs) based on the specific context of a conversation (e.g.,
  booking a specialized reservation).
- **Remote Sub-Agents:** An orchestrator agent delegates a task to a
  remote specialized agent (e.g., a travel booking agent) which returns a
  UI payload to be rendered inside the main chat window.
- **Adaptive Workflows:** Enterprise agents that generate approval
  dashboards or data visualizations on the fly based on the user's query.

## Architecture

The A2UI flow disconnects the generation of UI from the execution of UI:

1. **Generation:** An Agent (using Gemini or another LLM) generates or uses
   a pre-generated `A2UI Response`, a JSON payload describing the composition
   of UI components and their properties.
2. **Transport:** This message is sent to the client application
   (via A2A, AG UI, etc.).
3. **Resolution:** The Client's **A2UI Renderer** parses the JSON.
4. **Rendering:** The Renderer maps the abstract components
   (e.g., `type: 'text-field'`) to the concrete implementation in the client's codebase.

## Dependencies

A2UI is designed to be a lightweight format, but it fits into a larger ecosystem:

- **Transports:** Compatible with **A2A Protocol** and **AG UI**.
- **LLMs:** Can be generated by any model capable of generating JSON output.
- **Host Frameworks:** Requires a host application built in a supported framework
  (currently: Web or Flutter).

## Getting started

Pick the path that matches where you want to start:

| Path                                                                                                                          | What you get                                                                                                                            | Time   |
| ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| 🍜 **[Quickstart Restaurant Finder Demo](https://a2ui.org/quickstart/)**                                                      | Full-stack A2UI running locally with a Gemini powered ADK agent and Lit renderer. Learn A2UI end-to-end and customize to your use case. | ~5 min |
| ⚛️ **[A2UI + AG-UI (CopilotKit)](docs/guides/a2ui-with-any-agent-framework.md)**                                              | Set up CopilotKit with your agent framework of choice, then enable A2UI rendering. Ready to ship A2UI in a React app.                   | ~5 min |
| 🎨 **[A2UI Composer](https://a2ui-composer.ag-ui.com/)** · **[Widget Builder](https://go.copilotkit.ai/A2UI-widget-builder)** | Generate A2UI JSON from a visual editor and paste it into any agent prompt — no install required.                                       | ~1 min |
| 🎬 **[A2UI Theater](https://a2ui-composer.ag-ui.com/theater)**                                                                | Step through pre-built A2UI streaming scenarios across Lit, React, and Angular renderers — no install required.                         | ~1 min |

### Restaurant Finder demo — TL;DR

Prerequisites: Node.js 18+, [uv](https://docs.astral.sh/uv/), and a [Gemini API key](https://aistudio.google.com/apikey).

To run the demo, you will need to clone the [samples](https://github.com/a2ui-project/samples) repository and follow the instructions there.

```bash
git clone https://github.com/a2ui-project/samples.git
cd samples
# See README.md in the samples repository for instructions to run the restaurant finder demo.
```

### A2UI + AG-UI — TL;DR

```bash
npx copilotkit@latest init
```

Set up CopilotKit with your framework of choice (ADK, LangGraph, CrewAI, Mastra, …), then follow the **[AG-UI guide](docs/guides/a2ui-with-any-agent-framework.md)** to enable A2UI rendering. CopilotKit's [quickstart](https://docs.copilotkit.ai/quickstart) covers the initial install for any supported agent framework.

### Other renderers

For Flutter, check out the [GenUI SDK](https://github.com/flutter/genui), which uses A2UI under the hood. See [docs/reference/renderers.md](docs/reference/renderers.md) for the full list of client implementations.

## Roadmap

We hope to work with the community on the following:

- **Spec stabilization:** Moving towards a v1.0 specification.
- **More renderers:** Adding official support for React, Jetpack Compose, iOS (SwiftUI), and more.
- **Additional transports:** Support for REST and more.
- **Additional Agent frameworks:** Genkit, LangGraph, and more.

## Contribute

A2UI is an **Apache 2.0** licensed project. We believe the future of UI is agentic,
and we want to work with you to help build it.

See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.
