Overview
Provides the end-to-end specification and hands-on workflow for A2UI v0.8: UI generation (surfaceUpdate/dataModelUpdate/beginRendering/deleteSurface) and client event callback (action → userAction → A2A).
Workflow (must be followed)
- Confirm Catalog and surfaceId: default to the standard Catalog, and all component ids must be unique.
- Design the component graph: a flat component list + children/child to assemble the tree.
- Write the data model: dataModelUpdate fills the ValueMap and binds via path.
- Trigger rendering: send beginRendering specifying root.
- Interaction callback: component action.context binds data, and the client parses it into userAction.
- Incremental updates: structural changes use surfaceUpdate, data changes use dataModelUpdate.
Generation-side rules
- Each message can have only one top-level key: beginRendering / surfaceUpdate / dataModelUpdate / deleteSurface.
- Each component in surfaceUpdate.components can have only one component type key.
- children uses explicitList or template (template must contain componentId and dataBinding).
- dataModelUpdate.contents uses only ValueMap (valueString/valueNumber/valueBoolean/valueMap).
- For BoundValue, choose either literal* or path; relative paths are resolved via dataContextPath.
Client event rules
- userAction requires: name, surfaceId, sourceComponentId, timestamp.
- action.context must be resolved to final values (paths must not be retained).
- When sending a DataPart, mimeType must match the server side; the specification is application/json+a2ui.
- Every A2A message carries a2uiClientCapabilities (supportedCatalogIds).
Compatibility notes
- TextField field naming differs between the schema and the renderer: the schema commonly uses textFieldType, while the Lit v0.8 type uses type. Field alignment or mapping must be done during integration.
- Modal's entryPointChild is assigned slot="entry" by the renderer; do not reuse the slot name.
Reference materials (load as needed)
- Protocol and data model:
references/protocol-v0-8.md - Standard component list:
references/standard-catalog-v0-8.md - Schema location:
references/schemas-v0-8.md - JSONL template example:
references/examples-jsonl-v0-8.md - Snippet library:
references/snippets-v0-8.md - Client event parsing:
references/client-events-v0-8.md - A2A extension and capability negotiation:
references/a2a-extension-v0-8.md - End-to-end workflow:
references/sample-client-flow.md - End-to-end request template:
usage.md