Skip to content

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 ​

AreaSupport
VersionsA2UI 0.9.1, and 1.0 when it's final. Snapshots are saved in 1.0's single-message form.
CatalogsThe basic catalog, and the Agent Playgrounds catalog
Messages from agentscreateSurface, updateComponents, updateDataModel and deleteSurface
Messages to agentsaction events, and error when a message doesn't validate
Data bindingJSON Pointer paths, templates over lists, and two-way binding for inputs
FunctionsEvery basic catalog function, plus copyToClipboard and openSurface from ours

Catalog ids ​

CatalogcatalogId
Basichttps://a2ui.org/specification/v0_9/catalogs/basic/catalog.json
Agent Playgroundshttps://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 Modal opens as a sheet, and rich components like Map and Terminal can 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 onAction handler.
  • 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:

  1. Sends an error back to the creator, with VALIDATION_FAILED, a JSON Pointer to the problem and a reason, so an agent can fix it and try again
  2. Keeps drawing the last valid state, or the fallback text if there isn't one
  3. 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.

All your Agents, playing nicely in one Playground.