Skip to content

Evolution Guide v0.9.1 → v1.0

This guide is automatically included from specification/v1_0/docs/evolution_guide.md. Any updates will automatically appear here.

For more information, see the following related documentation:

A2UI Protocol Evolution Guide: v0.9 to v1.0

This document serves as a comprehensive guide to the changes between A2UI version 0.9 (including 0.9.1) and version 1.0. It details the shifts in philosophy, architecture, and implementation, providing a reference for stakeholders and developers migrating between versions.

1. Executive summary

Version 1.0 differs from 0.9 in the following ways:

  • A new renderer-to-agent RPC mechanism allows synchronous responses to renderer actions (actionResponse) using a unique actionId.
  • Agent-to-renderer RPC function calls are supported via the callFunction message. Renderers return execution results via the functionResponse message. Runtime execution boundaries and return types are defined in catalogs and verified at runtime, rather than being validated on the wire.
  • The theme property in the catalog and surface creation message is replaced by surfaceProperties, and primaryColor is removed to separate layout from branding.
  • Components and initial data model states can be defined directly within the createSurface parameters. This allows for the creation of entire UIs in a single message, rather than a create followed by separate updates.
  • The functions field in a Catalog is now defined as a map of function name to its definition, instead of a list.
  • Standard JSON Schema metadata fields ($schema, $id, title, and description) are supported in catalogs, preventing validation failures on inline catalogs with strict property checks.
  • Identifier naming rules across all catalog entities (component names, function names, and argument keys) must conform to Unicode Standard Annex #31 (UAX #31).
  • The @index built-in function dynamically retrieves iteration indices during list template rendering. The @ prefix is reserved for core system context evaluations.
  • Standardized the names of core architectural components, renaming "client" to renderer and "server" to agent (e.g., server_to_client schemas are renamed to agent_to_renderer), because A2UI is sometimes generated on clients, and rendering sometimes happens on servers, making those terms ambiguous.

2. Changes

2.1. Catalog definition schema

  • Renamed the $defs/theme schema to $defs/surfaceProperties in the Catalog schema, and removed the primaryColor property.
  • Changed the functions property in the Catalog schema from a list to a map object, keyed by function name.
  • Added callableFrom (enum: rendererOnly, agentOnly, rendererOrAgent) to FunctionDefinition to restrict where a function can be invoked.
  • Added an optional instructions field to the Catalog schema to embed design guidelines and component usage rules directly in the catalog, replacing the external rules.txt file.
  • Supported standard JSON Schema metadata fields ($schema, $id, title, and description) in the Catalog object definition. Since the Catalog schema restricts properties with additionalProperties: false, this ensures inline catalogs containing standard schema metadata do not fail schema validation.
  • Enforced Unicode Standard Annex #31 (UAX #31) identifier naming constraints (XID_Start, XID_Continue) across component names, function names, and argument keys.

2.2. Standard catalogs (basic)

  • Added posterUrl property to the Video component in catalogs/basic/catalog.json, allowing a preview image to be displayed before the video plays.
  • Added placeholder prop to the TextField component schema.
  • Added a steps property to the Slider component schema to snap values to discrete intervals.
  • Added an optional instructions field to the Catalog schema (catalogs/basic/catalog.json) to embed Markdown guidelines/rules directly, replacing the external rules.txt file.
  • Renamed $defs/theme to $defs/surfaceProperties in the basic catalog.

2.3. Agent-to-renderer messages

  • Added actionResponse message structure (ActionResponseMessage) to allow the agent to respond to a specific action call using a unique actionId with a value or error.
  • Added callFunction message structure (CallFunctionMessage) to support agent-initiated function execution. Removed callableFrom and returnType properties from the wire payload, relying on runtime catalog verification.
  • Updated the createSurface message (CreateSurfaceMessage) to rename the theme field to surfaceProperties, and allowed passing initial components and dataModel directly inside the payload.
  • Updated all protocol version references and envelopes from v0.9 or v0.9.1 to v1.0.

2.4. Renderer-to-agent events

  • Added actionId to the action message properties, which the renderer generates if a response is expected (wantResponse: true).
  • Added the functionResponse renderer-to-agent message to return the successful result (value) of an agent-initiated function call. Function execution failures are reported via the separate error message (see next item), not via functionResponse.
  • Updated renderer error messages to support functionCallId when reporting function execution failures, enforcing mutual exclusivity with surfaceId.
  • Updated all protocol version references from v0.9 or v0.9.1 to v1.0.

2.5. Catalog definition schema

  • Added an optional instructions field to the Catalog object definition (catalog_definition.json) as a plain Markdown string to embed design guidelines directly.
  • Renamed theme capability block to surfaceProperties within the Catalog definition in catalog_definition.json.
  • Added static callableFrom and returnType metadata properties to FunctionDefinition inside catalog_definition.json to advertise execution boundaries and return types to the agent.

2.6. Agent card and transport metadata

  • Standardized the official MIME type to application/a2ui+json to conform to IANA media type guidelines.
  • Updated capabilities namespace in transport metadata and A2A metadata parameters from v0.9/v0.9.1 to v1.0.

2.7. Data encoding

  • Standardized data deletion behavior in updateDataModel by making the value property required. Setting a path's value to null deletes the key at that path. Omitting the value property is now a schema validation error.
  • Removed callableFrom and returnType properties and validation constraints from FunctionCall and dynamic value schemas in common_types.json, deferring boundary checking and return type validation entirely to runtime execution.
  • Added built-in @index function (with optional offset parameter) under FunctionCall to retrieve the iteration index during list template rendering. Reserved the @ prefix for core system context evaluations.

2.8. Processing rules

  • Explicitly specified that surfaceId must be globally unique per renderer session. Creating a surface with an ID that already exists (without first deleting it) is an error.
  • Enforced runtime lookup of function execution boundaries and return types. If a renderer receives a remote call to a function configured as rendererOnly or if the function is unregistered, it rejects the call and returns an error with the code INVALID_FUNCTION_CALL.
  • Enforced catalog entity naming compliance with Unicode Standard Annex #31 (UAX #31).
  • Restricted @index evaluation scope strictly to template instantiation loops (Collection Scope). Calling @index outside of template iteration results in an evaluation error.

2.9. Terminology standardization

  • Renamed client to renderer and server to agent globally across all protocol schemas, capabilities, and message list definitions.
  • Renamed all client-to-server and server-to-client JSON schema files to use renderer/agent filenames:
  • server_to_client.json -> agent_to_renderer.json
  • client_to_server.json -> renderer_to_agent.json
  • client_capabilities.json -> renderer_capabilities.json
  • server_capabilities.json -> agent_capabilities.json
  • client_data_model.json -> renderer_data_model.json

3. Migration guide

This section outlines the steps required to migrate existing applications and components from version 0.9 (including 0.9.1) to version 1.0.

For agents

  • Set the version field in all streamed JSON envelopes to "v1.0".
  • Change the MIME type of A2UI payloads in transport layers from application/json+a2ui to application/a2ui+json.
  • Rename the theme field in createSurface messages to surfaceProperties and remove primaryColor. You can also pass initial components and dataModel directly in the createSurface payload.
  • Convert the functions property in catalog definitions from an array to a JSON object map keyed by function name.
  • Rename the $defs/theme catalog definition to $defs/surfaceProperties and remove the primaryColor field.
  • Ensure all generated catalog entity names conform to UAX #31 identifier rules.
  • Do not include callableFrom or returnType properties in wire-level FunctionCall payloads. Set static callableFrom and returnType metadata in catalog function definitions where needed.
  • Update Video, TextField, and Slider components to support optional posterUrl, placeholder, and steps properties.
  • Explicitly set values to null in updateDataModel messages to delete keys at specified paths. The value property is now required, and omitting it is a schema validation error.
  • Rename all references, constants, and endpoints mapping to server_to_client.json or server_capabilities.json to use agent_to_renderer.json and agent_capabilities.json.

For renderers

  • Implement function execution by adding support for parsing callFunction messages, checking boundary definitions in the catalog (callableFrom), rejecting invalid calls with INVALID_FUNCTION_CALL, and returning functionResponse messages.
  • Support synchronous action responses by generating actionId for actions with wantResponse: true and writing returned values from actionResponse messages into the data model.
  • Support simultaneous version handling during session initialization by inspecting the version property (e.g., "v1.0") to route payloads to version-specific controllers.
  • Enforce surface uniqueness by raising an error if createSurface is received for an existing surfaceId.
  • Update error reporting to handle functionCallId and enforce mutual exclusivity with surfaceId.
  • Enforce Unicode identifier naming by verifying that all catalog entity names (components, functions, prop keys) conform to UAX #31 identifier rules.
  • Support built-in @index evaluation during list template rendering (Collection Scope) to provide the 0-based iteration index, adjusted by any offset parameter.
  • Rename all references, constants, and endpoints mapping to client_to_server.json or client_capabilities.json to use renderer_to_agent.json and renderer_capabilities.json.