Paste your key, then try _"A weekend in Lisbon from JFK in May, two of us"_.
Here Flutter is built for the web, in a phone layout; the same Dart code can
target iOS and Android, which this sample does not set up. Ask both apps the
same thing: the same messages, drawn by two renderers.
## How A2UI works
Five short steps, in the order you meet them on screen: what on the screen is
A2UI, what the agent is allowed to draw, how the model learns it, what travels
to the client, and what draws it. For all of it in one picture, see
[how A2UI fits into this app](/quickstart/#how-a2ui-fits-into-this-app).
### 1. What is A2UI, and what is app code
Not everything on screen is A2UI. Blue is composed by the agent; grey is app
code, written by you, the builder, and the same on every turn:
- **A2UI, composed by the agent:** the cards in the conversation, the trip
panel (the trip sheet in Flutter) and the web client's Home dashboard.
- **App code:** the header and tabs, the message box, the chat bubbles (the
model's words, shown as plain text), the key form, and the Catalog and Wire
tabs.
Each blue region is a **surface**: one area of UI the agent controls. A surface
is made of **components** (a `Text`, a `Button`, a `FlightOption`), and the
values they show come from the surface's **data model**. When the user taps a
flight, the agent receives an **action** saying which one.
A rule of thumb for your own app: if it should look the same on every turn,
build it yourself as app code; if it depends on what the user just asked, let
the agent compose it.
### 2. The catalog: what the agent may draw
The **catalog** (`catalogs/a2ui-travel/catalog.json`) lists everything the
agent may use, and it holds two kinds of thing:
- **Components**, and the properties each takes. A2UI's **basic catalog**
provides `Text`, `Row`, `Column`, `List`, `Button`, `TextField` and more;
this app adds travel components such as `FlightOption`, `HotelCard`,
`DateRangePicker` and `PriceSummary`. A component can hold others, so a card
is a small arrangement of catalog components.
- **Functions**, which run in the client. The basic ones format and check
values (`formatCurrency`, `formatDate`, `pluralize`, `required`); this app
adds `calcNights` and `equals`. A component can show a function's result, so
the night count follows the dates the user picks, with no turn to the agent:
```text
"${calcNights(start: ${/trip/startDate}, end: ${/trip/endDate})} nights"
```
The web client's **Catalog** tab draws every component with the real renderer:
The catalog is also the **guardrail**. The server checks every message the
model writes against it before sending anything, and each client implements
every component and function in it, so the agent can only ask for what the
client knows how to draw. The work splits between the model and you, the
builder:
| The model decides | You, the builder, decide |
| -------------------------------- | -------------------------------------------------- |
| Whether to show a card | Which components and functions exist (the catalog) |
| Which components, and the layout | The data in them |
| The wording | That every message is checked against the catalog |
| What to ask next | What a press records |
### 3. Skills: teaching the model A2UI
A **skill** is a Markdown file that teaches a model to write A2UI for a
catalog. This app has two, in `skills/express-modular/`: `a2ui-core` teaches
the notation, and `a2ui-travel` teaches this catalog. Here is an entry from the
second:
```text
• FlightOption(airline, departTime,
arriveTime, origin, destination,
price, action (static), duration?,
stops?, flightNumber?, …)
- Description: A single selectable
flight itinerary leg. Use one per
option when presenting a choice
of flights.
- airline: Operating carrier,
e.g. 'Iberia' or 'Delta'.
```
Here the skills are generated from the catalog with the A2UI agent SDK's
`SkillGenerator` (`scripts/build_skills.py`), so when a component changes,
`npm run generate` updates what the model is taught to match.
### 4. What the model writes, and what the client receives
The model writes **A2UI Express**, a short notation, as its skills taught it.
`root` comes first, so the card can appear before the rest is written:
```text
root = Column([head, list])
head = Text("### Flights to Madrid")
list = List(_template($/flights, fare))
fare = FlightOption($airline,
$departTime, $arriveTime,
$origin, $destination, $price,
Event("select_flight", {id: $id}))
```
On the server, the **A2UI agent SDK** reads the Express as the model streams
it, turns it into **A2UI messages** and checks each against the catalog. The
messages are JSON: `createSurface`, `updateComponents`, `updateDataModel` and
`deleteSurface`. Here is the component list one of these blocks became (trimmed
to ids and links): each component names its children by id, starting from
`root`.
```json
[
{"id": "root", "component": "Column", "children": ["head", "list"]},
{"id": "head", "component": "Text", "text": "### Flights to Madrid"},
{"id": "fare", "component": "FlightOption"},
{
"id": "list",
"component": "List",
"children": {"path": "/flights", "componentId": "fare"}
}
]
```
In the client, a **MessageProcessor** from the A2UI SDK applies the messages:
it keeps each surface's components and data, fills in bound values, runs
catalog functions, and sends presses back as actions. React uses
`@a2ui/web_core`'s (`apps/web/src/surfaces.ts`); Flutter uses `a2ui_core`'s
(`apps/flutter/lib/chat.dart`).
The web client's **Wire** tab shows both forms of every surface side by side,
what the model wrote and what the client received:
Express is one way for a model to write A2UI, chosen because it is short. A2UI
itself is the JSON.
### 5. Renderers
A **renderer** implements the catalog's components with native widgets and
uses a MessageProcessor to apply messages. It holds no app logic.
- **In this app:** React (`@a2ui/react`, `@a2ui/web_core`) in
`renderers/react/`, and Flutter (`a2ui_flutter`, `a2ui_core`) in
`renderers/flutter/`. The apps around them are `apps/web/` and
`apps/flutter/`.
- **[Maintained by the A2UI project](/concepts/sdks/#renderer-sdk):** Lit
(web components), Angular, React, Flutter, SwiftUI, Jetpack Compose and
Markdown.
- **[From the community](/ecosystem/renderers/):** UIKit, React Native,
Vue, Lynx, a terminal renderer and more.
The server never knows which client it is talking to. Adding a platform means
writing a renderer for the same catalog, with no change to the agent.
## Deploy to Cloud Run
Run the quickstart app in your own Google Cloud project: the server and both
clients on one URL. You need a project with billing enabled.
[](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https://github.com/a2ui-project/labs&cloudshell_git_branch=main&cloudshell_workspace=samples/travel-a2ui&cloudshell_tutorial=docs/cloud-shell.md&show=ide%2Cterminal)
Cloud Shell opens with the sample and a short guide beside the terminal: sign
in, choose a project, and run one script:
```bash
./scripts/deploy.sh
```
It turns on the services the deploy needs, lets the build use them, then builds
and deploys (about ten minutes the first time) and prints the URL. No key is
stored on the service: each visitor pastes their own. From your own clone, the
same script works anywhere the gcloud CLI is signed in; see
[deploying](https://github.com/a2ui-project/labs/blob/main/samples/travel-a2ui/docs/deploying.md)
for what it runs.
## Keep going
- [Build your own](https://github.com/a2ui-project/labs/tree/main/samples/travel-a2ui#build-one-of-your-own): what to change to make
this app about something other than travel.
- [A2UI renderers](/concepts/sdks/#renderer-sdk): the official Renderer SDKs and [community renderers](/ecosystem/renderers/).
- [How A2UI works](/concepts/overview/): the concepts, in depth.
- [A2UI v1.0 specification](/specification/v1.0-a2ui/).
---
# Overview: How A2UI Works
> How the A2UI agent SDK, transport, and client renderer fit together, traced through a single request.
Canonical URL: https://a2ui.org/concepts/overview/
A2UI lets an AI agent describe an interactive UI as a stream of JSON messages that a client app renders with its own native widgets. Below you'll find the mechanics on each side of the connection, how they fit together, and one request traced from the user's prompt to a button tap.
---
## Generating UI
On the server, you configure the [A2UI Agent SDK](/concepts/sdks/#agent-sdk) with a [component catalog](/concepts/catalogs/) (`catalog.json`) that describes the UI components and functions available to render on your client. From that catalog, the SDK's skill generator produces an A2UI skill containing prompt instructions and grammar rules. Your agent code and LLM runtime sit outside the SDK: they take the generated A2UI skill alongside your domain tools (such as a flight search API), call the model, and pass its UI output to the SDK's compiler. The compiler parses and validates the content against the catalog, then sends layout ([`updateComponents`](/concepts/messages/)) and data ([`updateDataModel`](/concepts/messages/)) messages over a transport such as AG-UI, A2A, MCP, or WebSockets.
On the client, your app hosts an [A2UI Renderer](/concepts/sdks/#renderer-sdk), which draws the UI with native platform widgets inside a region of your screen called a surface. Controls bound to the surface's [data model](/concepts/data-binding/) update state locally as the user interacts with them, and user triggers such as button taps send [`action`](/concepts/actions-and-functions/) messages back to the agent.
While this page focuses on generating UI at request time, A2UI content can also be authored in advance and sent as a static payload (for example, returned from an MCP server via an agent to a client), following a traditional server-driven UI pattern.
_In the diagram above, purple marks your server-side agent code, blue marks your client app, and the teal dashed outlines mark the A2UI libraries on each side (the Agent SDK on the server and the Renderer on the client)._
---
## Step-by-step generation
The rest of this page traces a flight-booking request through each stage of the pipeline: defining the catalog, generating the skill, prompting the model, compiling and validating the output, rendering the surface on the client, and handling user actions.
### Define the catalog
You define the components and functions your client can render in `catalog.json`. A travel app might pair the basic catalog with domain components such as `FlightCard`. Each component declares its properties with JSON Schema, so the Agent SDK can validate that the model only emits components and properties the client knows how to draw:
#### v1.0
{/* prettier-ignore */}
```jsonc
{
"protocolVersion": "1.0",
"catalogId": "https://example.com/catalogs/travel/v1/catalog.json",
"components": {
"FlightCard": {
"type": "object",
"description": "Displays a flight segment with fare and passenger count.",
"properties": {
"component": {"const": "FlightCard"},
"flightNumber": {
"$ref": "common_types.json#/$defs/DynamicString",
"description": "IATA flight designator, such as 'LH 454'."
}
// ... origin, destination, price, passengers
},
"required": ["component", "flightNumber", "origin", "destination", "price", "passengers"]
}
// ... other components and functions
}
}
```
#### v0.9.1
{/* prettier-ignore */}
```jsonc
{
"catalogId": "https://example.com/catalogs/travel/v0_9/catalog.json",
"components": {
"FlightCard": {
"type": "object",
"allOf": [
{"$ref": "https://a2ui.org/specification/v0_9/common_types.json#/$defs/ComponentCommon"},
{
"type": "object",
"description": "Displays a flight segment with fare and passenger count.",
"properties": {
"component": {"const": "FlightCard"},
"flightNumber": {
"$ref": "https://a2ui.org/specification/v0_9/common_types.json#/$defs/DynamicString",
"description": "IATA flight designator, such as 'LH 454'."
}
// ... origin, destination, price, passengers
},
"required": ["component", "flightNumber", "origin", "destination", "price", "passengers"]
}
],
"unevaluatedProperties": false
}
// ... other components and functions
}
}
```
### Generate the skill
From `catalog.json`, the Agent SDK's skill generator builds an A2UI skill containing grammar rules for the chosen [inference format](/concepts/inference-formats/) (such as Express) together with component and function signatures derived directly from your catalog:
```text
---
name: a2ui
description: Generates interactive user interface components for user requests.
---
# A2UI Express DSL Output Contract
You must output the user interface using A2UI Express.
IMPORTANT: You MUST always surround the entire A2UI Express block with the literal sentinel tags `
Flight {flightNumber}
{fareAmount !== undefined && ${fareAmount.toFixed(2)}}
);
});
export const travelCatalog = new Catalog(
'https://example.com/catalogs/travel/v1/catalog.json',
'1.0',
[FlightStatusCard],
BASIC_FUNCTIONS,
);
const processor = new MessageProcessor([travelCatalog]);
```
#### Lit
```typescript
import {html, nothing} from 'lit';
import {customElement} from 'lit/decorators.js';
import {z} from 'zod';
import {A2uiLitElement, type LitComponentApi} from '@a2ui/lit';
import {Catalog, type ComponentApi, MessageProcessor} from '@a2ui/web_core';
import {BASIC_FUNCTIONS, DynamicNumberSchema, DynamicStringSchema} from '@a2ui/web_core/v1_0';
const FlightStatusCardApi = {
name: 'FlightStatusCard',
allowedParents: ['Column', 'List'],
schema: z.object({
flightNumber: DynamicStringSchema,
fareAmount: DynamicNumberSchema.optional(),
}),
} satisfies ComponentApi;
@customElement('flight-status-card')
export class FlightStatusCardElement extends A2uiLitElement
Flight ${flightNumber}
${fareAmount !== undefined ? html`$${fareAmount.toFixed(2)}` : nothing}
`;
}
}
const FlightStatusCard = {
...FlightStatusCardApi,
tagName: FlightStatusCardElement.tagName,
element: FlightStatusCardElement,
} satisfies LitComponentApi;
export const travelCatalog = new Catalog(
'https://example.com/catalogs/travel/v1/catalog.json',
'1.0',
[FlightStatusCard],
BASIC_FUNCTIONS,
);
const processor = new MessageProcessor([travelCatalog]);
```
#### Angular
```typescript
import {Component, computed} from '@angular/core';
import {z} from 'zod';
import {
AngularCatalog,
BASIC_FUNCTIONS,
CatalogComponent,
createComponentImplementation,
provideA2UI,
} from '@a2ui/angular';
import {type ComponentApi} from '@a2ui/web_core';
import {DynamicNumberSchema, DynamicStringSchema} from '@a2ui/web_core/v1_0';
const FlightStatusCardApi = {
name: 'FlightStatusCard',
allowedParents: ['Column', 'List'],
schema: z.object({
flightNumber: DynamicStringSchema,
fareAmount: DynamicNumberSchema.optional(),
}),
} satisfies ComponentApi;
@Component({
selector: 'app-flight-status-card',
template: `
Flight {{ flightNumber() }}
@if (formattedFare(); as fare) {
\${{ fare }}
}
`,
})
export class FlightStatusCardComponent extends CatalogComponentEdge cases when createSurface.catalogId is omitted
`catalogId` in `createSurface` is optional. If a surface omits `createSurface.catalogId`, every component must set its own `@catalogId` and every function call its own `catalogId`. If an entry omits its catalog ID and the surface has no default `catalogId` either, the renderer rejects that component or function call rather than falling back to `supportedCatalogIds`. See [Mixable catalogs and component resolution logic](/specification/v1.0-a2ui/#mixable-catalogs-and-component-resolution-logic) for the full resolution rules.
[BasicCatalog](https://github.com/a2ui-project/a2ui/blob/main/Package.swift) | v0.9.1, v1.0 | [swift/core](https://github.com/a2ui-project/a2ui/tree/main/swift/core) | | Kotlin | [androidx.a2ui](https://developer.android.com/jetpack/androidx/releases/a2ui) | v0.9.1 | [AndroidX a2ui](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:a2ui/) | All v0.9.1 packages accept v0.9 wire envelopes and catalog IDs. Swift packages are distributed through Swift Package Manager from [`a2ui-project/a2ui`](https://github.com/a2ui-project/a2ui) (the `A2UISwiftCore` product exposes the `A2UICore` module), and the AndroidX group on Google Maven publishes the `a2ui-model` and `a2ui-engine` artifacts. Most applications install a Core SDK automatically through an [Agent SDK](#agent-sdk) or [Renderer SDK](#renderer-sdk), though you can depend on a Core SDK directly to build headless state processors or custom UI adapters. To implement a Core SDK in another language, read [`blueprints/modules`](https://github.com/a2ui-project/a2ui/tree/main/blueprints/modules) and validate against the YAML suites in [`conformance/core`](https://github.com/a2ui-project/a2ui/tree/main/conformance/core). ## Agent SDK An Agent SDK connects a language model or agent runtime to the A2UI protocol while leaving model selection, tool execution, and conversation state under your application's control. ### Primary functions 1. Negotiates active [Catalog](/concepts/catalogs/) definitions and protocol versions (v0.9.1 and v1.0) against the capabilities reported by the client renderer (see [Overview](/concepts/overview/)). 2. Generates skills, system prompt instructions, and examples directly from catalog schemas and prompt instructions, replacing hand-written prompts that become outdated when components change. 3. Compiles streaming or batch model output from [inference formats](/concepts/inference-formats/) (such as compact Express syntax, which cuts output tokens without client changes, or chunk-healed Direct JSON) into standard A2UI [wire messages](/concepts/messages/). 4. Validates outgoing messages statefully against active surface state on the server so broken component IDs, placement violations, or schema mismatches can be fed back to the model for self-correction before transmission. 5. Supports optional server-side [`@macro`](/guides/macros/) expansion in Python and integrates with agent frameworks and transports including [Google ADK](https://github.com/google/adk-python) and the [A2A protocol](https://a2a-protocol.org/). ### Packages | Language | Published packages | Versions | Source | | :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | TypeScript | [@a2ui/agent](https://www.npmjs.com/package/@a2ui/agent) | v0.9.1, v1.0 | [typescript/agents/a2ui_agent](https://github.com/a2ui-project/a2ui/tree/main/typescript/agents/a2ui_agent) | | Python | [a2ui-agent-sdk](https://pypi.org/project/a2ui-agent-sdk/)
[a2ui-adk](https://pypi.org/project/a2ui-adk/) (ADK)
[a2ui-a2a](https://pypi.org/project/a2ui-a2a/) (A2A) | v0.8, v0.9.1, v1.0 | [python/a2ui_agent](https://github.com/a2ui-project/a2ui/tree/main/python/a2ui_agent)
[python/a2ui_adk](https://github.com/a2ui-project/a2ui/tree/main/python/a2ui_adk)
[python/a2ui_a2a](https://github.com/a2ui-project/a2ui/tree/main/python/a2ui_a2a) | | Dart | [a2ui_agent](https://pub.dev/packages/a2ui_agent) | v0.9.1, v1.0 | [dart/a2ui_agent](https://github.com/a2ui-project/a2ui/tree/main/dart/a2ui_agent) | Swift and Kotlin target client-side rendering; for legacy v0.8 and v0.9 JVM servers, [`kotlin/agent_sdk_legacy`](https://github.com/a2ui-project/a2ui/tree/main/kotlin/agent_sdk_legacy) remains in the repository. ### Go and community SDKs For **Go** services and CLI clients, community-maintained libraries cover server-side validation, streaming parsers, and terminal rendering—including [`satorunooshie/a2ui-go`](https://github.com/satorunooshie/a2ui-go), [`tmc/a2ui`](https://pkg.go.dev/github.com/tmc/a2ui), [`charmbracelet/a2tea`](https://github.com/charmbracelet/a2tea), and [`muncus/a2term`](https://github.com/muncus/a2term) (listed with version details in [Community Projects](/ecosystem/renderers/)). To implement a conformance-verified Core or Agent SDK in Go, Rust, C#, or another language, follow the language-agnostic specifications in [`blueprints/modules`](https://github.com/a2ui-project/a2ui/tree/main/blueprints/modules), verify behavioral parity against the YAML suites in [`conformance/core`](https://github.com/a2ui-project/a2ui/tree/main/conformance/core) and [`conformance/agent`](https://github.com/a2ui-project/a2ui/tree/main/conformance/agent), and open a pull request to add your package to [Community Projects](/ecosystem/renderers/#how-to-submit-a-project). See [Using a catalog in an agent](/concepts/catalogs/#using-a-catalog-in-an-agent) and [Inference Formats](/concepts/inference-formats/#how-inference-formats-stay-swappable) for TypeScript, Python, and Dart examples of configuring `A2uiGenerator`, negotiating capabilities, and compiling model responses, or run a working agent in the [Quickstart](/quickstart/). ## Renderer SDK A Renderer SDK connects a Core SDK's resolved surface state to a client UI framework. Official Renderer SDKs include a built-in implementation of the [Basic Catalog](/concepts/catalogs/#the-basic-catalog) styled through the host framework's theming system, and let you register custom catalogs with per-component rendering logic and local functions (see [How to Define a Catalog](/guides/defining-a-catalog/)). ### Primary functions 1. Applies incremental [surface, component, and data model updates](/concepts/messages/) across supported protocol versions (v0.9.1, v1.0, and v0.8 on Web), updating only changed subtrees so unchanged siblings keep focus and local UI state. 2. Evaluates [reactive data bindings](/concepts/data-binding/), nested collection scopes, relative JSON Pointers, and local two-way input edits. 3. Executes [local catalog functions](/concepts/catalogs/#functions) and [reactive validation checks](/specification/v1.0-a2ui/#component-validation--check-rules), enforcing v1.0 caller and user-activation rules. 4. Builds capability and data-model sync metadata payloads for your transport layer, dispatches user action events and structured error messages, and handles v1.0 bidirectional function RPCs. 5. Maps protocol accessibility attributes to host accessibility APIs across Flutter, Web WAI-ARIA, SwiftUI, and Jetpack Compose. ### Packages | Framework | Published packages | Versions | Source | | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Flutter | [a2ui_flutter](https://pub.dev/packages/a2ui_flutter) | v0.9.1, v1.0 | [dart/a2ui_flutter](https://github.com/a2ui-project/a2ui/tree/main/dart/a2ui_flutter) | | React | [@a2ui/react](https://www.npmjs.com/package/@a2ui/react) | v0.8, v0.9.1, v1.0 | [typescript/renderers/react](https://github.com/a2ui-project/a2ui/tree/main/typescript/renderers/react) | | Lit | [@a2ui/lit](https://www.npmjs.com/package/@a2ui/lit) | v0.8, v0.9.1, v1.0 | [typescript/renderers/lit](https://github.com/a2ui-project/a2ui/tree/main/typescript/renderers/lit) | | Angular | [@a2ui/angular](https://www.npmjs.com/package/@a2ui/angular) | v0.8, v0.9.1, v1.0 | [typescript/renderers/angular](https://github.com/a2ui-project/a2ui/tree/main/typescript/renderers/angular) | | SwiftUI | [A2UISwiftUI](https://github.com/a2ui-project/a2ui/blob/main/Package.swift)
[BasicCatalogSwiftUI](https://github.com/a2ui-project/a2ui/blob/main/Package.swift) | v0.9.1, v1.0 | [swift/swiftui](https://github.com/a2ui-project/a2ui/tree/main/swift/swiftui) | | Jetpack Compose | [androidx.a2ui.compose](https://developer.android.com/jetpack/androidx/releases/a2ui-compose)
[material3-a2ui](https://developer.android.com/jetpack/androidx/releases/compose-material3) | v0.9.1 | [AndroidX a2ui](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:a2ui/) · [material3-a2ui](https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:compose/material3/material3-a2ui/) · [Docs](https://developer.android.com/develop/ui/compose/agentic) | On Web, [`@a2ui/web_core`](https://www.npmjs.com/package/@a2ui/web_core) provides the shared Basic Catalog implementation used by React, Lit, and Angular, [`@a2ui/markdown-it`](https://www.npmjs.com/package/@a2ui/markdown-it) ([source](https://github.com/a2ui-project/a2ui/tree/main/typescript/renderers/markdown-it)) renders Markdown inside text components, and [`@a2ui/catalog-mcp`](https://www.npmjs.com/package/@a2ui/catalog-mcp) adds MCP app components (see [Call MCP Tools from A2UI](/guides/mcp-catalog/)). See [Registering a catalog in a renderer](/concepts/catalogs/#registering-a-catalog-in-a-renderer) and [How to Define a Catalog](/guides/defining-a-catalog/) for Flutter, Web, SwiftUI, and Jetpack Compose examples of setting up a message processor, registering component widgets and local functions, and mounting surfaces, or run a React or Flutter client in the [Quickstart](/quickstart/). Read [Authoring Universal Web Components](/guides/authoring-universal-components/) to share custom components across React, Lit, and Angular, or see the [Android Jetpack Compose guide](https://developer.android.com/develop/ui/compose/agentic) for Android integration. Browse [Community Projects](/ecosystem/renderers/) for community renderers, or consult [`blueprints/modules`](https://github.com/a2ui-project/a2ui/tree/main/blueprints/modules) and [`conformance`](https://github.com/a2ui-project/a2ui/tree/main/conformance) to build a custom framework adapter. --- # Render A2UI Inside an MCP App > Bundle an A2UI renderer inside an MCP App ui:// resource so existing MCP hosts can display interactive A2UI surfaces without native host code. Canonical URL: https://a2ui.org/guides/a2ui-in-mcp-apps/ An **[MCP App](https://modelcontextprotocol.io/extensions/apps/overview)** can bundle an embedded A2UI web renderer inside its `ui://` HTML resource (`text/html;profile=mcp-app`) so existing [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) hosts display interactive A2UI surfaces without adding A2UI renderer code to the host application. Instead of requiring every MCP client (such as Claude Desktop, the MCP Inspector, or an IDE) to install an A2UI SDK, your MCP server ships a self-contained HTML bundle that mounts `
---
## Quick start: run the community sample
The [`samples/community/mcp/a2ui-in-mcpapps/`](https://github.com/a2ui-project/a2ui/blob/main/samples/community/mcp/a2ui-in-mcpapps/README.md) directory contains a runnable end-to-end sample with a Python MCP server (`server/server.py`), two single-file Angular micro-apps (`ui://editor/app` for a generative document editor and `ui://basic/app` for a counter), and a sample Angular MCP Apps host (`client/`) that runs a double-iframe sandbox on `http://localhost:4200`.
> **Note**
The community sample currently emits A2UI `v0.8` messages (`surfaceUpdate`, `dataModelUpdate`, and
`beginRendering`) rendered by `@a2ui/angular` `0.10.x` inside the micro-apps. The implementation
walkthrough below updates this pattern to `v1.0` and `v0.9.1` wire payloads with `@a2ui/lit` and
`@a2ui/web_core`.
### Prerequisites
Install these tools before building and running the sample from a clone of the A2UI repository:
1. Python 3.10 or later and [`uv`](https://docs.astral.sh/uv/) for the Python MCP server (`server/.python-version` targets Python 3.13 when managed by `uv`).
2. Node.js 22.12 or later with Corepack enabled (`corepack enable`) so `yarn` resolves the standalone Yarn workspace under `samples/community/`.
3. A `GOOGLE_API_KEY` from [Google AI Studio](https://aistudio.google.com/apikey) so `server/smart_editor_agent.py` can initialize its Gemini client at startup and generate contextual editor controls (if a Gemini call fails at runtime, the editor falls back to preset slider controls).
### Build the sandbox relay and micro-apps
The server serves single-file HTML bundles from `server/apps/public/`, which are git-ignored in a fresh checkout. Install the `samples/community` workspace dependencies, build the host's outer sandbox relay, and build both micro-apps from the repository root:
```bash
cd samples/community
yarn install
# Build the host's outer sandbox relay (client/public/sandbox_iframe/)
yarn workspace a2ui-in-mcpapps-client run build:sandbox
# Build and inline the Editor micro-app (server/apps/public/editor.html)
yarn workspace basic-mcp-app-angular-editor run build:all
# Build and inline the Basic Counter micro-app (server/apps/public/app.html)
yarn workspace basic-mcp-app-angular run build:all
```
When iterating on a single micro-app, you can run `yarn build:all` directly inside `samples/community/mcp/a2ui-in-mcpapps/server/apps/editor` or `samples/community/mcp/a2ui-in-mcpapps/server/apps/src`.
### Start the MCP server and host client
Open two terminals starting from the repository root.
1. In the first terminal, start the Python MCP server over Server-Sent Events (SSE) on `http://127.0.0.1:8000/sse` (pass `--transport stdio` instead when connecting a desktop MCP host over standard input/output):
```bash
cd samples/community/mcp/a2ui-in-mcpapps/server
export GOOGLE_API_KEY="your-api-key" # Required at startup by smart_editor_agent.py
uv sync
uv run python server.py --transport sse --port 8000
```
2. In the second terminal, start the sample Angular MCP Apps host on `http://localhost:4200`:
```bash
cd samples/community/mcp/a2ui-in-mcpapps/client
yarn start
```
### Try both views in the browser
Open `http://localhost:4200` to test how the sandboxed micro-apps render A2UI payloads returned by the MCP server:
1. Keep **Generative Editor App** selected and click **Load Selected App**. The host calls `get_editor_app` and loads `ui://editor/app` (`editor.html`). Select more than 10 characters of text inside any Editor.js paragraph; the app calls `smart_editor_get_controls`, renders generated A2UI controls (`Slider`, `CheckBox`, or `MultipleChoice`) in the right-hand panel, and calls `smart_editor_apply` when you click **Generate Revision** to rewrite the passage and swap in **Accept** and **Reject** A2UI buttons.
2. Switch the selector to **Basic Counter App** and click **Load Selected App**. The host calls `get_basic_app`, mounts `ui://basic/app` (`app.html`), and delivers the initial A2UI counter surface via `ui/notifications/tool-result`. Clicking **Increase counter** inside the rendered A2UI card calls `increase_counter` on the MCP server and updates `/counter` in place.
---
## Architecture and end-to-end flow
In a native A2UI client integration, the outer host application owns `MessageProcessor` and renders A2UI components directly in its DOM. Embedding A2UI inside an MCP App moves the A2UI runtime across the iframe boundary so any standards-compliant [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) host can render A2UI surfaces unchanged:
1. The **MCP server** publishes one or more self-contained HTML bundles under `ui://` URIs (`mimeType: "text/html;profile=mcp-app"`), alongside entry tools and UI callback tools that return `EmbeddedResource` items carrying `application/a2ui+json` messages.
2. The **MCP host application** connects to the MCP server, inspects `_meta.ui.resourceUri` on the invoked tool, fetches the `ui://` HTML via `resources/read`, and mounts an outer sandbox proxy iframe (`sandbox.html`) that injects the HTML into an inner `srcdoc` iframe with `sandbox="allow-scripts"`.
3. The **embedded MCP App** runs inside that opaque-origin `srcdoc` frame. It bundles its own A2UI web renderer (`MessageProcessor`, component catalogs, and `