Message Reference

Current v0.9.1 lifecycle

Message	Direction	Purpose
`createSurface`	Agent → renderer	Create a named surface and select its catalog.
`updateComponents`	Agent → renderer	Add or replace component definitions.
`updateDataModel`	Agent → renderer	Apply versioned data-model changes.
`deleteSurface`	Agent → renderer	Remove the active surface and associated state.

Messages use the application/a2ui+json media type. A surfaceId must be unique while active and may be reused only after deletion. Validate messages against the exact official v0.9 schema.

{"createSurface":{"surfaceId":"order","catalogId":"https://example.com/catalog.json"}}
{"updateComponents":{"surfaceId":"order","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Review order"}}}}]}}
{"updateDataModel":{"surfaceId":"order","path":"/","value":{"status":"draft"}}}

Renderers must reject unsupported catalogs, component types, paths, URLs, and actions. See the production security checklist.

Legacy v0.8 message reference

The following section is retained for host products that still require v0.8. Do not mix these message names into a v0.9.1 stream.

Message Types

beginRendering

Signals the client to start rendering a surface.

Schema:

{
  beginRendering: {
    surfaceId: string; // Required: Unique surface identifier
    root: string;      // Required: The ID of the root component to render
    catalogId?: string; // Optional: URL of component catalog
    styles?: object;    // Optional: Styling information
  }
}

Example:

{ "beginRendering": { "surfaceId": "main", "root": "root-component" } }

surfaceUpdate

Defines or updates UI components.

Schema:

{
  surfaceUpdate: {
    surfaceId: string; // Required: Target surface
    components: Array<{ // Required: List of components
      id: string; // Required: Component ID
      component: { // Required: Wrapper for component data
        [ComponentType]: { // Required: Exactly one component type
          ...properties // Component-specific properties
        }
      }
    }>
  }
}

Usage Notes:

Components form an adjacency list (flat structure).
Sending a component with an existing ID updates it.
Components can be added incrementally.

Example:

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

dataModelUpdate

Updates the application state (data model) for a surface.

Schema:

{
  dataModelUpdate: {
    surfaceId: string; // Required: Target surface
    path?: string;     // Optional: Path to a location in the model
    contents: Array<{  // Required: Data entries
      key: string;
      valueString?: string;
      valueNumber?: number;
      valueBoolean?: boolean;
      valueMap?: Array<{...}>;
    }>
  }
}

Usage Notes:

The contents array is LLM-friendly, avoiding generic value inference issues.
Supports granular updates via path.

deleteSurface

Removes a UI surface and its data.

Schema:

{
  deleteSurface: {
    surfaceId: string; // Required: Surface to delete
  }
}

Example:

{ "deleteSurface": { "surfaceId": "modal" } }

Message Ordering

Recommended Order:

surfaceUpdate (Define components)
dataModelUpdate (Populate data)
beginRendering (Show UI)
Subsequent surfaceUpdate / dataModelUpdate (Interactive updates)
deleteSurface (Cleanup)