A2UI
A2UI (Agent-to-User Interface) is Google’s protocol for agent-driven UI. Zakardo adopts A2UI as its frontend protocol — capabilities emit declarative, structured UI descriptions that stream to the frontend and render using a component catalog.
How A2UI Works in Zakardo
Section titled “How A2UI Works in Zakardo”Instead of building static pages, Zakardo applications render UI dynamically from plan execution:
- A capability executes and produces output data
- The A2UI Composition Engine transforms the output into A2UI messages
- Messages stream to the frontend via SSE (Server-Sent Events)
- The frontend renderer maps A2UI components to native UI components and renders them
Capability Output → A2UI Composition → SSE Stream → Frontend Renderer → Rendered UISurfaces
Section titled “Surfaces”A surface is a named region in the frontend where A2UI content renders. Zakardo defines three standard surface types:
| Surface | Purpose | Example |
|---|---|---|
assistant | Primary content area for plan execution results | Contact list, deal details |
workspace | Persistent workspace views (anchored views) | Dashboard, analytics |
notification | Transient messages and alerts | ”Contact created successfully” |
Developers can define additional custom surfaces for their application.
Anchored Views vs Ephemeral Views
Section titled “Anchored Views vs Ephemeral Views”| View Type | Description | When Used |
|---|---|---|
| Anchored Views | Pre-registered, persistent UI layouts tied to specific capabilities | ”Show contacts” always renders the same polished contacts table |
| Ephemeral Views | Dynamically composed layouts assembled at runtime | A novel plan produces a custom layout from capability outputs |
Anchored views provide a consistent, polished experience for common interactions. Ephemeral views handle novel plans that have no pre-designed layout.
A2UI Messages
Section titled “A2UI Messages”The runtime sends four types of A2UI messages:
| Message Type | Purpose |
|---|---|
surface_update | Add or update components on a surface |
data_model_update | Update the data model that components bind to |
begin_rendering | Signal that a new rendering context is starting |
delete_surface | Remove a surface and its contents |
Component Catalog
Section titled “Component Catalog”Zakardo provides a Standard Catalog of plan-aware A2UI components:
| Component | Purpose |
|---|---|
DataTable | Tabular data with sortable columns |
DetailCard | Key-value detail display |
StatusBadge | Status indicators with color coding |
ActionButton | User action triggers |
FormInput | Form fields for user input |
SelectList | Selection from options |
ConfirmDialog | Confirmation prompts (used for gates) |
ProgressBar | Execution progress indicators |
ErrorDisplay | Structured error messages |
Developers extend the catalog with custom catalogs containing domain-specific components.
Streaming Architecture
Section titled “Streaming Architecture”A2UI messages stream to the frontend in real-time via SSE:
import { ZakardoClient } from '@zakardo/client';
const client = new ZakardoClient({ baseUrl: 'http://localhost:3000/zakardo/v1' });
const stream = client.intent.stream(intentId);
stream.on('a2ui_surface_update', (event) => { // Render the surface update renderer.applySurfaceUpdate(event.surface_id, event.components);});
stream.on('a2ui_data_model_update', (event) => { // Update the data model renderer.applyDataModelUpdate(event.entries);});React Integration
Section titled “React Integration”The @zakardo/a2ui-react package provides React components for rendering A2UI:
import { ZakardoSurface } from '@zakardo/a2ui-react';
function App() { return ( <div> <ZakardoSurface surfaceId="assistant" /> <ZakardoSurface surfaceId="workspace" /> </div> );}The renderer automatically maps A2UI component types to React components from the registered catalogs.
Interaction Points
Section titled “Interaction Points”When a capability declares an interaction spec, the A2UI Composition Engine renders an interaction UI at runtime:
| Interaction Type | A2UI Rendering |
|---|---|
SELECT | Selection list with options |
COMPARE | Side-by-side comparison view |
REVIEW | Data review with approve/reject |
INPUT | Free-form input field |
CONFIRM | Confirmation dialog |
Execution pauses until the user responds, then resumes with the user’s input.
Further Reading
Section titled “Further Reading”- Frontend Architecture Specification — full 900-line specification
- Studio — visual tool for previewing A2UI rendering
- Runtime API — SSE streaming protocol details