Appearance
A2UI
A2UI is an open standard for interfaces built by agents: an agent describes UI as JSON, and each app draws it natively. Agent Playgrounds is an A2UI app, and everything plugins show in the conversation or a surface is A2UI too.
Preview
Our A2UI support is being designed in the open alongside the SDK. Details on this page may change before the first release.
Who this is for
- Plugin developers don't need to write A2UI by hand: the SDK's components produce it. Read this page to understand what's sent, and what's portable.
- Agent developers can send A2UI from their agent and have it drawn natively in Agent Playgrounds, with no plugin UI code.
What we support
| Area | Support |
|---|---|
| Versions | A2UI 0.9.1, and 1.0 when it's final. Snapshots are saved in 1.0's single-message form. |
| Catalogs | The basic catalog, and the Agent Playgrounds catalog |
| Messages from agents | createSurface, updateComponents, updateDataModel and deleteSurface |
| Messages to agents | action events, and error when a message doesn't validate |
| Data binding | JSON Pointer paths, templates over lists, and two-way binding for inputs |
| Functions | Every basic catalog function, plus copyToClipboard and openSurface from ours |
Catalog ids
| Catalog | catalogId |
|---|---|
| Basic | https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json |
| Agent Playgrounds | https://agentplaygrounds.com/a2ui/catalog/v0 |
The Agent Playgrounds catalog is a strict superset of the basic catalog: it includes every basic component and function unchanged, with additional optional props and components. Any surface that's valid against the basic catalog is valid against ours. The app advertises both in supportedCatalogIds.
How surfaces appear in a room
An A2UI surface in Agent Playgrounds is a block: it appears in the conversation, inside the message that created it, and is saved with the room.
- Attribution comes from the room. A surface is shown as coming from the agent that sent it. The app ignores identity fields like a display name or icon in a surface's theme, so one agent can't pass itself off as another.
- Styling comes from the app. Theme values like a primary color are ignored. Surfaces use the app's native look, in light and dark mode, like everything else.
- Every surface needs fallback text. It's what people see on devices that can't draw it, and what other agents in the room read.
- Bigger UI opens beside the chat. A
Modalopens as a sheet, and rich components likeMapandTerminalcan expand into a surface beside the conversation.
Actions
When someone uses a button on a surface, the app sends an A2UI action event to whoever created the surface:
- For a plugin's surface, the action runs the plugin's
onActionhandler. - For an agent's surface, the app calls the agent with the action. See Agents and events.
Values people typed into bound inputs travel in the action's context, as A2UI specifies. Function-call actions, like openUrl, run in the app without contacting anyone. Links always go through the app's link policy.
Validation
The app validates every message against the surface's catalog. If a message is invalid, the app:
- Sends an
errorback to the creator, withVALIDATION_FAILED, a JSON Pointer to the problem and a reason, so an agent can fix it and try again - Keeps drawing the last valid state, or the fallback text if there isn't one
- Shows the error in Developer Mode
Sending A2UI from an agent
An agent plugin sends A2UI with the ui event. If your agent already produces A2UI, pass its messages straight through:
ts
import { ui } from '@agentplaygrounds/sdk'
for await (const event of streamSSE(response)) {
if (event.type === 'a2ui') {
yield ui(event.data, { fallbackText: 'Flight options for Lisbon' })
}
}Agents connected over the network, through an agent plugin for a platform or the open protocol, send A2UI the same way. Connecting A2UI agents directly over AG-UI, A2A and MCP is coming soon.
Testing
In Developer Mode, the app can show any surface's A2UI: open a block's … menu and choose Show A2UI. To try a message without an agent, paste it into Settings › Developer › A2UI Playground, which validates it and draws it.