a2ui-angular

# A2UI Angular Renderer Development Skill > **Tech Stack**: Angular 21+, A2UI Protocol v0.8+, TailwindCSS 4.x, daisyUI 5.5.5 ## What is A2UI? A2UI (Agent-to-User Interface) is a **declarative protocol by Google** that lets AI agents describe rich, interactive UIs as structured JSON data instead of generating executable code. The agent sends a JSON blueprint; the client app renders it using its own native components. **Key principle:** UI-as-data, not UI-as-code. Agents never generate HTML/JS — they describe intent via a flat component adjacency list. The client validates against an approved component catalog and renders with native framework components. ## Iron Law **A2UI PAYLOADS ARE UNTRUSTED. VALIDATE COMPONENT TYPES AGAINST THE CATALOG ALLOWLIST BEFORE RENDERING. NEVER EXECUTE AGENT-PROVIDED CODE.** Every component from an agent must be validated against the client's approved catalog. Rendering any component type the agent sends, or executing agent-provided scripts, exposes the application to XSS, code injection, and data theft. The catalog allowlist is the security boundary. ## Conventions & Structure > For Angular coding conventions, read the `angular-spa` skill's `reference/angular-conventions.md` > For A2UI-specific patterns, read `reference/a2ui-protocol.md` ## Documentation Sources | Source | URL / Tool | Purpose | |--------|-----------|---------| | A2UI Spec | `https://a2ui.org/` | Protocol specification, component format | | A2UI GitHub | `https://github.com/google/A2UI` | Reference implementations, samples | | A2A Extension | `https://a2ui.org/a2a-extension/a2ui/v0.8` | A2A protocol integration (Python ADK) | | A2UI Composer | `https://a2ui.org/composer/` | Visual widget builder — prototype before wiring | | @a2ui/angular | `npm install @a2ui/angular` | Official Angular renderer SDK | | Angular v21 | `angular-cli` MCP | Workspace-aware help, schematics | | daisyUI v5 | `https://daisyui.com/llms.txt` | Component reference for rendering | | TailwindCSS | `Context7` MCP | Utility classes for layout | ## Before Writing Any A2UI Code 1. **Read `reference/a2ui-protocol.md`** — protocol structure, JSON format, adjacency list, action model 2. **Read `reference/a2ui-renderer-patterns.md`** — Angular renderer architecture, catalog service, recursive rendering 3. **Read `reference/a2ui-security.md`** — allowlist enforcement, injection prevention, input sanitization 4. **Read `reference/a2ui-component-catalog.md`** — standard component types, property schemas, action definitions 5. **Verify Angular APIs** — Use `angular-cli` MCP or Context7 MCP before using any Angular API ## Process 1. **Understand Requirements** — Clarify which A2UI component types to support, agent transport (REST/WebSocket/SSE), and action handling needs 2. **Define Component Catalog** — Create the allowlist of approved A2UI component types with their property schemas 3. **Build Renderer** — Create the recursive `A2UIRendererComponent` that maps A2UI types to Angular/daisyUI components 4. **Implement Agent Service** — Create the service that communicates with the AI agent and receives A2UI payloads 5. **Add Action Handling** — Wire user interactions (clicks, form submits) back to the agent as A2UI actions 6. **Enable Streaming** — Support progressive rendering via SSE or WebSocket for real-time UI updates 7. **Write Tests** — Unit tests for catalog validation, renderer component, and action dispatch 8. **Verify Build** — Run `ng build` to ensure no compilation errors ## Reference Files Detailed patterns are in `reference/`: ### A2UI Protocol - `a2ui-protocol.md` — Protocol specification, JSON format, adjacency list structure, message types, userAction - `a2ui-protocol-advanced.md` — Action model, streaming (JSONL/SSE/WebSocket/REST/A2A), A2A integration, versioning - `a2ui-security.md` — Allowlist enforcement, injection prevention, untrusted payload handling - `a2ui-component-catalog.md` — Layout (Row, Column) + Display (Text, Image, Icon, Divider) + Interactive (Button, TextField, Checkbox, DateTimeInput) component schemas - `a2ui-component-containers.md` — Container types (Card, Modal, Tabs, List), extended catalog (ChoicePicker, Slider, AudioPlayer, Video), how to add new types - `a2ui-functions.md` — Full functions reference: validation (required, regex, email), formatting (formatCurrency, formatDate, pluralize), logical (and, or, not), navigation (openUrl) — `A2UIFunctionService` implementation ### Angular Implementation - `a2ui-renderer-patterns.md` — Architecture overview, file structure, TypeScript models, catalog service, sanitizer service, renderer key patterns - `a2ui-renderer-template.md` — Full A2UIRendererComponent implementation (all 12 @case branches, computed signals, action dispatch) - `a2ui-chat-template.md` — Chat page component, streaming variant (SSE + JSONL), wire format reference with JSON examples - `a2ui-renderer-services.md` — Official `@a2ui/angular` SDK setup (A2uiRendererService, SurfaceComponent, A2UI_RENDERER_CONFIG), A2UIAgentService (REST + SSE), unit test template - `a2ui-production-architecture.md` — Production stack, Domain DSL, Custom Catalog patterns (BoundProperty, BasicCatalogBase, FunctionImplementation), Charts/Dashboard, Testing patterns, Observability metrics - `a2ui-client-integration.md` — `agUiResource` service pattern, `registerHandlers`, widget template, **demo-only vs production action handler warning**, rate limits (surfaces/session, actions/sec, payload size) ## Anti-Patterns — What to Avoid ```typescript // ❌ FORBIDDEN: Rendering arbitrary component types from agent @switch (comp.type) { @default { <div [innerHTML]="comp.properties['html']"></div> // XSS vector! } } // ✅ REQUIRED: Validate against catalog, skip unknown types @switch (comp.type) { @default { <!-- Unknown A2UI type silently skipped — not in catalog --> } } ``` ```typescript // ❌ FORBIDDEN: Executing agent-provided code eval(comp.properties['script']); new Function(comp.properties['handler'])(); // ✅ REQUIRED: Declarative action dispatch (v0.8 format) onAction(comp: A2UIComponent): void { const action = comp['action'] as { name: string; context?: Array<{ key: string; value: unknown }> }; if (!action?.name) return; this.actionTriggered.emit({ name: action.name, context: action.context ?? [] }); } ``` ```typescript // ❌ FORBIDDEN: Deeply nested JSON tree from agent { "children": [{ "children": [{ "children": [...] }] }] } // ✅ REQUIRED: surfaceUpdate with components as array, root field (A2UI v0.8 protocol) { "surfaceUpdate": { "surfaceId": "main", "components": [ { "id": "root", "component": { "type": "Column", "children": {"explicitList": ["btn-1"]} } }, { "id": "btn-1", "component": { "type": "Button", "primary": true, "action": {"name": "submit"} } } ], "root": "root" } } // ✅ REQUIRED: userAction — 5th message type, client → agent { "userAction": { "name": "book_hotel", "surfaceId": "main", "sourceComponentId": "btn-book", "timestamp": "2026-03-10T12:00:00Z", "context": { "hotelId": "H-456" } } } ``` ## Error Handling - If agent returns an unknown component type → skip it silently (log warning), render remaining components - If agent payload is malformed JSON → show error state to user, log full error - If agent connection drops mid-stream → render what was received so far, show reconnect option - If action dispatch fails → show error toast, do NOT silently swallow ## Common Commands ```bash # Generate A2UI feature module mkdir -p src/app/features/a2ui-chat/{components,services,models} # Run tests npx ng test --watch=false # Build npx ng build ```