Skip to content

README.md

Latest commit

 

History

History
185 lines (136 loc) · 6.98 KB

README.md

File metadata and controls

185 lines (136 loc) · 6.98 KB

Featest - AI-Powered Feature Request App

Python Lit Google ADK A2UI A2A

An end to end demonstration of A2UI + A2A protocols on a concrete use case: a feature request voting application powered by AI.

Featest Demo

🏗️ Architecture

The application implements a full-stack AI architecture combining multiple Google protocols and frameworks:

  • Backend: A Python Starlette server exposes the agent via the A2A protocol, enabling standard HTTP-based communication with AI agents
  • Agent Pipeline: Built with Google ADK, a Sequential Agent Pattern chains two specialized agents:
    • Controller Agent - Executes business logic through CRUD tools (list, add, vote, comment features)
    • View Agent - Transforms controller output into A2UI components (cards, buttons, lists)
  • Frontend: A Lit web client processes the streaming A2UI response and renders native components progressively

Architecture Diagram

📐 Source: diagrams/architecture.d2

🔑 Key Concepts

A2UI (Agent-to-User Interface)

A2UI is a JSONL-based streaming UI protocol that enables AI agents to generate platform-agnostic user interfaces. Instead of returning plain text, the agent returns structured UI components (cards, buttons, lists) that the client renders natively.

Why A2UI?

  • 🎨 Rich UIs - AI generates interactive components, not just text
  • ⚡ Streaming - Progressive rendering as the response arrives
  • 📱 Platform Agnostic - Same schema works for web, mobile, or native apps

A2A (Agent-to-Agent Protocol)

A2A is Google's open protocol for agent interoperability. It provides a standard way to communicate with AI agents over HTTP, enabling agents to be deployed as services.

Why A2A?

  • 🔌 Interoperability - Agents can talk to each other using a common protocol
  • 🌐 HTTP-Native - Deploy agents as standard web services
  • 📝 Task-Based - Structured request/response model with task lifecycle

Sequential Agent Pattern

The backend uses a two-agent pipeline:

  1. Controller Agent - Executes business logic via CRUD tools (list, add, vote, comment)
  2. View Agent - Takes controller output and formats it as A2UI components

This separation allows each agent to focus on its specialty: the controller on data operations, the view on presentation.

✨ Features

Feature Description
📋 List Features View all feature requests sorted by votes
➕ Add Features Submit new feature ideas via natural language
👍 Upvote Vote for features you want to see implemented
💬 Comment Add feedback and discuss features
🧠 Rationalize AI analyzes and ranks features by importance
💡 Suggest AI recommends new features based on patterns
🏷️ Tag AI automatically categorizes features

📸 Screenshots

Initial State List Features
Initial State List Features
Upvote Feature Leave Comment
Upvote Comment
Rationalize Features Suggest Features
Rationalize Suggest
Tag Features
Tag

🚀 Quick Start

Prerequisites

  • Python 3.14+
  • Node.js 18+
  • uv package manager
  • just command runner

Installation

# Clone the repository
git clone https://github.com/yourname/featest.git
cd featest

# Install Python dependencies
uv sync

# Install client dependencies
cd client && npm install && cd ..

Configuration

Create a .env file from the sample:

cp .env.sample .env

Configure your environment variables:

GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_RUN_LOCATION=your-region

Running

# Terminal 1: Start the backend
just web

# Terminal 2: Build & watch the client
just client-watch

Navigate to http://localhost:8000

Usage Examples

Type natural language commands in the chat input:

Command Action
show features Display all feature requests
add feature: Dark Mode - Add dark theme support Add a new feature
vote for dark mode Vote for a feature
comment on mobile app: This is essential! Add a comment
rationalize features Get AI analysis of feature priorities

🧪 Development

Quality Checks

# Run all checks (type check, lint, format, tests)
just check

# Client checks
just client-check

📚 Resources

📄 License

MIT License - See LICENSE.txt