The A2UI Contract: A Deep Dive into Agent-to-UI Architecture

The A2UI contract focuses on agent-to-UI architecture, allowing a language model to design a user interface dynamically without writing code. Instead, the model sends a description, and a contract on the wire ensures that description is trustworthy. Here's a deep dive into the three roles involved in this process:

1. The Agent: This is your server code, responsible for deciding what to show on the user interface. It determines which components to fill with values. The agent communicates solely through messages to the client, never executing any code itself.

2. The Protocol: This defines the shape of the description that the agent sends. It consists of four message types that the agent may send, and one type that the client may send back. The protocol ensures that the description's shape is consistent and can be validated before any action is taken.

3. The Renderer: This is the client library and the set of components built for the UI. The renderer's job is to decide how the description actually looks and behaves on screen. The agent, which runs on the server controlled by your team, is the only component that runs here.

A2UI's approach moves the decision-making process away from the model itself. Rather than asking the model to produce executable code, A2UI asks it to produce data in the form of a small JSON object. This object names a component that already exists on the client side and specifies which values should be displayed. Because the model only names things and never produces executable code, its output can be validated against a schema before any action is taken.

This architecture has several benefits. First, the output can be cached since the same component serves every request. Only the values behind the component need to be fresh. Second, the format the description travels in can be treated as a real contract, making it versioned, documented, and implementable by more than one client.

Three key roles are involved in this process: Agent, Protocol, and Renderer. Each role has its own responsibilities and boundaries defined by the protocol, ensuring a clear separation of duties. The agent decides what to show, the protocol defines the shape of the description, and the renderer decides how it looks. The agent runs on the server, while everything from the wire onward is client code.

Six design commitments hold these roles together. Streaming messages allow the UI to arrive as a sequence of small JSON messages, enabling the client to render incrementally rather than waiting for a single document. Declarative components describe the UI (for example, a StatCard with a specific label) rather than programming it, allowing the client to map names to real code.

Data binding keeps structure and state separate, with values changing through a distinct data model. The component tree underneath doesn't move, ensuring stability. These concepts work together to create an independent UI container, each with its own component tree and data model. The agent communicates with the client through three messages, the catalog serves as the allowlist of component types, and the data model exists for each surface.

Actions, the only client-to-agent message, are purely local interactions. Finally, the transport layer is intentionally left out, allowing for flexibility in how the messages are carried, such as through SSE, WebSocket, or a single POST response.