Catalogs and Actions

Catalog schema

A catalog is a JSON Schema file defining what components, functions, and themes an agent can use. All A2UI JSON is validated against the chosen catalog.

{
  "catalogId": "https://myapp.com/catalog/v1",
  "components": {
    "Text": {
      "type": "object",
      "properties": {
        "text": {"type": "string"},
        "variant": {"type": "string", "enum": ["h1", "h2", "h3", "h4", "h5", "body", "caption"]}
      },
      "required": ["text"]
    },
    "StockTicker": {
      "type": "object",
      "properties": {
        "symbol": {"type": "string"},
        "refreshInterval": {"type": "number", "default": 5000}
      },
      "required": ["symbol"]
    }
  },
  "functions": [
    {
      "name": "openUrl",
      "parameters": {
        "type": "object",
        "properties": {
          "url": {"type": "string", "format": "uri"}
        },
        "required": ["url"]
      }
    }
  ],
  "theme": {
    "primaryColor": {"type": "string"},
    "fontFamily": {"type": "string"}
  }
}

Catalog negotiation (3-step handshake)

1. Agent advertises: Agent optionally lists supported catalogs (e.g., in A2A AgentCard)
2. Client sends preferences: Include supportedCatalogIds in message metadata (required)
3. Agent selects: Picks best matching catalog when creating a surface; locked for the surface lifetime

// Client metadata in every outgoing message
{
  "a2uiClientCapabilities": {
    "supportedCatalogIds": [
      "https://a2ui.org/specification/v0_9/basic_catalog.json",
      "https://myapp.com/catalog/v1"
    ]
  }
}

Building custom catalogs

Use the catalog build tool to assemble catalogs from multiple source files:

uv run tools/build_catalog/assemble_catalog.py \
  base_components.json \
  custom_components.json \
  --extend-basic-catalog \
  --output-name my-catalog \
  --catalog-id "https://myapp.com/catalog/v1" \
  --version "1.0.0" \
  --out-dir ./catalogs

Options:

• --extend-basic-catalog: Include all standard A2UI components
• --output-name: Output filename (without extension)
• --catalog-id: URI identifier for the catalog
• --version: Semantic version string

Catalog versioning

• Any structural change (new component, new property, rename, removal) requires a new version
• Metadata-only changes (descriptions, typos) do not require versioning
• Include version in the catalogId URI: https://myapp.com/catalog/v2

Two-phase validation

1. Agent-side: Validate generated JSON against catalog schema before sending
2. Client-side: Validate received messages on receipt

Error reporting:

{
  "version": "v0.9",
  "error": {
    "code": "VALIDATION_FAILED",
    "surfaceId": "flight-card-123",
    "path": "/components/FlightCard/flightNumber",
    "message": "Missing required property 'flightNumber' in component 'FlightCard'."
  }
}

Client-to-server actions

Server events

Dispatch user actions to the agent for processing:

{
  "id": "book-btn",
  "component": "Button",
  "child": "btn-label",
  "action": {
    "event": {
      "name": "submit_booking",
      "context": {
        "date": {"path": "/booking/date"},
        "guests": {"path": "/booking/guests"}
      }
    }
  }
}

The context object resolves data binding paths at click time and includes resolved values in the action payload sent to the agent.

Local function calls

Execute client-side functions without contacting the agent:

{
  "action": {
    "functionCall": {
      "call": "openUrl",
      "args": {"url": "https://example.com/help"}
    }
  }
}

Functions must be defined in the catalog's functions array.

Validation checks

Auto-disable buttons until conditions are met:

{
  "id": "submit-btn",
  "component": "Button",
  "child": "btn-text",
  "action": {
    "event": {"name": "submit_form"}
  },
  "checks": [
    {
      "condition": {"call": "required", "args": {"value": {"path": "/email"}}},
      "message": "Email is required"
    },
    {
      "condition": {"call": "required", "args": {"value": {"path": "/name"}}},
      "message": "Name is required"
    }
  ]
}

Data model sync

Enable with sendDataModel: true in createSurface. The client attaches its entire data model as a2uiClientDataModel metadata to every outgoing message. This enables stateless agents that don't need to track form state.

Security considerations

• Sandboxed execution: No arbitrary code runs - only declarative JSON
• Data model isolation: Each surface has its own isolated data model
• Orchestrator responsibility: Strip a2uiClientDataModel metadata before forwarding to sub-agents to prevent cross-agent data leakage
• Surface ownership: Route actions to the agent that owns the surface via surfaceId

A2UI Component Reference

Component categories

Layout components

Row - Horizontal layout container.

Column - Vertical layout container. Same properties as Row but axes are swapped.

List - Renders a collection of items. Supports static children or dynamic templates.

Display components

Text - Renders text content.

Image - Displays an image.

Icon - Renders a named icon from the catalog's icon set.

Divider - Visual separator.

Video - Embeds video content with a source URL.

Interactive components

Button - Clickable action trigger.

TextField - Text input with bidirectional data binding.

CheckBox - Boolean toggle with bidirectional binding.

Slider - Numeric range input.

DateTimeInput - Date and/or time picker.

MultipleChoice / ChoicePicker - Selection from options.

Container components

Card - Visual grouping container with optional elevation/border.

Modal - Overlay dialog triggered by an entry point component.

Tabs - Tabbed navigation container.

Common properties (all components)

v0.8 vs v0.9 syntax comparison

v0.8 component:

{"id": "title", "component": {"Text": {"text": {"literalString": "Hello"}, "usageHint": "h1"}}}

v0.9 component:

{"id": "title", "component": "Text", "text": "Hello", "variant": "h1"}

v0.8 children:

{"children": {"explicitList": ["child-1", "child-2"]}}

v0.9 children:

{"children": ["child-1", "child-2"]}

A2UI Message Reference

A2UI uses JSON Lines (JSONL) for streaming - each line is a complete JSON object representing one operation. Messages flow from agent to client via any transport.

v0.9 message types (current draft)

createSurface

Creates a new UI surface. Must be sent before any component or data updates.

{
  "version": "v0.9",
  "createSurface": {
    "surfaceId": "booking-form",
    "catalogId": "https://a2ui.org/specification/v0_9/basic_catalog.json",
    "sendDataModel": true
  }
}

• catalogId is required in v0.9
• sendDataModel: true enables the client to attach its data model to outgoing messages

updateComponents

Adds or updates components on an existing surface.

{
  "version": "v0.9",
  "updateComponents": {
    "surfaceId": "booking-form",
    "components": [
      {"id": "title", "component": "Text", "text": "Reservation", "variant": "h1"},
      {"id": "name-input", "component": "TextField", "label": "Your Name", "value": {"path": "/guest/name"}},
      {"id": "row-1", "component": "Row", "children": ["title", "name-input"], "justify": "spaceBetween"}
    ]
  }
}

• Components are upserted by id - sending a component with an existing ID updates it
• Order within the array does not matter; parent-child relationships use ID references

updateDataModel

Sets or updates data in the surface's data model.

{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "booking-form",
    "path": "/guest",
    "value": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  }
}

• path uses JSON Pointer (RFC 6901) notation
• Granular updates: send only the changed path, not the entire model
• Supports nested paths: "/guest/preferences/dietary"

deleteSurface

Removes a surface and all its components and data.

{
  "version": "v0.9",
  "deleteSurface": {
    "surfaceId": "booking-form"
  }
}

error

Report errors back to the agent.

{
  "version": "v0.9",
  "error": {
    "code": "VALIDATION_FAILED",
    "surfaceId": "booking-form",
    "path": "/components/FlightCard/flightNumber",
    "message": "Missing required property 'flightNumber'"
  }
}

v0.8 message types (stable)

surfaceUpdate

Creates or updates a surface with components. Serves as both create and update.

{
  "surfaceUpdate": {
    "surfaceId": "main",
    "components": [
      {"id": "header", "component": {"Text": {"text": {"literalString": "Hello"}, "usageHint": "h1"}}}
    ]
  }
}

dataModelUpdate

Sets data in the surface's data model using typed value fields.

{
  "dataModelUpdate": {
    "surfaceId": "main",
    "contents": [
      {"key": "user", "valueMap": [
        {"key": "name", "valueString": "Jane"},
        {"key": "age", "valueInt": 30},
        {"key": "active", "valueBool": true}
      ]}
    ]
  }
}

Value types: valueString, valueInt, valueFloat, valueBool, valueMap, valueList.

beginRendering

Signals the client to start rendering. Required in v0.8 before UI appears.

{
  "beginRendering": {
    "surfaceId": "main",
    "root": "header"
  }
}

• root specifies the top-level component ID to start the render tree

deleteSurface

Same as v0.9.

Message ordering rules

1. Components must be defined before they are referenced as children
2. createSurface (v0.9) or surfaceUpdate (v0.8) must come before data/component updates
3. In v0.8, beginRendering must come after all initial components and data are sent
4. After initial render, component and data updates can arrive in any order
5. Different surfaces operate independently - no ordering constraints between them

Client-to-server action payload (v0.9)

When a user interacts with an action-bearing component:

{
  "version": "v0.9",
  "action": {
    "name": "submit_reservation",
    "surfaceId": "booking-form",
    "sourceComponentId": "submit-btn",
    "timestamp": "2026-02-25T10:40:00Z",
    "context": {
      "time": "7:00 PM",
      "size": 4
    }
  }
}

• context values are resolved from data binding paths defined in the component's action
• Client includes a2uiClientCapabilities with supportedCatalogIds in message metadata

Transport options

Renderer Development Guide

Available renderers

All web renderers share @a2ui/web-lib (web_core) as their foundation.

web_core modules

Key imports

import type * as Types from '@a2ui/web_core/types/types';
import type * as Primitives from '@a2ui/web_core/types/primitives';
import { A2uiMessageProcessor } from '@a2ui/web_core/data/model-processor';
import { MessageProcessor, SurfaceModel } from '@a2ui/web_core/v0_9';
import * as Styles from '@a2ui/web_core/styles/index';

Implementation checklist

Message processing and state

• Surface management keyed by surfaceId - handle multiple surfaces independently
• Component buffering as Map<string, Component> per surface, store by id
• Resolve component references via container properties (children, child, entryPoint)
• Separate data model store per surface
• Handle adjacency list contents format for v0.8 data model

Rendering logic

• Buffer all surfaceUpdate/dataModelUpdate messages, wait for beginRendering before initial render (v0.8)
• For v0.9, render on createSurface receipt
• Start render from specified root component ID (v0.8) or first component (v0.9)
• Data binding resolution order: Check literal* values first, then resolve path references
• Support relative binding in dynamic list templates (paths scoped to array item)
• Dynamic lists: Resolve template.dataBinding path, iterate data items, render template.componentId for each

Client-to-server communication

• Construct userAction payload on user interaction
• Resolve action.context bindings at interaction time (not at render time)
• Include a2uiClientCapabilities with supportedCatalogIds in every outgoing A2A message metadata
• Send error messages for failed data binding or unknown component types

Component mapping

Map A2UI component types to native framework widgets:

// Example component registry
const componentMap: Record<string, ComponentRenderer> = {
  'Text': renderText,
  'Button': renderButton,
  'TextField': renderTextField,
  'Card': renderCard,
  'Row': renderRow,
  'Column': renderColumn,
  'List': renderList,
  'Image': renderImage,
  'CheckBox': renderCheckBox,
  'DateTimeInput': renderDateTimeInput,
  'Slider': renderSlider,
  'Modal': renderModal,
  'Tabs': renderTabs,
  'Icon': renderIcon,
  'Divider': renderDivider,
  'Video': renderVideo,
  'MultipleChoice': renderMultipleChoice,
};

function renderComponent(model: ComponentModel): FrameworkElement {
  const renderer = componentMap[model.type];
  if (!renderer) {
    console.warn(`Unknown component type: ${model.type}`);
    return renderFallback(model);
  }
  return renderer(model);
}

Custom component registration

Extend the renderer with application-specific components:

// Register custom component
componentMap['StockTicker'] = (model: ComponentModel) => {
  const symbol = resolveBinding(model.properties.symbol);
  const interval = model.properties.refreshInterval ?? 5000;
  return createStockTickerWidget(symbol, interval);
};

Safety rules for custom components:

• Only register trusted, reviewed components
• Validate all properties before use
• Process user input through sanitization
• Restrict API access from custom component code