🧩 Agora - Open-Source AI Agent Chat Platform

Brutally simple. Extremely modular. Production-ready.

Agora is a minimal, open-source chat platform for running AI agent frameworks. Think "ChatGPT, but open and composable."

Live Demo: https://agora-federico-de-pontes-projects.vercel.app

✨ Features

• 🎯 Modular Agents - Each agent self-contained with own config, memory, and tools
• 🔄 Real-time Streaming - SSE-based token streaming for instant responses
• 💾 BYOK (Bring Your Own Key) - Encrypted API key management with Fernet
• 🔐 Supabase Auth - User authentication and row-level security
• 🎨 Dark Mode UI - Clean, modern interface
• 🚀 Vercel Deployment - Serverless Python backend + Next.js frontend
• 🧪 No Framework Bloat - Direct OpenAI API calls, no LangChain/CrewAI overhead
• 📊 Error Tracking - Sentry integration for production monitoring
• 🧪 E2E Testing - Comprehensive Playwright test suite (21 tests)

🏗️ Architecture

┌──────────────────────────────────────────┐
│ Vercel Deployment (Single Domain)       │
│                                          │
│  ┌────────────────────────────────────┐ │
│  │ FRONTEND (Next.js 15)              │ │
│  │  - Chat UI                         │ │
│  │  - SSE client (EventSource)        │ │
│  │  - Agent selector                  │ │
│  │  - Supabase Auth UI                │ │
│  └───────────────┬────────────────────┘ │
│                  ↓                       │
│  ┌────────────────────────────────────┐ │
│  │ BACKEND (Python 3.12 Serverless)   │ │
│  │  - /api/health                     │ │
│  │  - /api/agents                     │ │
│  │  - /api/chat-stream (SSE)          │ │
│  │  - /api/keys/* (BYOK management)   │ │
│  │  - Orchestrator + multi-agent      │ │
│  └───────────────┬────────────────────┘ │
└──────────────────┼──────────────────────┘
                   ↓
        ┌──────────────────────┐
        │ Supabase             │
        │  - PostgreSQL DB     │
        │  - Auth (JWT)        │
        │  - RLS policies      │
        └──────────────────────┘

🚀 Quick Start

Deploy to Vercel (Recommended)

1. Click the "Deploy with Vercel" button above
2. Configure environment variables (see below)
3. Deploy!

Manual Deployment to Vercel

1. Clone the repository

git clone https://github.com/yourusername/agora.git
cd agora

2. Set up environment variables

cp .env.example .env
# Edit .env and add your keys (see Environment Variables section)

3. Install Vercel CLI and deploy

npm install -g vercel
vercel

4. Configure Vercel project settings

• Root Directory: frontend (set in Vercel dashboard)
• Framework Preset: Next.js
• Build Command: npm run build
• Output Directory: .next

5. Add environment variables in Vercel dashboard

Go to your project → Settings → Environment Variables and add:

• DEPLOYMENT_MODE=production
• SUPABASE_URL=https://your-project.supabase.co
• SUPABASE_ANON_KEY=your-anon-key
• SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
• NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
• NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
• ENCRYPTION_MASTER_KEY=your-fernet-key (generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
• OPENAI_API_KEY=sk-proj-your-key (default key for server-side operations)
• SENTRY_DSN=https://your-sentry-dsn@sentry.io/your-project (optional)
• NEXT_PUBLIC_SENTRY_DSN=https://your-sentry-dsn@sentry.io/your-project (optional)

6. Redeploy

vercel --prod

📁 Project Structure

agora/
├── frontend/                    # Next.js 15 frontend
│   ├── app/
│   │   ├── page.tsx             # Main chat page
│   │   └── layout.tsx           # Root layout
│   ├── components/
│   │   ├── ChatInterface/       # Chat UI components
│   │   ├── auth/                # Authentication components
│   │   └── ui/                  # shadcn/ui primitives
│   ├── lib/
│   │   ├── sse-client.ts        # SSE client for streaming
│   │   ├── api/                 # API client methods
│   │   └── hooks/               # React Query hooks
│   ├── tests/                   # Playwright E2E tests
│   │   ├── 01-frontend.spec.ts
│   │   ├── 02-api.spec.ts
│   │   └── 03-integration.spec.ts
│   ├── sentry.client.config.ts  # Sentry client config
│   ├── sentry.server.config.ts  # Sentry server config
│   └── playwright.config.ts     # Playwright configuration
│
├── api/                         # Python serverless functions
│   ├── health.py                # Health check endpoint
│   ├── agents.py                # List available agents
│   ├── chat.py                  # Non-streaming chat
│   ├── chat-stream.py           # SSE streaming chat
│   ├── keys/                    # BYOK endpoints
│   │   ├── save.py              # Save encrypted API key
│   │   ├── list.py              # List user's keys
│   │   ├── [provider].py        # Delete key
│   │   └── test/[provider].py   # Test key exists
│   └── _lib/                    # Shared utilities
│       ├── utils/
│       │   └── supabase_client.py
│       ├── agents/              # Agent primitives
│       │   ├── base_primitive.py
│       │   ├── role_primitive.py
│       │   └── swarm_primitive.py
│       └── sentry_util.py       # Sentry error tracking
│
├── backend/                     # Legacy FastAPI code (for reference)
├── requirements.txt             # Python dependencies
├── vercel.json                  # Vercel configuration
├── .env.example                 # Environment variables template
├── LICENSE                      # MIT License
└── .github/
    └── workflows/               # CI/CD pipelines
        ├── test.yml             # Run tests on PR
        ├── lint.yml             # Linting checks
        └── deploy.yml           # Auto-deploy to Vercel

🧩 Agent Primitives

Agora uses composable primitives instead of hardcoded agents. Users create custom agents by writing simple YAML files.

Role Primitive (type: role)

Simple LLM with configurable system prompt. Perfect for specialized personas and single-purpose agents.

Use cases: Academic writer, code reviewer, customer service bot, content generator

Example:

name: "Academic Writer"
type: role
description: "Writes academic-style content"
system_prompt: "You are an expert academic writer..."

Swarm Primitive (type: swarm)

Parallel task decomposition. Breaks complex queries into sub-tasks, executes in parallel, then synthesizes results.

Use cases: Multi-perspective research, complex analysis, divide-and-conquer problems

Example:

name: "Research Team"
type: swarm
description: "Multi-agent research"
max_parallel: 3

Bulk Primitive (type: bulk)

Batch processing of lists/items with structured output. Extracts items, processes each, returns formatted table/JSON.

Use cases: "Analyze these 10 companies", "Summarize each article", "Score these resumes"

Example:

name: "Company Analyzer"
type: bulk
description: "Analyze multiple companies"
item_prompt_template: "Analyze: {{item}}"

Pipeline Primitive (type: pipeline)

Sequential multi-step workflows where each step feeds the next. Supports variable interpolation.

Use cases: Research → Outline → Draft → Review, Data extraction → Analysis → Visualization

Example:

name: "Research Pipeline"
type: pipeline
steps:
  - name: "research"
    prompt: "Research: {{query}}"
  - name: "draft"
    prompt: "Write article: {{research}}"

See ARCHITECTURE.md for complete documentation.

🌐 API Reference

See API.md for full API documentation.

Quick Examples

Health Check:

curl https://your-deployment.vercel.app/api/health

List Agents:

curl https://your-deployment.vercel.app/api/agents

Chat (SSE Streaming):

curl -N "https://your-deployment.vercel.app/api/chat-stream?query=Hello&agent_name=auto"

🛠️ Local Development

Frontend Development

cd frontend
npm install
npm run dev
# Open http://localhost:3000

Backend Development (with Supabase)

# Install Supabase CLI
npm install -g supabase

# Start Supabase locally
supabase start

# Run Python serverless locally (via Vercel)
vercel dev

Running Tests

# E2E tests with Playwright
cd frontend
npm run test:e2e

# With UI mode for debugging
npm run test:e2e:ui

# View test report
npm run test:e2e:report

🔐 Environment Variables

See .env.example for a complete, documented list of all environment variables.

Required:

• SUPABASE_URL - Your Supabase project URL
• SUPABASE_ANON_KEY - Supabase anonymous key
• SUPABASE_SERVICE_ROLE_KEY - Supabase service role key
• ENCRYPTION_MASTER_KEY - Fernet encryption key for BYOK
• OPENAI_API_KEY - Default OpenAI API key (for server-side operations)

Optional:

• SENTRY_DSN - Sentry error tracking DSN
• VERCEL_BYPASS_KEY - Bypass deployment protection for E2E tests

🧪 Testing

Agora has comprehensive test coverage:

• 21 Playwright E2E tests:
  • Frontend UI tests (6)
  • Backend API tests (9)
  • Integration tests (6)
• CI/CD: All tests run automatically on PRs via GitHub Actions
• Coverage: 85.7% passing (3 tests blocked by deployment protection)

Run tests locally:

cd frontend
VERCEL_BYPASS_KEY=your-key npm run test:e2e

📊 Monitoring & Observability

Error Tracking (Sentry)

Agora integrates with Sentry for error tracking:

1. Sign up at sentry.io
2. Create a new Next.js project
3. Add SENTRY_DSN and NEXT_PUBLIC_SENTRY_DSN to your environment variables
4. Errors will be automatically tracked in production

Performance Monitoring (Vercel Analytics)

Vercel Analytics is automatically enabled on Vercel deployments.

View metrics at: https://vercel.com/[team]/[project]/analytics

Logs

View serverless function logs:

vercel logs [deployment-url]

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick start:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

MIT License - see LICENSE file for details.

🎯 Roadmap

Phase 1: Production-Ready (Current)

• Vercel serverless deployment
• SSE streaming chat
• BYOK system
• Multi-agent orchestration
• E2E test suite
• CI/CD pipeline
• Error tracking (Sentry)
• Real Supabase Auth (in progress)

Phase 2: Enterprise Features

• Multi-tenancy (organizations)
• Team collaboration
• Usage tracking & limits
• Audit logging
• Rate limiting

Phase 3: SaaS

• Stripe billing integration
• Subscription tiers
• Admin dashboard
• User analytics

Phase 4: Self-Hosted

• Docker Compose deployment
• Kubernetes manifests
• SSO (SAML, OIDC)
• Custom agent upload

Future

• Agent marketplace
• Plugin system
• Mobile app
• Voice input/output
• Self-hosted LLM support (Ollama, LocalAI)

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

⭐ Star History

If you find Agora useful, please consider starring the repository!

---

Built with ❤️ by the open-source community

Agora v0.3.0 - "Production Ready"