discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens
a2ui-project/a2ui · source
Snapshot 0 · 2026-11-04T12:47:28Z · TypeScript · Apache-2.0
Content fingerprint
f542ff4fa39055f1df22ea165d01b99c780e37382f502d4d0d0e073741ef3ff7GitHub description at capture
README at capture
# A2UI: Agent-to-User Interface A2UI is an open-source generative UI framework, 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/public/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's current production release is **v0.9.1**, a patch release in > the stable v0.9 protocol family. The v1.0 specification is a release > candidate, while v0.8 is legacy. 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**. ## When to use A2UI - **Use A2UI** when you need agent-generated UI on **Flutter**, **Angular**, **SwiftUI / Jetpack Compose**, or **more than one platform** from the same agent. - **Use A2UI** when the agent is **remote, third-party, or across a trust boundary** and must not send executable code to your renderer. - **Use A2UI on Flutter** with [`a2ui_flutter`](dart/a2ui_flutter/): `flutter pub add a2ui_flutter a2ui_core`. It replaces the `genui` package. - **You may not need A2UI** for a **React-only chat** that renders tool results as your own components; an LLM toolkit alone may be enough. A2UI fits once you add platforms or remote agents. Install the renderer for your framework, for example `npm install @a2ui/react` (or `@a2ui/angular`, `@a2ui/lit`). It depends on `@a2ui/web_core`; add `@a2ui/web_core` explicitly too if your app imports from it directly (e.g. the message processor or basic catalog). See the [Client Setup guide](https://a2ui.org/guides/client-setup/) for each platform. ## 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 | | ⚛️ **[Use A2UI with Any Agent Framework & Harness](docs/public/guides/a2ui-with-any-agent-framework.md)** | Scaffold an AG-UI app or harness for your framework of choice, then enable A2UI rendering over AG-UI. | ~5 min | | 🎨 **[A2UI Composer](https://a2ui-project.github.io/composer/)** | 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 — Summary Prerequisites: Node.js 18+ (with [Corepack](https://nodejs.org/api/corepack.html) enabled), [uv](https://docs.astral.sh/uv/), and a [Gemini API key](https://aistudio.google.com/apikey). ```bash git clone https://github.com/a2ui-project/a2ui.git cd a2ui export GEMINI_API_KEY="your_gemini_api_key" # Enable Corepack (macOS Homebrew users: see tip below) corepack enable yarn install cd samples/client/lit yarn demo:restaurant ``` > [!TIP] > **macOS Homebrew Users:** If you previously installed standalone package managers, unlink conflicts before installing Corepack so Corepack can manage versions per-project: > > ```bash > brew unlink yarn pnpm > brew install corepack > corepack enable > ``` These commands install dependencies across workspaces, build the renderers, start the Python agent, and open the client at `http://localhost:5173`. For step-by-step instructions, alternative demos, and troubleshooting see the **[full Quickstart](docs/public/quickstart.md)**. ### Use A2UI with Any Agent Framework & Harness — Summary ```bash npx create-ag-ui-app@latest ``` Use the AG-UI CLI with your framework or harness of choice (Google Chat, ADK, LangGraph, CrewAI, Mastra, Strands, Slack, Teams, etc.), then follow the **[AG-UI guide](docs/public/guides/a2ui-with-any-agent-framework.md)** to enable A2UI rendering. Some scaffold paths use [CopilotKit's A2UI runtime](https://docs.copilotkit.ai/generative-ui/a2ui) with Next.js under the hood, but the setup surface is AG-UI-first. ### Other renderers For Flutter, check out the [GenUI SDK](https://github.com/flutter/genui), which uses A2UI under the hood. See [docs/public/reference/renderers.md](docs/public/reference/renderers.md) for the full list of client implementations. ## Packages These packages are developed in this repository. Packages marked "Not published yet" can be used from source. ### Python | Package | Description | Version | | ------------------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | [a2ui-core](python/a2ui_core/) | Protocol messages, data model, data binding and catalog validation. | [](https://pypi.org/project/a2ui-core/) | | [a2ui-agent-sdk](python/a2ui_agent/) | Agent SDK: teaches the LLM a catalog and parses its response into A2UI messages. | [](https://pypi.org/project/a2ui-agent-sdk/) | | [a2ui-a2a](python/a2ui_a2a/) | Connects the agent SDK to the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org). | Not published yet | | [a2ui-adk](python/a2ui_adk/) | Connects the agent SDK to the [Agent Development Kit (ADK)](https://github.com/google/adk-python). | Not published yet | ### TypeScript | Package | Description | Version | | ------------------------------------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | [@a2ui/web_core](typescript/core/web_core/) | Protocol messages, state management and catalogs shared by the web renderers. | [](https://www.npmjs.com/package/@a2ui/web_core) | | [@a2ui/lit](typescript/renderers/lit/) | Lit (web components) renderer. | [](https://www.npmjs.com/package/@a2ui/lit) | | [@a2ui/angular](typescript/renderers/angular/) | Angular renderer. | [](https://www.npmjs.com/package/@a2ui/angular) | | [@a2ui/react](typescript/renderers/react/) | React renderer. | [](https://www.npmjs.com/package/@a2ui/react) | | [@a2ui/markdown-it](typescript/renderers/markdown-it/) | Markdown rendering with markdown-it and DOMPurify, shared by the web renderers. | [](https://www.npmjs.com/package/@a2ui/markdown-it) | | [@a2ui/agent](typescript/agents/a2ui_agent/) | Agent SDK for TypeScript and Node.js. | Not published yet | ### Dart and Flutter | Package | Description | Version | | ---------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | [a2ui_core](dart/a2ui_core/) | Protocol messages, data model, data binding and expressions for renderers and agents. | [](https://pub.dev/packages/a2ui_core) | | [a2ui_agent](dart/a2ui_agent/) | Agent SDK: teaches the LLM a catalog and parses its response into A2UI messages. | [](https://pub.dev/packages/a2ui_agent) | | [a2ui_flutter](dart/a2ui_flutter/) | Flutter renderer. | Not published yet | | [a2ui_cli](dart/a2ui_cli/) | Developer tool that generates typesafe component code from a catalog. | Not published yet | ### Swift The Swift libraries are built by the [Package.swift](Package.swift) at the root of this repository. | Package | Description | Version | | -------------------------------------------------- | ------------------------------------------------------------ | ----------------- | | [A2UISwiftCore, BasicCatalog](swift/core/) | Message processor, data model and basic catalog definitions. | Not published yet | | [A2UISwiftUI, BasicCatalogSwiftUI](swift/swiftui/) | SwiftUI renderer and basic catalog views. | Not published yet | ## 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.