Skip to content

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.

Instead of building static pages, Zakardo applications render UI dynamically from plan execution:

  1. A capability executes and produces output data
  2. The A2UI Composition Engine transforms the output into A2UI messages
  3. Messages stream to the frontend via SSE (Server-Sent Events)
  4. The frontend renderer maps A2UI components to native UI components and renders them
Capability Output → A2UI Composition → SSE Stream → Frontend Renderer → Rendered UI

A surface is a named region in the frontend where A2UI content renders. Zakardo defines three standard surface types:

SurfacePurposeExample
assistantPrimary content area for plan execution resultsContact list, deal details
workspacePersistent workspace views (anchored views)Dashboard, analytics
notificationTransient messages and alerts”Contact created successfully”

Developers can define additional custom surfaces for their application.

View TypeDescriptionWhen Used
Anchored ViewsPre-registered, persistent UI layouts tied to specific capabilities”Show contacts” always renders the same polished contacts table
Ephemeral ViewsDynamically composed layouts assembled at runtimeA 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.

The runtime sends four types of A2UI messages:

Message TypePurpose
surface_updateAdd or update components on a surface
data_model_updateUpdate the data model that components bind to
begin_renderingSignal that a new rendering context is starting
delete_surfaceRemove a surface and its contents

Zakardo provides a Standard Catalog of plan-aware A2UI components:

ComponentPurpose
DataTableTabular data with sortable columns
DetailCardKey-value detail display
StatusBadgeStatus indicators with color coding
ActionButtonUser action triggers
FormInputForm fields for user input
SelectListSelection from options
ConfirmDialogConfirmation prompts (used for gates)
ProgressBarExecution progress indicators
ErrorDisplayStructured error messages

Developers extend the catalog with custom catalogs containing domain-specific components.

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);
});

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.

When a capability declares an interaction spec, the A2UI Composition Engine renders an interaction UI at runtime:

Interaction TypeA2UI Rendering
SELECTSelection list with options
COMPARESide-by-side comparison view
REVIEWData review with approve/reject
INPUTFree-form input field
CONFIRMConfirmation dialog

Execution pauses until the user responds, then resumes with the user’s input.