Components and Structure

A2UI represents a surface as a flat list of component objects. Components refer to children by ID, so an agent can stream and replace individual definitions without regenerating a deeply nested tree.

A v0.9 component list

{
  "version": "v0.9.1",
  "updateComponents": {
    "surfaceId": "main",
    "components": [
      {"id":"root","component":"Column","children":["greeting","actions"]},
      {"id":"greeting","component":"Text","text":"Hello","variant":"h2"},
      {"id":"actions","component":"Row","children":["cancel","confirm"],"justify":"end"},
      {"id":"cancel-label","component":"Text","text":"Cancel"},
      {"id":"cancel","component":"Button","child":"cancel-label","action":{"event":{"name":"cancel"}}},
      {"id":"confirm-label","component":"Text","text":"Confirm"},
      {"id":"confirm","component":"Button","child":"confirm-label","variant":"primary","action":{"event":{"name":"confirm"}}}
    ]
  }
}

One component uses the conventional ID root. Each component has a unique id, a string component type, and properties defined by the selected Catalog.

Static and dynamic children

A fixed child list is an array of component IDs:

{"id":"toolbar","component":"Row","children":["back","title","menu"]}

For a data-driven list, ChildList also supports the template structure defined in the v0.9 common types. Validate that form against the exact schema rather than copying an older v0.8 explicitList or dataBinding example.

Literal and bound values

A dynamic property can use a literal value or a JSON Pointer path:

{"id":"fixed","component":"Text","text":"Welcome"}
{"id":"bound","component":"Text","text":{"path":"/user/name"}}

When the data model changes at /user/name, the renderer updates the bound component. The host should restrict writable paths and validate value types and sizes.

Incremental updates

Sending updateComponents with a new ID adds a definition. Sending the same ID replaces that definition. To stop displaying a child, update its parent’s child list. Deleting the whole surface uses deleteSurface and should release all associated state.

This behavior makes stable IDs important. It also means an update should include the complete new definition for a replaced component rather than assuming omitted properties will merge.

Catalog boundary

The Basic Catalog supplies common layout, text, media, input, and container components. A host may negotiate a custom Catalog for product-specific components such as charts or maps. The renderer must reject types and properties outside the negotiated Catalog.

See the component reference, message reference, and official v0.9.1 protocol.