know.2nth.ai › Agents › A2UI
agents · A2UI · Skill Leaf

The agent describes the screen. Your app draws it.

A2UI is Google's open protocol for agent-driven interfaces. Instead of replying with a paragraph, the agent streams JSON that names components from a catalog your app has approved, and your app renders them with its own native widgets. Version 1.0 shipped on 11 November 2026. It is the first release stable enough to build on, and it is still a young, Google-run project with an uneven renderer story.

Spec v1.0 · 11 Nov 2026 Apache 2.0 Declarative JSON, no code on the wire Web, Flutter, SwiftUI Android still on 0.9.1

Try it in the lab → A model replies in A2UI and the page draws the screen, with the JSON beside it.

A format for screens, not a UI framework.

Most agents answer in text. Ask one to rebook a flight and it writes out three options, waits for you to type "the second one", then asks you to confirm in another message. A2UI lets the same agent answer with a card, a date picker and a button. The agent does not send HTML or JavaScript. It sends a description: which components to show, how they nest, and what data fills them.

The app on the other end owns the rendering. It registers a catalog of components it is willing to draw, and maps each one to a real widget in its own design system. The agent can only compose from that catalog. Google's launch post put the pitch as "safe like data, but expressive like code".

The project went public on 15 December 2025 at v0.8, moved to v0.9 on 17 April 2026, and reached v1.0 on 11 November 2026. It lives at a2ui.org and github.com/a2ui-project/a2ui under Apache 2.0.

The four ideas

Surface — one screen or card the agent controls, identified by a surfaceId. Catalog — the approved set of components and functions; the renderer advertises which catalogs it supports. Data model — a JSON object held separately from the layout, so a value can change without rebuilding the screen. Actions and functions — how a tap or a form submit travels back to the agent, and how each side can call a registered function on the other.

Who runs it

A2UI is a Google project. Contributions need Google's Contributor License Agreement, and nothing on the project's site or repository says it has been handed to a foundation. That is a real difference from A2A, which Google donated to the Linux Foundation. The licence is permissive, so the code is yours to use; the direction of the spec is Google's to set.

Ten message types, split by direction.

The agent streams JSON messages to the renderer. The renderer sends user actions, function calls and errors back. Layout and data are separate, which is what makes live updates cheap.

DirectionMessageWhat it does
Agent → renderercreateSurfaceOpens a surface. In 1.0 it can carry the components and the starting data in the same message.
updateComponentsAdds or replaces components on an existing surface.
updateDataModelChanges one value at a path. A null value deletes the key.
deleteSurfaceRemoves the surface.
callRendererFunctionAsks the app to run a catalog function and return the result.
agentFunctionResponseAnswers a function call the app made.
Renderer → agentactionReports a user interaction, such as a button press.
callAgentFunctionAsks the agent side to run a function, for example an availability check.
rendererFunctionResponseAnswers a function call the agent made.
errorReports a validation or execution failure, with a code and a JSON pointer to the fault.

A complete screen in one message. This is the spec's own small example, re-indented: a column holding one text component, bound to a value in the data model.

{
  "version": "1.0",
  "createSurface": {
    "surfaceId": "user_profile_card",
    "catalogId": "https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json",
    "sendDataModel": true,
    "components": [
      { "id": "root", "component": "Column", "children": ["user_name"] },
      { "id": "user_name", "component": "Text", "text": { "@path": "/name" } }
    ],
    "dataModel": { "name": "John Doe" }
  }
}

Three details matter. Components are a flat list with IDs, not a nested tree, so the model can emit them in any order and patch one later. {"@path": "/name"} is a data binding written as a JSON Pointer. And catalogId is an identifier, not a URL the renderer fetches. Changing the name afterwards is one small message:

{
  "version": "1.0",
  "updateDataModel": {
    "surfaceId": "user_profile_card",
    "path": "/name",
    "value": "Jane Doe"
  }
}

What happens when the model gets it wrong

The renderer validates every message against the catalog. A failure comes back as an error with a code (VALIDATION_FAILED, UNALLOWED_PARENT, UNALLOWED_CHILD), the surface, a JSON pointer to the bad field and a one-sentence reason. The spec says these errors "can be reported back to the LLM in a subsequent prompt, allowing it to self-correct". Note the word can: the retry loop is yours to build. The protocol supplies the error, not the repair.

A stable target, and one breaking rename.

The 1.0 release is mostly about making the protocol dependable enough to ship against. If you built on 0.9, it is a migration, not a version bump.

ChangeWhat it means in practice
Screen in one messagecreateSurface can embed components and data, so a new screen no longer needs three messages to appear.
Function calls both waysThe agent can call the app, and the app can call the agent, each with a structured response. Google's example is a reservation picker that checks availability on the spot.
Mixed catalogsOne surface can use components from more than one catalog, such as the basic set plus your own.
The @ prefixBindings and function calls are now {"@path": ...} and {"@call": ...}. 0.9 used a bare path. The migration guide warns against a blanket find-and-replace, because path is still a plain field elsewhere.
Themes removedtheme is gone from createSurface. Styling belongs to the app, not the agent.
Accessibility and metadataComponents carry @accessibility, @checks and @metadata keys.
Renamed roles"Client" became "renderer" and "server" became "agent" throughout the spec.

The pace is the risk

Three versions in eleven months, with v0.8 already marked deprecated and a syntax break between 0.9 and 1.0. The project is collecting requirements for 1.1. A "1.0" label from a team moving this fast means the wire format is stable for now, not that the churn is over. Pin your renderer and SDK versions.

The model writes less. The server fills in the rest.

Having a model type out verbose JSON is slow and costs tokens. Two additions from October 2026 attack that: a compact format the model writes instead of JSON, and macros that expand on your server.

Inference formats. The agent SDKs separate what the model writes from what goes over the wire. The wire format is always A2UI JSON. The inference format is swappable, and since October the default is A2UI Express: a Python-style syntax, one statement per line, that the SDK compiles into validated JSON. It is available in the Python, TypeScript and Dart agent SDKs. The renderer never sees it.

from a2ui.processor import A2uiGenerator, CatalogConfig
from a2ui.inference_formats import ExpressFormatFactory

catalog = CatalogConfig.from_path("catalog.json")
generator = A2uiGenerator(
    ...,  # catalog and other settings, see the SDK docs
    inference_format_factory=ExpressFormatFactory(),
)
processor = generator.create_processor(renderer_capabilities)

# The SDK writes the prompt section that teaches the model the format
system_prompt = f"{instructions}\n\n{processor.prompt_snippet}"

# ...call your model, then turn its reply into validated A2UI messages
parts = processor.parse_response(model_reply)

What Express saves. The project's own benchmark (54 samples, basic catalog, a Gemini Flash model, temperature 0) reports the model's output dropping from a median of 807 tokens to 297, and input from 10,980 to 6,000, with the same first-try pass rate of 98.1% either way. That is roughly the "up to 3x fewer tokens" Google quotes. It is a vendor benchmark on a vendor model, and nobody independent has rerun it yet.

Macros. A macro is a Python function that returns components. The model writes a short call; the SDK expands it on the server before anything reaches the renderer.

from a2ui.transformers.macros import macro

@macro
def FlightCard(flight: str, route: str, status: DynamicString) -> Card:
    """Args: ...  (the decorator reads these to describe the macro to the model)"""
    return Card(...)  # a Column of Text components, e.g. Text(text=f"### {flight}")

# What the model writes, in Express:
#   root = FlightCard("OS 87", "Vienna to New York", $/flight/status)

Macros can also look data up. The model passes an ID, such as an order number, and your code fetches the record and fills in the values. Every figure on screen then comes from your system, not from the model's memory of it. Macros are Python-only today; the docs say other languages come next.

Read the big numbers carefully

A demo doing the rounds shows 170 characters of model output becoming about 6,000 characters of JSON, a 35x ratio. That measures one screen where macros did most of the work, in characters, not tokens. Express on its own is about 3x. Google also cites "up to 80x" faster layout decisions, which refers to a different approach entirely: handing layout choices to a System One model such as Jev. That path is on the roadmap as official SDK support, not shipped.

What macros do and don't do for privacy

If a macro fetches the data, the model only needs the ID, so account balances or patient details need not enter the prompt at all. That is a property of how you design the agent. The docs do not promise it, and it stops being true the moment you also pass that data to the model for reasoning. The docs' actual warning points the other way: treat macro arguments as untrusted model output and check every ID against your backend.

Renderers, transports and MCP Apps.

The protocol is only useful where a renderer exists. Web and Flutter are the strong path. Native Android is behind.

RendererPlatformStatus at 1.0 launch
React, Angular, LitWebOfficial. Share a web_core library with a v1_0 entry point.
FlutteriOS, Android, web, desktopOfficial. Also runs inside MCP Apps.
SwiftUIApple platformsOfficial, in the main repository.
Jetpack ComposeAndroidOfficial, but on 0.9.1. Google says 1.0 is "coming soon" and gives no date.
LynxByteDance's cross-platform frameworkCommunity, by ByteDance. On 0.9, adapting to 1.0.
Vue, Svelte, React Native, terminal and othersVariousCommunity. Most are on 0.8 or 0.9; a few have reached 1.0.

Even Google's own products are mid-migration: the launch post says Gemini "supports A2UI 0.9.1 today" and that Gemini Enterprise is being upgraded. Named outside adopters are Atlassian, which is bringing it to Jira, Alation, ByteDance and Bloomberg. Bloomberg is named once with no detail.

Transport. A2UI does not define its own connection. The spec names AG-UI as the standard binding for agent-to-user traffic, with an extension for carrying A2UI over A2A and a mapping onto MCP tool results and resources. Server-Sent Events and WebSockets work too. Plain REST is listed with the caveat that it cannot stream.

A2UI and MCP Apps are different answers

An MCP App is a sandboxed web page shown in an iframe inside an assistant such as Claude or Gemini. It can look like anything, and it looks like itself rather than like the host. A2UI sends a description and lets the host draw it natively. Google and the MCP Apps authors describe three ways to combine them: send A2UI over an MCP server, embed an MCP App inside an A2UI surface, or bundle an A2UI renderer inside an MCP App so it appears in assistants that have no A2UI support of their own. The last route has limits worth knowing: the iframe cannot use local storage or cookies, and cannot make its own network calls.

When to build on A2UI. When to wait.

A2UI earns its place when you own the app the user is looking at and the agent's replies are really forms and choices in disguise. It adds a renderer, a catalog and a validation loop to maintain, so it has to replace enough bad chat turns to pay for that.

Use A2UI when

  • You own the web or mobile app the agent lives in
  • The agent keeps asking for dates, options and confirmations in text
  • You have a design system and want the agent held inside it
  • One agent backend must serve web and mobile at once
  • Your web stack is React, Angular or Lit, or your mobile stack is Flutter
  • Third-party or less-trusted agents will render into your app

What the catalog does not protect you from

The security argument is sound as far as it goes: no executable code crosses the wire, and an agent cannot draw a component the app has not registered. That closes script injection. It does not stop a manipulated agent from composing a misleading screen out of approved parts, putting the wrong amount on a legitimate "Confirm payment" button, or calling a function it is allowed to call at the wrong time. Treat every action coming back from a surface the way you would treat any request from an untrusted client: authorise it on the server.

Useful in your own app. Irrelevant on WhatsApp.

The local question is less about the protocol and more about where your customers actually meet your agent.

Channel first. A2UI needs a renderer inside an app you control, or an assistant that hosts MCP Apps. A lot of South African customer service runs through WhatsApp, where neither exists; WhatsApp has its own buttons and flows, on its own terms. If that is your main channel, A2UI changes nothing for you today. It becomes interesting for the banking app, the insurer's self-service portal, the internal operations console: surfaces you already own.

Android is the catch. In a market where most phones are Android, the official Compose renderer sitting a version behind is not a footnote. The practical route for a mobile team that wants 1.0 now is Flutter, which covers Android and iOS from one codebase and is not on Google's list of renderers still catching up.

Tokens are billed in dollars. Output tokens are the expensive ones, and Express cuts the output for a screen by roughly two-thirds on the project's own numbers. For a high-volume agent that renders a card on most turns, that is a real line on a rand-denominated bill, and shorter output also means the screen appears sooner on a slow connection.

POPIA. The macro pattern gives you a clean way to keep personal information out of a model hosted offshore: the model handles an order or account ID, and your server in-country fetches and fills the details. That helps with the cross-border transfer question only if you hold the line and never pass the same data to the model another way. It is an architecture you choose, not a compliance feature you switch on.

Where A2UI links in the tree.

A2UI is the presentation layer of the agent protocol stack: MCP reaches tools, A2A reaches other agents, A2UI reaches the person.

Specification, announcements and guides.

Primary sources only. The spec and the evolution guide are the ones to read before writing code; the blog posts carry the dates and the adoption claims.