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
Try the interactive playground live: https://golevishal.github.io/agui-cloudscape-renderer/
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-domEnsure you import Cloudscape's global styles in your application's entrypoint:
import "@cloudscape-design/global-styles/index.css";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>
);
}- 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_RESPONSEandUSER_CANCELevents. - Reactive Data Binding: live pointer resolving (e.g.
$/deployment/message) connected viauseSyncExternalStorefor granular updates fromDATA_MODEL_UPDATEevents. See DATA_MODEL_UPDATE.md. - Multi-surface Layouts: Route components dynamically to the
mainlayout,toolssidebar, ornavigationdrawer. - Security-First Fields: Click-to-reveal
PropertyRedactwrapper prevents shoulder-surfing for sensitive API keys, passwords, and tokens. - Dual-Panel Playground: Test your JSON payloads in real time at the
/playgroundroute with shareable encoded URL hash states.
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) |
Renders the A2UI event tree and manages the internal layout shell.
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;
}Server-Sent Events hook with exponential reconnection backoff and inbound event validation.
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;
}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.
WebSocket hook supporting bidirectional streaming, keep-alive pinging, and validation.
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;
}Returns the same hook result structure as useSSEAgUiEvents, but sends outbound events directly through the WebSocket channel.
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);For reference implementations of the backend event streaming and HITL responses:
- 🚀 Lightweight FastAPI Backend: A mock Python server demonstrating SSE progress streams and bidirectional WebSocket form approvals.
- 🦜🕸️ LangGraph Integration Agent: An agent graph demonstrating human-in-the-loop task execution, intermediate tool states, progress tracking, and validation.
If you want to build and test the renderer codebase:
# 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 devhttp://localhost:5173/- Interactive demo simulating simulated HITL flow.http://localhost:5173/playground- JSON protocol playground.
# 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-runPlease see CONTRIBUTING.md for details on filing issues, submitting pull requests, and codebase guidelines.
MIT © Vishal Gole