A2UI Cloudscape Renderer

A reactive rendering engine that bridges the A2UI Protocol with the native AWS Cloudscape Design System. Feed it strict JSON event arrays—get production-grade, enterprise-quality UI components in return.

Read the architecture walkthrough: Rendering AI Agent Interfaces with A2UI, React, and AWS Cloudscape

Installation

Install the library along with its peer dependencies:

npm install agui-cloudscape-renderer @cloudscape-design/components @cloudscape-design/collection-hooks @cloudscape-design/global-styles react react-dom

Ensure you import Cloudscape's global styles in your application's entrypoint:

import "@cloudscape-design/global-styles/index.css";

Quick Start (SSE Integration)

import React from 'react';
import { ProtocolBridge, useSSEAgUiEvents } from 'agui-cloudscape-renderer';
import '@cloudscape-design/global-styles/index.css';

export function AgentConsole() {
  // 1. Establish SSE event stream
  const { events, emitEvent, readyState, error } = useSSEAgUiEvents({
    endpoint: 'https://api.youragent.com/v1/ui/stream',
    emitEndpoint: 'https://api.youragent.com/v1/ui/events',
  });

  if (error) return <div>Connection Error: {error.message}</div>;

  return (
    <div style={{ padding: 20 }}>
      <h3>Connection Status: {readyState}</h3>
      
      {/* 2. Pass stream data & emission callback to the bridge */}
      <ProtocolBridge 
        events={events} 
        emitEvent={emitEvent} 
      />
    </div>
  );
}

Features

• Component Tree Resolution: Recursive dictionary parser mapping A2UI Catalog layout & primitive components 1:1 to Cloudscape.
• Auto-generated Tables: Paginated sorting tables that automatically convert status strings (e.g. "Success", "Failed") to native <StatusIndicator> icons.
• HITL Form Engine: Validates inputs (regex, min/max length, required fields) and emits USER_RESPONSE and USER_CANCEL events.
• Reactive Data Binding: live pointer resolving (e.g. $/deployment/message) connected via useSyncExternalStore for granular updates from DATA_MODEL_UPDATE events. See DATA_MODEL_UPDATE.md.
• Multi-surface Layouts: Route components dynamically to the main layout, tools sidebar, or navigation drawer.
• Security-First Fields: Click-to-reveal PropertyRedact wrapper prevents shoulder-surfing for sensitive API keys, passwords, and tokens.
• Dual-Panel Playground: Test your JSON payloads in real time at the /playground route with shareable encoded URL hash states.

Mapped Catalog Components

The renderer fully maps the following A2UI components:

| Category | Components | |---|---| | Layouts | Row · Column · List · Card · Tabs · Modal | | Primitives | Text · Image · Icon · Divider | | Interactions | Button · TextField · CheckBox · ChoicePicker · DateTimeInput | | Specialized | Table (auto-columns, pagination) · PropertyRedact (shoulder-surf protection) |

API Reference

<ProtocolBridge />

Renders the A2UI event tree and manages the internal layout shell.

Props

interface ProtocolBridgeProps {
  /** The accumulated array of A2UI Protocol events */
  events: AgUiEvent[];
  /** Callback emitted when the client sends a response, cancellation, or error */
  emitEvent: (event: OutboundClientEvent) => Promise<void>;
  /** Optional sessionId to uniquely identify this renderer instance */
  sessionId?: string;
}

useSSEAgUiEvents(options)

Server-Sent Events hook with exponential reconnection backoff and inbound event validation.

Options

interface SSEHookOptions {
  /** The URL to connect to for the event stream */
  endpoint: string;
  /** The HTTP POST URL for emitting client events (defaults to endpoint) */
  emitEndpoint?: string;
  /** Automatically reconnect on disconnect (default: true) */
  reconnect?: boolean;
  /** Maximum number of reconnection attempts (default: 5) */
  maxRetries?: number;
}

Return Value (SSEHookResult)

• events: AgUiEvent[] — Validated inbound events accumulated from connection startup.
• emitEvent: (event: OutboundClientEvent) => Promise<void> — Function to POST outbound actions back to the server.
• readyState: 'connecting' | 'open' | 'closed' | 'error' — Connection state.
• error: Error | null — Connection errors if retries are exhausted.
• reconnectAttempt: number — Count of current reconnect attempts.
• reset: () => void — Clears events and establishes a new connection.

useWebSocketAgUiEvents(options)

WebSocket hook supporting bidirectional streaming, keep-alive pinging, and validation.

Options

interface WSHookOptions {
  /** The WebSocket server URL (ws:// or wss://) */
  endpoint: string;
  /** Automatically reconnect on socket failure (default: true) */
  reconnect?: boolean;
  /** Maximum number of reconnection attempts (default: 5) */
  maxRetries?: number;
  /** Keepalive ping interval in milliseconds (default: 30000) */
  pingInterval?: number;
}

Return Value (WSHookResult)

Returns the same hook result structure as useSSEAgUiEvents, but sends outbound events directly through the WebSocket channel.

Validation Utilities

Verify incoming and outgoing payloads:

import { validateAgUiEvent, validateOutboundEvent } from 'agui-cloudscape-renderer';

// Validate inbound event (returns ValidationResult)
const resIn = validateAgUiEvent(rawEvent);
if (!resIn.ok) {
  console.error("Invalid event:", resIn.error.message, "at path:", resIn.error.path);
}

// Validate outbound event
const resOut = validateOutboundEvent(rawOutbound);

Contributor Guide

If you want to build and test the renderer codebase:

Development Setup

# Clone the repository
git clone https://github.com/golevishal/agui-cloudscape-renderer.git
cd agui-cloudscape-renderer

# Install package dependencies
npm install

# Start the local development server (Vite app)
npm run dev

Route Index

• http://localhost:5173/ - Interactive demo simulating simulated HITL flow.
• http://localhost:5173/playground - JSON protocol playground.

Commands

# Code Style checking
npm run lint

# Run Vitest test suite
npm run test

# Bundle library for publishing (outputs to dist-lib/)
npm run build:lib

# Local Dry Run of the package npm bundle
npm pack --dry-run

Contributing

Please see CONTRIBUTING.md for details on filing issues, submitting pull requests, and codebase guidelines.

License

MIT © Vishal Gole