A2ui Development

A2UI Protocol Development Guide

Reference for Google's A2UI (Agent-to-UI) protocol — a declarative wire format that lets an agent describe rich, interactive UI as structured JSON instead of executable code or raw HTML.

When to Use This Skill

• Implementing an agent backend that needs to render forms, cards, lists, or other rich widgets — not just chat text
• Building a native A2UI renderer (web, mobile, or desktop) that consumes createSurface/updateComponents/updateDataModel messages
• Parsing or emitting A2UI messages by hand, without adopting a full ready-made renderer SDK
• Validating a hand-built A2UI payload against the official schema
• Debugging surface/component/data-model synchronization issues

Dependencies

A2UI has many ready-made renderer/solution packages across languages. This skill deliberately does not teach any of them as "the way" to implement A2UI — the goal is understanding the wire format well enough to emit/consume it natively. The packages below are useful only as a schema/type reference to validate against:

Intentionally out of scope (full ready-made solutions, not covered here): a2ui-agent-sdk (PyPI — pulls in google-adk, google-genai, a2a-sdk), @a2ui/react, @a2ui/lit, @a2ui/angular, @copilotkit/a2ui-renderer, a2ui-vue, a2ui-shadcn, and similar. Reach for these only if you've decided you don't need to understand the wire format — this skill assumes you do.

Canonical source of truth, no package required: github.com/a2ui-project/a2ui/specification/{version}/json/ and .../catalogs/basic/ — the actual versioned JSON Schema and catalog files, fetchable directly.

Official References

Version Status

Message Types

Every A2UI message is a JSON envelope with a version field plus exactly one of these keys:

Client capability negotiation (which catalogs a client can render) happens via transport metadata — a supportedCatalogIds array — not as an A2UI message itself.

Message Flow

Typical surface lifecycle

createSurface (surfaceId, catalogId)
└── updateComponents (surfaceId, components: [...])
    └── updateDataModel (surfaceId, path: "/", value: {...})
        └── updateDataModel (surfaceId, path: "/user/name", value: "Alice")  (×N, incremental)
deleteSurface (surfaceId)

Interactive form round-trip

Agent: createSurface -> updateComponents (TextField bound to /form/name)
Client: user types "Alice" -> client-side write to /form/name (no message to agent required)
Agent: (reads the updated data model back via whatever channel this project already uses)
Agent: updateDataModel (path: "/form/status", value: "submitted")

Relationship to AG-UI

A2UI and AG-UI are separate protocols, explicitly designed to be used together or independently — neither requires the other. AG-UI covers the agent event/run lifecycle (text streaming, tool calls, reasoning, state sync); A2UI covers UI rendering (surfaces, components, data binding). A2UI works fully standalone over plain SSE/WebSockets/REST with zero AG-UI involvement. The two can also be combined — e.g. carrying an A2UI message as the payload of an AG-UI CUSTOM event — if a project already streams AG-UI and also wants rich UI. Full detail, including which approach to pick and a worked example of combining them, is in references/agui-relationship.md.

Detailed Guides

• Message Structures Reference — full JSON shapes, component/catalog model, data-binding syntax, version differences → references/message-structures.md
• Frontend (Client) Guide — building a native renderer: flat-list-to-tree, JSON Pointer resolution, reactive updates → references/frontend-guide.md
• Backend (Agent) Guide — constructing and validating messages natively, transport options → references/backend-guide.md
• AG-UI Relationship — standalone vs. combined use, and a worked A2UI-over-AG-UI example → references/agui-relationship.md