Voice Agent Template

This repository is a reference project for deploying and running voice-agent model infrastructure with a local backend/frontend workflow.

The default setup in this public template is:

• deploy ASR and TTS model servers on AWS with Terraform + EC2
• run the backend locally
• run the frontend locally

Prerequisites

Before running the stack, make sure you have:

1. An AWS account with credentials configured locally
2. Terraform installed: https://developer.hashicorp.com/terraform/install
3. uv installed for the Python backend
4. Node.js installed for the frontend
5. A SEA-LION API key for the default LLM configuration

For the default Terraform + EC2 path, make sure your AWS account has enough EC2 GPU quota and regional capacity for the G-series instances you plan to launch.

SEA-LION API key guide: https://docs.sea-lion.ai/guides/inferencing/api

Recommended Quickstart: Terraform + EC2

This is the primary supported path in the repo today. It deploys the ASR and TTS model servers on EC2, then connects your local backend and frontend to those model endpoints.

For more detail, see the Terraform models-only guide.

1. Deploy the model servers with Terraform

From the repository root:

cd iac/terraform/models-only/networking
terraform init
terraform apply -var-file="../common.tfvars"

cd ../compute
terraform init
terraform apply -var-file="../common.tfvars" -var-file="terraform.tfvars"

After the apply completes, print the backend environment values:

../scripts/print_model_env.sh

That command prints values such as QWEN3_ASR_BASE_URL and QWEN3_TTS_BASE_URL that you will paste into backend/.env.

2. Configure and run the backend

Create the backend environment file:

cd backend
cp .env.example .env

Then edit backend/.env and set:

SEALION_API_KEY=your_api_key_here
QWEN3_ASR_BASE_URL=http://your-asr-host:8091
QWEN3_TTS_BASE_URL=http://your-tts-host:8092

Install dependencies and start the backend:

uv sync
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

The backend will be available at http://localhost:8000.

3. Configure and run the frontend

Open a new terminal and create the frontend environment file:

cd frontend/client
cp .env.example .env

Make sure frontend/client/.env contains:

BACKEND_BASE_URL=http://localhost:8000

Then install dependencies and start the frontend:

npm install
npm run dev

The frontend will usually be available at http://localhost:3000.

Additional Docs

• Terraform models-only detailed setup
• Backend local development
• Frontend local development

Work In Progress: CloudFormation + SageMaker

The alternative CloudFormation + SageMaker path is still experimental. It is intended for the same local backend/frontend workflow, but it should not be treated as the default path yet.

If you want to explore it, see the CloudFormation models-only guide.

Docker build note

When building images for AWS, you may need --platform linux/amd64 so the resulting images match the deployment environment.