GenUI Platform - Full-Stack Generative UI Agent System

A production-grade framework for building multi-agent systems with dynamic, real-time UI generation using LangGraph, FastAPI, React, and the AG-UI protocol.

Architecture Overview

Frontend (React + TypeScript + CopilotKit)
              ↕ (SSE / AG-UI Events)
CopilotKit Runtime
              ↕ (HTTP)
Backend (FastAPI + LangGraph)
    ├── Supervisor Agent
    ├── Specialist Agents
    └── Tool Registry (MCP)

Project Structure

GenUI/
├── backend/
│   ├── app.py                 # FastAPI entry point
│   ├── models/
│   │   ├── ag_ui_events.py   # AG-UI protocol event schemas
│   │   └── a2ui_schema.py    # (Phase 2) Declarative UI schema
│   ├── agents/
│   │   ├── supervisor.py     # (Phase 1) Supervisor agent
│   │   └── specialists.py    # (Phase 5) Specialist agents
│   ├── tools/
│   │   └── registry.py       # (Phase 1) Tool definitions
│   ├── requirements.txt
│   └── .env
├── frontend/
│   ├── src/
│   │   ├── App.tsx           # Main app component
│   │   ├── hooks/
│   │   │   └── useStream.ts  # SSE consumer hook
│   │   ├── stores/
│   │   │   └── stateStore.ts # Zustand state management
│   │   └── components/       # (Phase 2) Component registry
│   ├── index.html
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── tailwind.config.js
└── docs/                      # (Phase 6) Documentation

Setup & Running

1. Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run server
python app.py
# Backend runs on http://localhost:8000

2. Frontend Setup

cd frontend

# Install dependencies
npm install

# Run dev server
npm run dev
# Frontend runs on http://localhost:5173

3. Verify End-to-End

1. Open http://localhost:5173 in your browser
2. Type a query in the text area
3. Click "Send Query"
4. Watch SSE events stream in real-time from the backend

Expected flow:

• Query sent
• RUN_STARTED event
• STATE_SNAPSHOT event
• TEXT_MESSAGE_CONTENT events (agent thinking)
• RUN_FINISHED event

---

Phase Breakdown

All phases have been fully implemented, tested, and documented.

Phase 0: Foundation &Spec Study ✅ (Complete)

• Project scaffolding & directory structure setup.
• FastAPI skeleton & SSE streaming endpoint (/api/agent/stream).
• React + TypeScript setup with Tailwind CSS.
• Full AG-UI event catalogue modeled as Pydantic models.
• SSE event consumer hook (useStream).
• Zustand state store (stateStore) for React state synchronization.

Phase 1: Agent Backbone & Basic Tool Execution ✅ (Complete)

• LangGraph supervisor node for dynamic request routing.
• 3 specialist node stubs (DataRetrieval, Analysis, Summarise).
• Extensible tool registry with mock tools (search_knowledge_base, fetch_data, calculate_metric).
• Real-time SSE streaming of thinking blocks (TEXT_MESSAGE_CONTENT) and tool states.
• Confidence score routing output.
• Artificial 5-second long-running tool execution to test SSE buffer flushing.

Phase 2: Controlled Generative UI ✅ (Complete)

• Custom components library (DataCard, ChartPanel, SummaryTable, StatusBadge).
• Registered custom component renderers as agent-callable actions.
• Strict props validation and error banners for component inputs.
• Theme compatibility (dark mode Outfits styling).

Phase 3: Declarative Generative UI ✅ (Complete)

• Recursive layout tree compiler (UIRenderer.tsx) parsing the A2UI spec.
• Security whitelist mapping allowed component tags (Card, Table, Form, Chart, List, Badge, Button).
• Safe RFC 6901 JSON pointer resolver for dynamic runtime data bindings.
• Gating filter rejecting unwhitelisted elements at rendering boundaries.

Phase 4: State Synchronisation & Predictive Updates ✅ (Complete)

• Bidirectional state sync (user edits propagate to agent state, agent updates reflect in UI).
• Live optimistic UI state updates for latency-free typing.
• Predictive intermediate progress states ("Fetching sales records... X% complete") streamed during tool runs.
• Custom state synchronization hook (useCoAgent).

Phase 5: Human-in-the-Loop & Approval Workflows ✅ (Complete)

• Risk-tiered authorization gating checkpoints using LangGraph interrupts.
• Context-aware PolicyEngine evaluating confidence scores and budget overrun flags.
• Interactive operator approval overlays (ApprovalCard) to edit or submit decisions.
• Persistent JSON audit logs (audit_log.json) storing decisions, metrics, and timestamps.

Phase 6: Open GenUI — MCP Apps & Canvas ✅ (Complete)

• Sandboxed iframe embedding (simulated-mcp-app endpoint).
• Bidirectional message passing handshake protocol (postMessage) for vector drawing sync.
• Collaborative whiteboard canvas with tools for shapes, colors, text annotations, and wipe actions.
• Synced collaborative task checklist with agent auto-generation capabilities.

Phase 7: Multi-Specialist Orchestration ✅ (Complete)

• Full multi-agent pool with 4 specialists (Search, Analysis, Recommendation, Report).
• Concurrent fork-and-join parallel agent nodes branching.
• Safe, recursive merge_results state reducer to prevent race conditions during parallel joins.
• Graceful degradation and error boundaries handling specialist failures.

Phase 8: Testing, Documentation, & CI/CD ✅ (Complete)

• Comprehensive backend automated testing suite (9 pytest test cases covering policy engine, tool registry, and supervisor graph routing).
• Flawless frontend TypeScript compilation and production packaging builds.
• Automated GitHub Actions workflow (.github/workflows/ci.yml) protecting the codebase on push/PRs.
• Premium guides: DEVELOPER_GUIDE.md (developer extension manual) and MARKET_RESEARCH_BOT_FLOW.md (end-to-end execution flow walkthrough).

---

Tech Stack

Component	Technology	Version
Backend Runtime	FastAPI	0.104.1
Agent Framework	LangGraph	0.0.51
Agent Orchestration	LangChain	>=0.1.46,<0.2.0
Data Validation	Pydantic	2.4.2
Frontend Framework	React	18.2.0
Frontend Build	Vite	5.4.21
Language	TypeScript	5.2.2
Styling	Tailwind CSS	3.3.6
State Management	Zustand	4.4.1

---

Key Concepts

AG-UI Protocol

Event-based bidirectional communication between agent and UI. Key events:

• RUN_STARTED / RUN_FINISHED — Lifecycle tracking
• TEXT_MESSAGE_* — Streaming agent thoughts
• TOOL_CALL_* — Tool execution with progress
• STATE_SNAPSHOT / STATE_DELTA — Shared state updates
• INTERRUPT / USER_APPROVAL — Human-in-the-loop checkpoints

A2UI (Declarative UI)

Agents describe UIs as JSON structures, not code:

{
  "type": "Card",
  "props": { "title": "...", "description": "..." },
  "children": [
    { "type": "Badge", "props": { "label": "...", "status_type": "success" } }
  ]
}

This is safe (no XSS), portable (same JSON on web/mobile), and scalable.

Multi-Agent Supervision

Supervisor agent routes user requests → Specialist agents handle domains → Results aggregate back to UI.

---

References

• Research Document: Generative UI Agent Research Plan.pdf
• AG-UI Spec: https://docs.ag-ui.com
• LangGraph Docs: https://langchain-ai.github.io/langgraph/
• CopilotKit Docs: https://docs.copilotkit.ai/
• A2UI Spec: https://developers.googleblog.com/a2ui-v0-9-generative-ui/

---

Status: 100% Completed (Phases 0 to 8 fully verified)