语音代理构建

Prerequisites

• Python 3.10 or higher (download from python.org. Verify with python --version)
• Node.js 16+
• PostgreSQL 14+
• Docker (optional)

🎙️ Open Source AI Voice Agent Builder

The open source alternative to Retell, Synthflow, and Vapi - Build reliable, observable, and easily testable AI voice agents with a focus on developer experience.

Installation

1. Clone the repository

   git clone https://github.com/yourusername/ai-voice-agent-builder.git
   cd ai-voice-agent-builder
   

2. Backend Setup

   # Create virtual environment (requires Python 3.10+)
   python -m venv venv

   # Activate the virtual environment
   source venv/bin/activate          # macOS / Linux
   # venv\Scripts\activate           # Windows (PowerShell/CMD)

   # Install dependencies
   pip install -r requirements.txt

   # Set up environment variables
   # Create a .env file in the project root with the required configuration:
   #   DATABASE_URL=postgresql://<user>:<password>@<host>/<dbname>
   #   JWT_SECRET_KEY=<your-secret-key>
   #   ENCRYPTION_KEY=<your-encryption-key>

   # Run database migrations
   alembic upgrade head

   # Seed service providers, models, and voices
   python dev/seed.py

   # Start the backend server with uvicorn (auto-reload for development)
   uvicorn main:app --host 0.0.0.0 --port 8000 --reload

   # Enterprise edition
   # uvicorn main_ee:app --host 0.0.0.0 --port 8000 --reload
   

Seed Data (dev/seed.py)

The seed script sets up your initial data — it creates an owner user, organization, and populates all supported service providers (LLM, STT, TTS), their models, and voices from dev/dev-data.json.

When you run python dev/seed.py, it will interactively prompt you for: - Organization name — your organization/workspace name - Owner email — the admin user's email (used for login) - Password — must be 8+ characters with uppercase, lowercase, digit, and special character

To auto-populate API keys for providers during seeding, set the corresponding environment variables in your .env file before running the script. For example:

   OPENAI_API_KEY=sk-...
   DEEPGRAM_API_KEY=...
   ELEVENLABS_API_KEY=...
   CARTESIA_API_KEY=...
   

3. Frontend Setup

   cd frontend

   # Install dependencies
   npm install

   # Start the frontend dev server (Next.js + Turbopack on :3000)
   npm run dev
   

4. Access the application - Frontend: http://localhost:3000 - Backend API: http://localhost:8000 - API Documentation: http://localhost:8000/docs

Docker Setup

```bash

Build and run with Docker Compose

docker-compose up -d

🚀 Quick Start

API Structure

Our codebase follows a clean architecture pattern:

core/
├── api/v1/              # FastAPI route handlers
│   ├── agents.py
│   ├── auth.py
│   ├── channels.py
│   ├── models.py
│   ├── organizations.py
│   ├── service_providers.py
│   └── voices.py
├── services/            # Business logic layer
│   ├── agent_service.py
│   ├── agent_factory_service.py
│   ├── voice_service.py
│   ├── channel_service.py
│   └── model_service.py
├── models/              # SQLAlchemy ORM models
│   ├── agent.py
│   ├── organization.py
│   ├── service_provider.py
│   ├── voice.py
│   └── user.py
├── middleware/           # Auth & request middleware
│   └── auth.py
├── utils/               # Utility functions
│   └── encryption.py    # AES encryption for API keys
├── bot.py               # Voice pipeline entry point
└── database/            # DB session & connection
dev/
├── seed.py              # Data seeding script
└── dev-data.json        # Provider/model/voice definitions