ADR-069: A2UI (Agent-to-User Interface) Integration

Status

Accepted - January 13, 2026

Track: T.1 - External Tools Integration

Context

Problem Statement

AI agents excel at generating text and code, but presenting rich, interactive interfaces to users remains challenging. CODITECT agents currently output:

1. Plain text - Limited formatting, no interactivity
2. Markdown - Better formatting, but still static
3. HTML/Code - Security risks when executing agent-generated code

This creates friction when agents need to:

• Collect structured user input (forms, selections)
• Display dynamic dashboards with real-time data
• Present interactive reports with actions
• Render cross-platform UIs from remote agents

Solution: A2UI

A2UI (Agent-to-User Interface) is Google's open-source standard that allows agents to "speak UI" via declarative JSON. Key benefits:

Principle	Implementation
Security First	Declarative data format, not executable code
LLM-Friendly	Flat component list with ID references, easy for LLMs to generate incrementally
Framework-Agnostic	Same JSON renders on Web, Flutter, Angular, React
Incrementally Updateable	Progressive rendering, efficient updates

A2UI Version

• Current: v0.9 (Public Preview)
• Specification: submodules/tools/A2UI/specification/0.9/

Decision

Integrate A2UI as a first-class UI generation capability for CODITECT agents, with:

1. Submodule integration at submodules/tools/A2UI/
2. Agent, skill, command, and hook components for A2UI generation
3. Validation and rendering infrastructure
4. Integration with existing CODITECT agents

Integration Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                      CODITECT + A2UI INTEGRATION                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    CODITECT Agent (e.g., senior-architect)          │   │
│  │                                                                      │   │
│  │  "Design a dashboard for task status"                               │   │
│  └───────────────────────────────┬─────────────────────────────────────┘   │
│                                  │                                          │
│                                  ▼                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                       a2ui-generator Agent                           │   │
│  │                                                                      │   │
│  │  Uses a2ui-component-design skill to generate A2UI JSON             │   │
│  └───────────────────────────────┬─────────────────────────────────────┘   │
│                                  │                                          │
│                                  ▼                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    A2UI JSON Payload                                 │   │
│  │                                                                      │   │
│  │  {                                                                   │   │
│  │    "type": "a2ui",                                                   │   │
│  │    "version": "0.9",                                                 │   │
│  │    "components": [                                                   │   │
│  │      {"id": "root", "type": "container", "children": [...]},        │   │
│  │      {"id": "card1", "type": "card", ...}                           │   │
│  │    ],                                                                │   │
│  │    "data": {...},                                                    │   │
│  │    "bindings": {...}                                                 │   │
│  │  }                                                                   │   │
│  └───────────────────────────────┬─────────────────────────────────────┘   │
│                                  │                                          │
│           ┌──────────────────────┼──────────────────────┐                  │
│           │                      │                      │                   │
│           ▼                      ▼                      ▼                   │
│  ┌─────────────┐        ┌─────────────┐        ┌─────────────┐             │
│  │ Lit Renderer│        │Angular Rend.│        │Flutter Rend.│             │
│  │  (Web)      │        │  (Web)      │        │  (Mobile)   │             │
│  └─────────────┘        └─────────────┘        └─────────────┘             │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

A2UI Component Catalog

A2UI uses a predefined catalog of safe, trusted components:

Layout Components

Component	Properties	Purpose
container	layout, padding, gap	Grouping, structure
card	elevation, header	Content sections
grid	columns, rows	Multi-column layouts
stack	direction, spacing	Flex layouts

Content Components

Component	Properties	Purpose
text	content, variant, color	Display text
image	src, alt, fit	Display images
icon	name, size, color	Visual indicators
divider	orientation	Visual separation

Interactive Components

Component	Properties	Purpose
button	label, action, variant	User actions
text-field	label, placeholder, validation	Text input
select	options, multiple	Option selection
checkbox	label, checked	Boolean input
slider	min, max, step	Range input
date-picker	format, min, max	Date selection

Data Components

Component	Properties	Purpose
list	items, template	Repeating items
table	columns, data	Tabular data
chart	type, data, options	Data visualization

A2UI JSON Structure

{
  "type": "a2ui",
  "version": "0.9",
  "components": [
    {
      "id": "root",
      "type": "container",
      "children": ["header", "metrics", "actions"],
      "properties": {
        "layout": "vertical",
        "padding": "16px"
      }
    },
    {
      "id": "header",
      "type": "text",
      "properties": {
        "variant": "h1",
        "content": "{{data.title}}"
      }
    },
    {
      "id": "metrics",
      "type": "grid",
      "children": ["metric1", "metric2"],
      "properties": {
        "columns": 2,
        "gap": "8px"
      }
    },
    {
      "id": "metric1",
      "type": "card",
      "children": ["m1-value"],
      "properties": {
        "elevation": 2
      }
    },
    {
      "id": "m1-value",
      "type": "text",
      "properties": {
        "content": "{{data.completedTasks}} / {{data.totalTasks}}"
      }
    },
    {
      "id": "actions",
      "type": "stack",
      "children": ["refresh-btn", "export-btn"],
      "properties": {
        "direction": "horizontal",
        "spacing": "8px"
      }
    },
    {
      "id": "refresh-btn",
      "type": "button",
      "properties": {
        "label": "Refresh",
        "action": "refresh-data"
      }
    },
    {
      "id": "export-btn",
      "type": "button",
      "properties": {
        "label": "Export",
        "variant": "secondary",
        "action": "export-report"
      }
    }
  ],
  "data": {
    "title": "Task Dashboard",
    "completedTasks": 42,
    "totalTasks": 50
  },
  "bindings": {
    "header-title": "data.title"
  }
}

CODITECT Components

Created Components (T.1)

Type	Component	Purpose
Agent	a2ui-generator	Generate A2UI JSON from descriptions
Skill	a2ui-component-design	Design component trees
Command	/a2ui	Quick A2UI generation and validation
Hook	a2ui-render-validation	Validate A2UI JSON before rendering
Workflow	a2ui-integration	End-to-end A2UI development workflow
Script	a2ui-renderer-bridge.py	Bridge CODITECT agents to A2UI renderers

Usage Examples

Generate Dashboard

# Using command
/a2ui "Create a task dashboard with progress metrics and action buttons"

# Using agent
/agent a2ui-generator "Design a code review interface with file list, diff viewer, and comment section"

Validate A2UI JSON

/a2ui --validate ui/dashboard.json

Preview in Browser

/a2ui --preview ui/dashboard.json
# Opens http://localhost:3000/preview

Integration with CODITECT Agents

CODITECT agents can generate A2UI responses for rich output:

# In agent response
{
  "text": "Here are your task results",
  "a2ui": {
    "type": "a2ui",
    "version": "0.9",
    "components": [...],
    "data": {...}
  }
}

Use Cases

1. Dynamic Data Collection

Agent generates custom forms based on conversation context:

User: "I need to book a specialized medical appointment"
Agent: [Generates A2UI form with date picker, specialist selector, insurance fields]

2. Remote Sub-Agents (A2A + A2UI)

Orchestrator delegates to remote specialized agent that returns A2UI:

Orchestrator → Travel Agent (remote) → A2UI booking interface

3. Adaptive Dashboards

Enterprise agents generate approval dashboards or visualizations on-the-fly:

User: "Show me pending approvals for my team"
Agent: [Generates A2UI dashboard with approval cards, status indicators, action buttons]

4. CODITECT Agent Output Enhancement

Standard CODITECT agents can include A2UI for richer responses:

/agent senior-architect "Design microservices architecture"
→ Returns architecture diagram + A2UI component with interactive dependency explorer

Implementation

Phase 1: Foundation (Complete)

• Add A2UI submodule at submodules/tools/A2UI/
• Create a2ui-generator agent
• Create a2ui-component-design skill
• Create /a2ui command
• Create a2ui-render-validation hook
• Create a2ui-integration workflow
• Create a2ui-renderer-bridge.py script

Phase 2: Renderer Integration (Planned)

• Build and configure Lit renderer
• Set up local preview server
• Integrate with CODITECT Cloud frontend
• Add Flutter renderer for mobile

Phase 3: Agent Ecosystem (Planned)

• Add A2UI output support to core CODITECT agents
• Create A2UI templates library
• Build custom component registry
• Integrate with A2A protocol

Configuration

Renderer Setup (One-Time)

# Build Lit renderer
cd ~/.coditect/submodules/tools/A2UI/renderers/lit
npm install && npm run build

# Run preview server
cd ~/.coditect/submodules/tools/A2UI/samples/client/lit/shell
npm install && npm run dev

A2UI Configuration

File: ~/.coditect/config/a2ui.json

{
  "a2ui": {
    "version": "0.9",
    "default_renderer": "lit",
    "preview_port": 3000,
    "validation": {
      "strict": true,
      "allow_unknown_components": false
    },
    "templates_path": "~/.coditect/templates/a2ui/"
  }
}

Consequences

Positive

1. Rich Agent UIs - Agents can generate interactive interfaces
2. Security - Declarative format, no code execution
3. Cross-Platform - Same JSON works on Web, Mobile, Desktop
4. Progressive Rendering - Incremental updates for responsive UX
5. LLM-Friendly - Easy for models to generate and modify
6. Standards-Based - Open standard, growing ecosystem

Negative

1. Renderer Setup - Requires building renderers (one-time)
2. Component Limitations - Restricted to predefined catalog
3. Learning Curve - New paradigm for UI generation
4. Preview Infrastructure - Needs local server for testing

Neutral

1. JSON Verbosity - More verbose than HTML, but safer
2. Version Management - Spec is evolving (currently v0.9)
3. Framework Lock-in - Requires A2UI-compatible renderers

Alternatives Considered

Option A: Direct HTML Generation (Rejected)

Risk: Security vulnerabilities from executing agent-generated code Reason: A2UI's declarative approach is inherently safer

Option B: Custom CODITECT UI Format (Rejected)

Effort: Significant development for custom spec Reason: A2UI is an open standard with community support and multiple renderers

Option C: React/Vue Component Generation (Rejected)

Risk: Framework-specific, requires code execution Reason: A2UI's framework-agnostic JSON is more portable and secure

Related Documents

• Submodule: submodules/tools/A2UI/
• Agent: agents/a2ui-generator.md
• Skill: skills/a2ui-component-design/SKILL.md
• Command: commands/a2ui.md
• Hook: hooks/a2ui-render-validation.md
• Workflow: workflows/developer-experience/a2ui-integration.yaml
• Script: scripts/a2ui-renderer-bridge.py
• Track: internal/project/plans/2026-01-13T05-27-27Z-pilot-tracks/TRACK-T-TOOLS.md
• ADR-070: ADK Integration (companion ADR)

Appendix

A. Submodule Location

coditect-core/
└── submodules/tools/A2UI/           ← Git submodule
    ├── specification/               ← A2UI spec (v0.8, v0.9)
    │   ├── 0.8/
    │   └── 0.9/
    ├── renderers/                   ← Client renderers
    │   ├── lit/                     ← Web Components (Lit)
    │   └── angular/                 ← Angular renderer
    ├── a2a_agents/                  ← A2A protocol agents
    ├── samples/                     ← Example implementations
    │   ├── agent/                   ← Agent samples
    │   └── client/                  ← Client samples
    ├── docs/                        ← Documentation
    └── tools/                       ← Tooling

B. A2UI vs Traditional UI Approaches

Aspect	Traditional HTML	A2UI
Security	XSS risks	Safe by design
Generation	Complex parsing	Simple JSON
Incremental Updates	Full re-render	Efficient patches
Cross-Platform	Web only	Any platform
Validation	Schema-dependent	Built-in catalog
LLM Friendliness	Moderate	High

C. Quick Reference

# Generate UI
/a2ui "Create a metrics dashboard"

# Validate JSON
/a2ui --validate output.json

# Preview
/a2ui --preview output.json

# Use agent
/agent a2ui-generator "Design a form for user registration"

---

Author: CODITECT Integration System Track: T.1 - A2UI Integration Repository: google/A2UI