# google/a2ui architecture

> Architecture diagram of the GitHub repository google/a2ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google/a2ui
- Repository: https://github.com/google/a2ui

## Overview

##### Project Type & Purpose
- This is an open-source, framework-agnostic UI standard and toolkit (A2UI: Agent-to-User Interface).
- It defines a JSON schema (“A2UI Response”) for declarative, updateable UIs generated by AI agents, plus reference implementations:
- Agent SDKs (Java, Python) that emit A2UI JSON
- Multiple client-side renderers (Angular, Lit, Web Core, Flutter via GenUI)
- Supporting tools (editor, inspector)
- Samples (agent demos, client shells)
- A formal specification with test/eval pipelines
- Purpose: Decouple UI generation (by agents) from UI execution (in host frameworks), enabling secure, cross-platform agentic interfaces.

##### File Structure Analysis
- Top-level directories:
- a2a_agents/    ← Java & Python agent extension libraries
- renderers/     ← UI renderer libraries per framework (angular, lit, web_core, flutter)
- samples/       ← End-to-end demos: agent (adk), client (angular, lit, personalized_learning)
- specification/ ← Versioned A2UI spec, JSON schemas, evaluation/test pipelines
- tools/         ← Developer tools (editor, inspector) built on A2UI
- docs/          ← MkDocs documentation site, tutorials, guides
- Configuration:
- mkdocs.yaml, GitHub workflows for CI across languages/frameworks
- Language-specific build configs: pom.xml, pyproject.toml, package.json, tsconfig.json
- Patterns:
- Modular, versioned spec → consumed by agents, renderers, tools
- Agent SDK → generates JSON → Transport → Renderer → Host UI
- Registry pattern in renderers for custom components & data binding

##### README Insights
- High-level flow: Generation (agent) → Transport → Resolution (renderer) → Rendering (UI)
- Core philosophies: Security (catalog + declarative), LLM-friendliness (incremental updates), framework-agnostic, extensibility
- Dependencies: A2A Protocol, AG UI transports, Node/Python/Java runtimes

- Specification Layer:
– versioned JSON schemas (specification/v0_8, v0_9, v0_10)
– evaluation & test pipelines
- Agent Layer:
– Java SDK (a2a_agents/java)
– Python SDK (a2a_agents/python)
– Sample agents (samples/agent/adk/…)
- Transport Layer:
– A2A Protocol, AG UI (implicit in docs)
- Client Layer:
– Renderers: Angular, Lit, Web Core, Flutter (renderers/*)
– Sample clients: Angular projects, Lit shell, personalized_learning
- Tooling Layer:
– Editor (tools/editor)
– Inspector (tools/inspector)
- Documentation & CI:
– MkDocs site (docs/*)
– GitHub Actions workflows (.github/workflows/*)

b. Relationships & Data Flow:
1. Agents import spec → emit A2UI JSON
2. JSON travels over a transport (A2A/AG UI/websocket/REST)
3. Renderer parses JSON against spec → looks up component catalog → constructs UI tree
4. Host application injects renderer output into native framework UI
5. Custom component registrations → allow extension beyond standard catalog

c. Architectural Patterns & Principles:
- Declarative data format (JSON) as boundary between agent and client
- Registry/inversion-of-control in renderers for extensibility
- Versioned, testable spec maintained separately from implementations
- Polyglot SDKs demonstrating multi-language support

d. Key Technologies & Frameworks:
- Java (Maven) & Python (pyproject) for agent SDKs
- TypeScript/Node for renderers and tools (npm, tsconfig)
- Angular, Lit, Web Components for web renderers
- MkDocs/Python for docs site
- GitHub Actions for multi-language CI
- Docker/Firebase/Cloud for personalized_learning demo

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Specification Layer
    subgraph "Specification Layer"
        spec08["A2UI Spec v0.8"]:::spec
        spec09["A2UI Spec v0.9"]:::spec
        spec10["A2UI Spec v0.10"]:::spec
    end

    %% Agent Layer
    subgraph "Agent Layer"
        JavaSDK["Java Agent SDK"]:::agent
        PythonSDK["Python Agent SDK"]:::agent
        SampleAgents["Sample Agents (ADK)"]:::agent
    end

    %% Transport Layer
    JSON["A2UI JSON Payload"]:::transport
    Transport["A2A/AG UI Transport"]:::transport

    %% Client Renderer Layer
    subgraph "Client Renderer Layer"
        AngularRenderer["Angular Renderer"]:::renderer
        LitRenderer["Lit Renderer"]:::renderer
        WebCoreRenderer["Web Core Renderer"]:::renderer
        FlutterRenderer["Flutter Renderer"]:::renderer
    end

    %% Host UI Integration
    HostUI["Host Application UI"]:::ui

    %% Tooling Layer
    subgraph "Tooling Layer"
        Editor["Editor Tool"]:::tools
        Inspector["Inspector Tool"]:::tools
    end

    %% Documentation & CI
    subgraph "Docs & CI"
        DocsSite["Documentation Site (MkDocs)"]:::docs
        CIWorkflows["CI Workflows"]:::docs
    end

    %% Data Flow Relationships
    spec10 -->|specifies schema| JavaSDK
    spec10 -->|specifies schema| PythonSDK
    spec10 -->|specifies schema| AngularRenderer
    spec10 -->|specifies schema| LitRenderer
    spec10 -->|specifies schema| WebCoreRenderer
    spec10 -->|specifies schema| FlutterRenderer
    spec10 -->|specifies schema| Editor
    spec10 -->|specifies schema| Inspector

    JavaSDK -->|"emits JSON"| JSON
    PythonSDK -->|"emits JSON"| JSON
    SampleAgents -->|"uses SDK"| JavaSDK
    SampleAgents -->|"uses SDK"| PythonSDK

    JSON -->|transports via| Transport
    Transport -->|delivers to| AngularRenderer
    Transport -->|delivers to| LitRenderer
    Transport -->|delivers to| WebCoreRenderer
    Transport -->|delivers to| FlutterRenderer

    AngularRenderer -->|"renders UI"| HostUI
    LitRenderer -->|"renders UI"| HostUI
    WebCoreRenderer -->|"renders UI"| HostUI
    FlutterRenderer -->|"renders UI"| HostUI

    Editor -->|edit/visualize| AngularRenderer
    Editor -->|edit/visualize| LitRenderer
    Editor -->|edit/visualize| WebCoreRenderer
    Editor -->|edit/visualize| FlutterRenderer

    Inspector -->|inspect UI| AngularRenderer
    Inspector -->|inspect UI| LitRenderer
    Inspector -->|inspect UI| WebCoreRenderer
    Inspector -->|inspect UI| FlutterRenderer

    DocsSite -.-> spec08
    DocsSite -.-> spec09
    DocsSite -.-> spec10
    CIWorkflows -.-> JavaSDK
    CIWorkflows -.-> PythonSDK
    CIWorkflows -.-> AngularRenderer

    %% Click Events
    click spec08 "https://github.com/google/a2ui/tree/main/specification/v0_8"
    click spec09 "https://github.com/google/a2ui/tree/main/specification/v0_9"
    click spec10 "https://github.com/google/a2ui/tree/main/specification/v0_10"
    click JavaSDK "https://github.com/google/a2ui/tree/main/a2a_agents/java"
    click PythonSDK "https://github.com/google/a2ui/tree/main/a2a_agents/python/a2ui_agent"
    click SampleAgents "https://github.com/google/a2ui/tree/main/samples/agent/adk"
    click AngularRenderer "https://github.com/google/a2ui/tree/main/renderers/angular"
    click LitRenderer "https://github.com/google/a2ui/tree/main/renderers/lit"
    click WebCoreRenderer "https://github.com/google/a2ui/tree/main/renderers/web_core"
    click FlutterRenderer "https://github.com/google/a2ui/blob/main/renderers/flutter/README.md"
    click Editor "https://github.com/google/a2ui/tree/main/tools/editor"
    click Inspector "https://github.com/google/a2ui/tree/main/tools/inspector"
    click DocsSite "https://github.com/google/a2ui/tree/main/docs/"
    click CIWorkflows "https://github.com/google/a2ui/tree/main/.github/workflows"

    %% Styles
    classDef spec fill:#D0E7FF,stroke:#036,stroke-width:1px
    classDef agent fill:#D0FFD0,stroke:#073,stroke-width:1px
    classDef transport fill:#E0E0E0,stroke:#555,stroke-width:1px
    classDef renderer fill:#FFE7D0,stroke:#E85,stroke-width:1px
    classDef tools fill:#E7D0FF,stroke:#705,stroke-width:1px
    classDef docs fill:#F0F0F0,stroke:#999,stroke-width:1px
    classDef ui fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 2 2
```
