feat: Add Motia-based A2UI Protocol Server

[rohitg00]

Add Motia-Based A2UI Protocol Server

Description

This PR adds a production-ready A2UI protocol server implemented using Motia, an open-source event-driven backend framework.

What's Included

• ✅ Complete A2UI v0.9 protocol implementation
• ✅ REST API for surface management
• ✅ Real-time streaming via WebSocket
• ✅ Gemini AI integration for dynamic UI generation
• ✅ Visual Workbench for debugging flows
• ✅ Session isolation and state management
• ✅ Interactive demo client

Screenshots

AI-Powered Dynamic UI Generation

Generate flight booking forms, dashboards, todo apps from natural language

Motia Workbench - Visual Flow Debugging

See event flow and debug A2UI steps in real-time

Weather Dashboard (22 components from one prompt)

API Endpoints

Method	Endpoint	Description
POST	/a2ui/surfaces	Create surface
GET	/a2ui/surfaces	List surfaces
GET	/a2ui/surfaces/:id	Get surface
PUT	/a2ui/surfaces/:id/components	Update components
PATCH	/a2ui/surfaces/:id/data	Update data model
DELETE	/a2ui/surfaces/:id	Delete surface
POST	/a2ui/actions	Handle user action
POST	/demo/generate-ui	Gemini AI generation

File Structure

server/motia/
├── motia.config.ts           # Framework configuration
├── package.json
├── README.md
├── .env.example              # Environment template
│
├── public/
│   ├── demo.html             # Interactive demo client
│   └── *.png                 # Screenshots
│
├── steps/
│   ├── a2ui/                 # Core protocol steps
│   │   ├── create-surface.step.ts
│   │   ├── update-components.step.ts
│   │   ├── generate-ui.step.ts
│   │   └── ...
│   │
│   ├── streams/              # Real-time streams
│   │   ├── a2ui-surface.stream.ts
│   │   └── a2ui-message.stream.ts
│   │
│   └── demo/                 # Demo agents
│       ├── restaurant-agent.step.ts
│       └── gemini-ui-generator.step.ts

Testing

# Quick Start
cd server/motia
npm install
echo "GEMINI_API_KEY=your_key" > .env
npm run dev

# Test APIs
bash test-a2ui.sh

# Interactive Demo
npx serve public -p 8080
# Open http://localhost:8080/demo.html

Tested With

• ✅ Existing Lit renderer (samples/client/lit)
• ✅ Demo HTML client (public/demo.html)
• ✅ Gemini 2.0 Flash for UI generation
• ✅ All A2UI v0.9 component types

Related

• Proposal: See PROPOSAL.md for detailed architecture
• Related Issues: Fixes https://github.com/google/A2UI/issues/288

Checklist

• [x] Code follows project conventions
• [x] README with setup instructions
• [x] API documentation
• [x] Demo client included
• [x] Screenshots included

Notes for Reviewers

1. Motia is polyglot framework compatible with A2UI
2. Uses GEMINI_API_KEY env var (same as existing samples)
3. Can work standalone or as gateway to Python ADK agents
4. All dependencies are well-maintained npm packages

---

Happy to address any feedback! 🚀