-
-*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**.
-
-## 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 updateable**: 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
+## A2UI – Agent-to-User Interface
+
+A2UI is an open-source specification and set of libraries that allow AI agents to describe **interactive user interfaces as structured data**, rather than executable code.
+
+Instead of returning raw text, an agent can return a declarative UI description that client applications safely render using their own native components.
+
+This enables agents to generate rich, interactive experiences while keeping execution, security, and control firmly in the hands of the client.
+
+---
+
+## Project Status
+
+**Current version:** v0.8 (Public Preview)
+
+A2UI is functional and actively evolving. The core concepts are stable, but the specification and component schemas may change as we move toward v1.0.
+
+### Stable Areas
+
+* Declarative component model
+* Component ID and reference system
+* Renderer architecture
+* Incremental UI updates
+
+### Likely to Change
+
+* Component naming and properties
+* Schema refinements
+* Transport integrations
+
+A2UI is suitable for experimentation, prototyping, and early production trials with version pinning.
+
+---
+
+## Why A2UI Exists
+
+AI systems are good at generating text and logic, but they struggle to safely produce UI across different platforms.
+
+Traditional approaches require agents to emit HTML, JSX, or framework-specific code, which introduces:
+
+* Security risks
+* Tight coupling to frontend stacks
+* Poor portability across clients
+
+A2UI solves this by letting agents **describe intent**, not implementation.
+
+The client decides how that intent is rendered.
+
+---
+
+## Core Principles
+
+### Security by Design
+
+Agents never generate executable UI code. They emit structured data. The client only renders components from a predefined, trusted catalog.
-The best way to understand A2UI is to run the samples.
+### Agent-Friendly Format
+
+The UI is represented as a flat, ID-based component list. This makes it easy for language models to generate, modify, and incrementally update.
+
+### Framework Independence
+
+The same A2UI payload can be rendered by web, mobile, or desktop clients using different frameworks.
+
+### Extensibility
+
+Clients can register custom components or wrappers, including sandboxed or legacy UI containers, while maintaining strict security boundaries.
+
+---
+
+## What Can You Build With A2UI
+
+* Dynamic forms generated from conversation context
+* Agent-driven dashboards and workflows
+* Remote sub-agents returning UI to a host application
+* Adaptive enterprise tools and internal systems
+
+---
+
+## How It Works
+
+1. An agent produces an A2UI JSON payload
+2. The payload is sent to the client
+3. The client renderer validates the payload
+4. Components are mapped to native UI elements
+5. User events are routed back to the agent
+
+UI generation and UI execution remain fully decoupled.
+
+---
+
+## Minimal Example
+
+```json
+{
+ "components": [
+ {
+ "id": "card",
+ "type": "card",
+ "children": ["title", "action"]
+ },
+ {
+ "id": "title",
+ "type": "text",
+ "value": "Welcome to A2UI"
+ },
+ {
+ "id": "action",
+ "type": "button",
+ "label": "Continue",
+ "onClick": { "event": "next_step" }
+ }
+ ]
+}
+```
+
+The renderer decides how a `card`, `text`, or `button` is displayed using native components.
+
+---
+
+## Architecture Overview
+
+* **Agents** generate A2UI payloads
+* **Transports** deliver payloads to clients
+* **Renderers** interpret and display components
+* **Clients** control security, layout, and execution
+
+A2UI integrates cleanly with agent frameworks and messaging protocols.
+
+---
+
+## Getting Started
-### Prerequisites
+### Requirements
-* Node.js (for web clients)
+* Node.js (for web renderers)
* Python (for agent samples)
-* A valid [Gemini API Key](https://aistudio.google.com/) is required for the samples.
+* Gemini API key for full demo functionality
+
+### Run the Demo
+
+Clone the repository:
+
+```bash
+git clone https://github.com/google/A2UI.git
+cd A2UI
+```
+
+Set your API key:
+
+```bash
+export GEMINI_API_KEY="your_api_key"
+```
+
+Run the agent:
+
+```bash
+cd samples/agent/adk/restaurant_finder
+uv run .
+```
+
+Run the web client:
+
+```bash
+cd renderers/lit
+npm install
+npm run build
+
+cd ../../samples/client/lit/shell
+npm install
+npm run dev
+```
+
+---
+
+## Contribution Paths
+
+You do not need to be an expert to contribute.
+
+### Beginner-Friendly
+
+* Improve documentation and examples
+* Add validation or error handling
+* Write sample payloads
+* Improve README clarity
+
+### Frontend Developers
+
+* Build new renderers (React, Vue, SwiftUI)
+* Improve accessibility and theming
+* Optimize rendering performance
+
+### Backend / Agent Developers
+
+* Create new agent samples
+* Improve incremental update patterns
+* Add schema validation tools
+
+### Spec and Design
+
+* Propose new components
+* Clarify semantics
+* Review security assumptions
+
+---
+
+## License
+
+A2UI is released under the Apache 2.0 License.
+
+---
+
+# 2. Suggested “Good First Issues”
+
+These are realistic, beginner-safe issues you should label as `good first issue`.
+
+### Documentation
+
+1. Add a glossary explaining core A2UI terms
+2. Write a “Common Mistakes” section
+3. Add more minimal JSON examples
+4. Improve error messages documentation
+
+### Tooling
+
+5. Create a JSON schema for validation
+6. Add a payload linter CLI
+7. Improve logging in renderers
+
+### Renderers
+
+8. Add keyboard accessibility support
+9. Improve layout fallback handling
+10. Add theme customization hooks
+
+### Samples
+
+11. Add a non-LLM mock agent
+12. Add a form-based demo
+13. Add a dashboard demo
+
+---
+
+# 3. React Renderer Starter Template (Design)
+
+### Folder Structure
+
+```
+renderers/react/
+ src/
+ components/
+ Card.tsx
+ Button.tsx
+ Text.tsx
+ registry.ts
+ Renderer.tsx
+ package.json
+ README.md
+```
+
+---
+
+### Component Registry
+
+```ts
+export type ComponentRenderer = (props: any) => JSX.Element;
+
+export const registry: Record{value}
; +} +``` -2. **Set your API Key:** +--- - ```bash - export GEMINI_API_KEY="your_gemini_api_key" - ``` +### Usage -3. **Run the Agent (Backend):** +```tsx +register("text", Text); +register("button", Button); +register("card", Card); - ```bash - cd samples/agent/adk/restaurant_finder - uv run . - ``` +