A2UI reference

> For agent authors: which parts of the A2UI interface format Agent Taskbay renders, what it refuses, and the safety rules that hold whatever an agent sends.

A2UI lets an agent describe an interface as declarative JSON that the client renders with its own components. Agent Taskbay renders a small, fixed subset of A2UI v0.9 and treats everything else as inert. It is experimental: it has not been tested against a real third-party A2UI agent or the official schemas (#25); it was exercised with the repository's own fixture agent and unit tests.

Opt-in and detectionCopy Anchor Link

Surfaces render only for agents whose stored card advertises the extension URI (negotiation rules). Otherwise the part is shown as an ordinary data part. For an agent that advertises it, every message the console sends activates the extension and includes this metadata so the agent can pick a catalog the console renders:

{ "a2uiClientCapabilities": { "v0.9": { "supportedCatalogIds": ["https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json"] } } }

The chat composer waits until the agent's card is known, because the card decides which extensions a message activates.

Where surfaces appearCopy Anchor Link

Surfaces are rendered in the Chat screen only. They are not shown on the task or approval pages and are not mapped to AG-UI (#24). A surface is the agent's request for input, like an INPUT_REQUIRED question. It is never an approval; use the approval request extension when a person must authorize an action.

Server-to-client envelopesCopy Anchor Link

Each array element is one envelope: an object with version: "v0.9" and exactly one of the keys below. Surfaces are built by folding all A2UI parts of the task's agent messages, oldest first.

An invalid envelope is skipped and counted, and the rest of the array is still applied. The console shows "n invalid interface updates ignored." Unknown envelope types, a wrong version, extra top-level keys and unknown surfaces count as invalid. At most 2,000 envelopes are processed per task.

ComponentsCopy Anchor Link

Only these Basic Catalog components render. Anything else becomes a labelled inert placeholder (Unsupported component "Name"), as do missing children, unsupported child lists (templates), a missing component, nesting deeper than 20 levels and cycles.

Not rendered (inert placeholder): Image, Icon, Video, AudioPlayer, List and templates, Tabs, Modal, DateTimeInput, Slider (#22), and any component outside the Basic Catalog.

Values and bindingsCopy Anchor Link

A value is a literal string, number or boolean, or a binding { "path": "/absolute/pointer" } with exactly one key. Relative paths, function calls, arrays and null resolve to nothing. Function calls, checks and validationRegexp are not evaluated (#23): a regular expression from an agent is a denial-of-service risk.

The agent's data model is built only by updateDataModel. What the person types is kept as a separate overlay in the browser, so an agent update never erases it, and it is not sent anywhere until a button action sends bound values.

Actions: client to serverCopy Anchor Link

A Button with action: { "event": { "name": "...", "context": { "key": <literal or binding> } } } sends one message on the same task, carrying a data part of media type application/a2ui+json:

{
  "version": "v0.9",
  "action": { "name": "confirm_deploy", "surfaceId": "main", "sourceComponentId": "confirm", "timestamp": "2026-10-06T20:00:00.000Z", "context": { "env": "staging" } }
}

name is 1 to 128 characters. Context values are resolved from the effective data model (agent model plus the person's edits) at click time; unresolvable values are omitted; the resolved context may not exceed 16 KB, otherwise the button is disabled. The message goes through the normal command path, so it needs the operate permission and is rate limited, idempotent and audited like a typed reply.

Safety rulesCopy Anchor Link

• Components are React elements chosen by the console. Every agent string is rendered as text; nothing is parsed as markup. (The fixture agent sends <b>not bold</b><img src=x onerror=...> as caption text to check this.)
• No URL is loaded, followed or opened by the renderer. Images, video, audio and openUrl are not implemented.
• No code, function or expression from an agent is evaluated.
• Prototype-polluting pointer segments are rejected.
• Sizes are bounded (see limits below), and a surface cannot grow without limit.
• The page's Content-Security-Policy additionally restricts connect-src to the same origin and forbids framing.

When it failsCopy Anchor Link

LimitsCopy Anchor Link

• A subset of the Basic Catalog: no media, lists, tabs, modals, date or slider inputs; no catalog functions or validation checks (#22, #23).
• Chat screen only; no merge rule yet for an agent update that arrives after a person edited a field (#24).
• v0.9 only; no other A2UI versions or custom catalogs.
• Not verified against third-party A2UI agents or the official schemas (#25).

Further readingCopy Anchor Link

• Decision record: A2UI renderer

RelatedCopy Anchor Link

• Rich content
• Extensions overview
• Build an agent for Taskbay
• AG-UI adapter