A complete starter project for building voice AI apps with LiveKit Agents for Python.

🚀 Quick Deployment: See Docker Deployment Steps for EC2/OpenVidu deployment.

The starter project includes:

• A simple voice AI assistant based on the Voice AI quickstart
• Voice AI pipeline based on OpenAI, Cartesia, and Deepgram
  • Easily integrate your preferred LLM, STT, and TTS instead, or swap to a realtime model like the OpenAI Realtime API
• Eval suite based on the LiveKit Agents testing & evaluation framework
• LiveKit Turn Detector for contextually-aware speaker detection, with multilingual support
• LiveKit Cloud enhanced noise cancellation
• Integrated metrics and logging

This starter app is compatible with any custom web/mobile frontend or SIP-based telephony.

Clone the repository and install dependencies to a virtual environment:

cd agent-starter-python
uv sync

Set up the environment by copying .env.example to .env.local and filling in the required values:

• LIVEKIT_URL: Use LiveKit Cloud or run your own
• LIVEKIT_API_KEY
• LIVEKIT_API_SECRET
• OPENAI_API_KEY: Get a key or use your preferred LLM provider
• DEEPGRAM_API_KEY: Get a key or use your preferred STT provider
• CARTESIA_API_KEY: Get a key or use your preferred TTS provider

You can load the LiveKit environment automatically using the LiveKit CLI:

lk app env -w .env.local

Before your first run, you must download certain models such as Silero VAD and the LiveKit turn detector:

uv run python src/agent.py download-files

Next, run this command to speak to your agent directly in your terminal:

uv run python src/agent.py console

To run the agent for use with a frontend or telephony, use the dev command:

uv run python src/agent.py dev

In production, use the start command:

uv run python src/agent.py start

Get started quickly with our pre-built frontend starter apps, or add telephony support:

For advanced customization, see the complete frontend guide.

This project includes a complete suite of evals, based on the LiveKit Agents testing & evaluation framework. To run them, use pytest.

uv run pytest

Once you've started your own project based on this repo, you should:

1. Check in your uv.lock: This file is currently untracked for the template, but you should commit it to your repository for reproducible builds and proper configuration management. (The same applies to livekit.toml, if you run your agents in LiveKit Cloud)

2. Remove the git tracking test: Delete the "Check files not tracked in git" step from .github/workflows/tests.yml since you'll now want this file to be tracked. These are just there for development purposes in the template repo itself.

3. Add your own repository secrets: You must add secrets for OPENAI_API_KEY or your other LLM provider so that the tests can run in CI.

This project is production-ready and includes a working Dockerfile. To deploy it to LiveKit Cloud or another environment, see the deploying to production guide.

This agent has been customized to fetch room metadata and instructions from your API. Follow these steps to deploy:

Option A: Build for AMD64 (recommended for EC2)

# Build for x86_64/AMD64 architecture (most cloud instances)
docker buildx build --platform linux/amd64 -t agent-starter-python:latest --load .

Option B: Build locally (if on same architecture)

docker build -t agent-starter-python:latest .

Method 1: Save/Load (recommended for one-time deployment)

# Save the image to a tar file
docker save agent-starter-python:latest > agent-starter-python.tar

# Transfer to EC2 (replace YOUR_EC2_IP with actual IP)
scp agent-starter-python.tar ec2-user@YOUR_EC2_IP:/home/ec2-user/

# SSH into EC2 and load the image
ssh ec2-user@YOUR_EC2_IP
docker load < agent-starter-python.tar
docker images | grep agent-starter-python  # Verify

Method 2: Build directly on EC2

# Transfer source code
scp -r /path/to/agent-starter-python ec2-user@YOUR_EC2_IP:/home/ec2-user/

# SSH and build
ssh ec2-user@YOUR_EC2_IP
cd agent-starter-python
docker build -t agent-starter-python:latest .

Method 3: Docker Registry (recommended for production)

# Push to Docker Hub
docker tag agent-starter-python:latest your-username/agent-starter-python:latest
docker push your-username/agent-starter-python:latest

# Pull on EC2
ssh ec2-user@YOUR_EC2_IP
docker pull your-username/agent-starter-python:latest

Create an agent-AGENT_NAME.yaml file in your OpenVidu configuration folder:

# Docker image of the agent
docker_image: agent-starter-python:latest

# Whether to run the agent or not
enabled: true

# Environment variables (replace with your actual values)
environment:
  LIVEKIT_URL: "wss://your-livekit-url"
  LIVEKIT_API_KEY: "your-api-key"
  LIVEKIT_API_SECRET: "your-api-secret"  
  OPENAI_API_KEY: "your-openai-key"

This agent automatically fetches room metadata and instructions from your API:

• Metadata API: GET https://api.builder.holofair.io/api/livekit/rooms/metadata?roomName={roomName}
• Instructions API: GET https://api.builder.holofair.io/api/agents/instruction?instruction_id={id}&metaverse_id={id}

The agent will only join rooms where:

• Room metadata contains instruction_id > 0
• Uses metaverse_id from metadata (defaults to 1)

# Test manually (optional)
docker run --rm \
  -e LIVEKIT_URL="your-url" \
  -e LIVEKIT_API_KEY="your-key" \
  -e LIVEKIT_API_SECRET="your-secret" \
  -e OPENAI_API_KEY="your-openai-key" \
  agent-starter-python:latest

# Check container status
docker ps
docker logs <container-id>

• Architecture mismatch: Use --platform linux/amd64 when building on Mac for EC2
• Large image size: Ensure *.tar files are in .dockerignore
• Environment variables: Verify all required env vars are set in OpenVidu config
• API connectivity: Ensure EC2 can reach api.builder.holofair.io

This project is licensed under the MIT License - see the LICENSE file for details.