How A2UI Works

Message Flow Between Client, Server, and Remote Agent
arrow_back Back to Demo

The A2UI Message Flow

This page shows a representative message sequence from when a user asks for flashcards about ATP.

A2UI enables agents to generate rich UI components as declarative JSON data, not executable code. The client application renders these using its own native components.

Browser Client
→
Local API Server
(api-server.ts)
→
Remote Agent
(Vertex AI Agent Engine)
→
Local API Server
→
Browser Renders
1
Client → Server /api/chat (Intent Detection)
User types "Create flashcards for bond energy misconceptions". The orchestrator first sends this to Gemini to detect the user's intent.
Request Payload JSON
2
Server → Client /api/chat (Intent Classification)
Gemini classifies the intent as "flashcards". This tells the orchestrator to fetch A2UI content from the specialized agent.
Response JSON
3
Client → Server /a2ui-agent/a2a/query
The browser requests A2UI content generation. It specifies format: flashcards and includes context about what the user asked for.
Request Payload JSON
4
Server → Remote Agent Deployed to Vertex AI Agent Engine
The server forwards the request to a remote A2UI-generating agent deployed to Vertex AI Agent Engine. This agent is a separate service that specializes in generating A2UI content.
Request to Remote Agent (via Agent Engine API) JSON
Key Point: This is the A2A (Agent-to-Agent) pattern described in the blog. The orchestrator delegates UI generation to a specialized remote agent deployed on Vertex AI Agent Engine - demonstrating cross-boundary agent collaboration.
5
Remote Agent → Server Response from Vertex AI Agent Engine
The remote agent (deployed on Agent Engine) returns A2UI JSON - a declarative description of UI components. This is the core of what A2UI provides.
A2UI Messages (Parsed) JSON • Scroll to see full payload

Understanding the A2UI Structure

beginRendering - Declares the surface and root component ID
surfaceUpdate - Contains the flat list of components with ID references
Components - Text, Column, Row, Flashcard - these are catalog components the client knows how to render

6
Server → Client /a2ui-agent/a2a/query
The server sends the A2UI payload to the browser. The @a2ui/web-lib renderer processes this JSON and creates native web components.
Final Response to Browser JSON
Result: The browser's A2UI renderer creates <a2ui-surface>, which contains <a2ui-flashcard> components styled to match the host application's theme.