ADR-086: AG-UI Event Protocol Integration

Document: ADR-086-ag-ui-event-protocol-integration
Version: 1.0.0
Purpose: Integrate AG-UI protocol for real-time AI-to-UI streaming
Audience: Frontend developers, agent builders, system architects
Date Created: 2026-01-19
Status: ACCEPTED
Related ADRs:
  - ADR-084-moe-ui-agent-architecture (agent pipeline)
  - ADR-085-atomic-design-component-library (component hierarchy)
  - ADR-071-copilotkit-agentic-frontend-integration (CopilotKit)
Related Documents:
  - skills/ag-ui-protocol/SKILL.md
  - skills/moe-ui-agui-streaming/SKILL.md

---

Context and Problem Statement

AI agents generating UI need a standardized way to stream updates to frontend applications. Current patterns have limitations:

• HTTP request/response is blocking (no progressive updates)
• Custom WebSocket implementations lack standardization
• No framework-agnostic protocol for AI-to-UI communication

Why now: The MoE UI pipeline (ADR-084) generates complex UIs that benefit from progressive rendering. Users should see UI elements appear as they're generated, not wait for complete output.

If we don't decide: Each UI generation is all-or-nothing, creating poor UX for complex generations and no ability to show work-in-progress.

---

Decision Drivers

Mandatory Requirements (Must-Have)

• Progressive UI rendering (stream as generated)
• Bidirectional communication (agent ↔ frontend)
• Framework agnostic (React, Vue, Angular, Svelte)
• Reliable delivery with reconnection handling

Important Goals (Should-Have)

• Low latency (<100ms per event)
• Support for partial UI updates (not full re-render)
• Event typing for IDE autocompletion
• Integration with existing A2UI tree format

Nice-to-Have

• Visual debugging tools
• Event replay for testing
• Analytics on streaming performance

---

Considered Options

Option 1: AG-UI Protocol (SELECTED)

Description: Adopt the open AG-UI (Agent-Generated UI) protocol, which defines standardized events for AI-to-UI streaming via WebSocket or Server-Sent Events.

Event Types:

// Core AG-UI Events
interface AGUIEvent {
  type: 'lifecycle' | 'text' | 'tool' | 'state' | 'custom';
  timestamp: number;
  payload: unknown;
}

// Lifecycle Events
type LifecycleEvent =
  | { type: 'RUN_STARTED'; runId: string }
  | { type: 'RUN_FINISHED'; runId: string }
  | { type: 'RUN_ERROR'; error: string }
  | { type: 'STEP_STARTED'; stepId: string }
  | { type: 'STEP_FINISHED'; stepId: string };

// UI-Specific Events
type UIEvent =
  | { type: 'COMPONENT_CREATED'; nodeId: string; component: A2UINode }
  | { type: 'COMPONENT_UPDATED'; nodeId: string; props: Partial<Props> }
  | { type: 'COMPONENT_REMOVED'; nodeId: string }
  | { type: 'TREE_COMPLETE'; tree: A2UITree };

Pros:

• Open standard with community adoption
• CopilotKit compatibility (ADR-071)
• Framework-agnostic by design
• Built-in TypeScript types
• Supports both WebSocket and SSE transports

Cons:

• External dependency (protocol spec)
• Learning curve for new event types
• May need custom events for CODITECT-specific needs

Effort: Medium

Option 2: Custom WebSocket Protocol (REJECTED)

Description: Design proprietary WebSocket message format for CODITECT.

Pros:

• Full control over message format
• No external dependencies
• Tailored to our exact needs

Cons:

• Reinventing the wheel
• No ecosystem/tooling
• Documentation burden
• CopilotKit incompatible

Effort: High

Option 3: HTTP Streaming (REJECTED)

Description: Use HTTP streaming (chunked transfer encoding) for progressive output.

Pros:

• Simple implementation
• No WebSocket complexity
• Works through all proxies

Cons:

• Unidirectional (server → client only)
• No structured events
• Hard to handle partial updates
• Connection management issues

Effort: Low

---

Decision Outcome

Chosen Option: Option 1 - AG-UI Protocol

Rationale: AG-UI is the emerging standard for AI-to-UI streaming, with CopilotKit adoption providing ecosystem validation. The protocol's event types align well with our A2UI tree structure, and TypeScript support enables type-safe integration.

---

Consequences

Positive Consequences

• Progressive Rendering: Users see UI as it's generated
• CopilotKit Compatible: Leverage existing frontend SDK
• Standardized: No proprietary protocol to document
• Type-Safe: Full TypeScript support
• Bidirectional: Frontend can send feedback during generation

Negative Consequences

• Protocol Dependency: Must track AG-UI spec changes
• Custom Events: May need CODITECT extensions to protocol
• Transport Complexity: Must handle WebSocket/SSE fallbacks

Risk Mitigation

Risk	Mitigation
Protocol changes	Pin to specific AG-UI version; abstract behind adapter
WebSocket failures	Automatic SSE fallback; reconnection logic
Event ordering	Sequence numbers; idempotent handlers
Large payloads	Incremental tree updates; compression

---

Implementation Details

Event Flow

┌─────────────────┐     WebSocket/SSE     ┌─────────────────┐
│  MoE UI Agent   │────────────────────▶│    Frontend     │
│    Pipeline     │                       │   Application   │
└─────────────────┘                       └─────────────────┘
         │                                         │
         │  RUN_STARTED                           │
         │───────────────────────────────────────▶│
         │                                         │
         │  STEP_STARTED (quality-gate)           │
         │───────────────────────────────────────▶│
         │                                         │
         │  STEP_FINISHED                         │
         │───────────────────────────────────────▶│
         │                                         │
         │  COMPONENT_CREATED (header)            │
         │───────────────────────────────────────▶│
         │                                         │
         │  COMPONENT_CREATED (sidebar)           │
         │───────────────────────────────────────▶│
         │                                         │
         │  COMPONENT_CREATED (card-1)            │
         │───────────────────────────────────────▶│
         │                                         │
         │  TREE_COMPLETE                         │
         │───────────────────────────────────────▶│
         │                                         │
         │  RUN_FINISHED                          │
         │───────────────────────────────────────▶│

CODITECT Event Extensions

// CODITECT-specific AG-UI events
interface CODITECTEvents {
  // Quality gate results
  QUALITY_GATE_PASSED: {
    gate: string;
    score: number;
    details: Record<string, unknown>;
  };

  QUALITY_GATE_FAILED: {
    gate: string;
    violations: Violation[];
  };

  // HITL events
  APPROVAL_REQUIRED: {
    requestId: string;
    riskLevel: 'low' | 'medium' | 'high' | 'critical';
    changes: Change[];
    timeout?: number;
  };

  APPROVAL_RECEIVED: {
    requestId: string;
    approved: boolean;
    modifier?: string;
  };

  // Design system events
  TOKEN_VIOLATION: {
    nodeId: string;
    property: string;
    actual: string;
    expected: string;
  };
}

Transport Configuration

// Connection setup
const connection = createAGUIConnection({
  url: 'wss://api.coditect.ai/agui',
  transport: 'websocket', // or 'sse'
  reconnect: {
    enabled: true,
    maxAttempts: 5,
    backoff: 'exponential',
  },
  auth: {
    token: sessionToken,
  },
});

// Event handlers
connection.on('COMPONENT_CREATED', (event) => {
  uiRenderer.addNode(event.nodeId, event.component);
});

connection.on('TREE_COMPLETE', (event) => {
  uiRenderer.finalize(event.tree);
});

connection.on('APPROVAL_REQUIRED', (event) => {
  showApprovalDialog(event);
});

Affected Components

Component	Change Type	Impact
agents/moe-ui-agui-event-coordinator.md	Add	Event streaming agent
skills/moe-ui-agui-streaming/SKILL.md	Add	Streaming patterns
packages/agui-client/	Add	Frontend SDK
services/agui-gateway/	Add	WebSocket server

---

Validation and Compliance

Success Criteria

• WebSocket connection established within 500ms
• Event latency < 100ms (P95)
• Automatic reconnection within 5 seconds
• All AG-UI event types supported
• CODITECT extension events documented
• Frontend SDK published to npm

Testing Requirements

• Unit tests for event serialization
• Integration tests for connection lifecycle
• Load tests for concurrent connections
• Chaos tests for network failures

---

Links

Internal Documentation

• skills/ag-ui-protocol/SKILL.md
• skills/moe-ui-agui-streaming/SKILL.md
• ADR-071-copilotkit-agentic-frontend-integration.md

External References

• AG-UI Protocol Specification
• CopilotKit Documentation
• WebSocket RFC 6455
• Server-Sent Events

Code Locations

• agents/moe-ui-agui-event-coordinator.md - Event coordination agent
• packages/agui-client/ - Frontend SDK
• services/agui-gateway/ - WebSocket server

---

Changelog

Version	Date	Author	Changes
1.0.0	2026-01-19	CODITECT	Initial version

---

Compliance: CODITECT-STANDARD-ADR v1.0.0