### Initialize and Start Development Environment

Source: https://github.com/deepgram-starters/fastapi-voice-agent/blob/main/AGENTS.md

Commands to initialize submodules, install dependencies, and start the backend and frontend servers.

```bash
# Initialize (clone submodules + install deps)
make init

# Set up environment
test -f .env || cp sample.env .env  # then set DEEPGRAM_API_KEY

# Start both servers
make start
# Backend: http://localhost:8081
# Frontend: http://localhost:8080
```

--------------------------------

### Initialize and start with Makefile

Source: https://github.com/deepgram-starters/fastapi-voice-agent/blob/main/README.md

Use the recommended Makefile approach to initialize the environment and start the application.

```makefile
make init
cp sample.env .env  # Add your DEEPGRAM_API_KEY
make start
```

--------------------------------

### Manual environment setup

Source: https://github.com/deepgram-starters/fastapi-voice-agent/blob/main/README.md

Manually clone the repository, set up the Python virtual environment, and install frontend dependencies.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/fastapi-voice-agent.git
cd fastapi-voice-agent
python3 -m venv venv
./venv/bin/pip install -r requirements.txt
cd frontend && corepack pnpm install && cd ..
cp sample.env .env  # Add your DEEPGRAM_API_KEY
```

--------------------------------

### Dependency Installation

Source: https://github.com/deepgram-starters/fastapi-voice-agent/blob/main/AGENTS.md

Commands to install backend and frontend dependencies.

```bash
python3 -m venv venv && ./venv/bin/pip install -r requirements.txt
```

```bash
cd frontend && corepack pnpm install
```

--------------------------------

### Manual FastAPI Server Startup

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Manually start the FastAPI application server without using the Makefile. This involves creating a virtual environment, installing dependencies, and running the application script.

```bash
# Manual startup without Makefile
python3 -m venv venv
./venv/bin/pip install -r requirements.txt
./venv/bin/python app.py
```

```text
# Server output:
# 🚀 FastAPI Voice Agent Server: http://localhost:8081
#    GET  /api/session
#    WS   /api/voice-agent (auth required)
#    GET  /api/metadata
```

--------------------------------

### Project Initialization Commands with Make

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Initialize the project by installing all dependencies using Makefile commands. This includes setting up the Python virtual environment and installing backend and frontend dependencies.

```bash
# Check prerequisites (git, python3, pip3)
make check-prereqs

# Initialize everything: submodules, venv, and dependencies
make init

# Install only backend dependencies
make install-backend

# Install only frontend dependencies
make install-frontend
```

--------------------------------

### Start Frontend Server

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Use this command to start only the frontend server. The server will be accessible on port 8080.

```bash
make start-frontend
```

--------------------------------

### Server Lifecycle Management

Source: https://github.com/deepgram-starters/fastapi-voice-agent/blob/main/AGENTS.md

Commands for starting, stopping, and rebuilding the application environment.

```bash
make start
```

```bash
# Terminal 1 — Backend
./venv/bin/python app.py

# Terminal 2 — Frontend
cd frontend && corepack pnpm run dev -- --port 8080 --no-open
```

```bash
lsof -ti:8080,8081 | xargs kill -9 2>/dev/null
```

```bash
rm -rf venv frontend/node_modules frontend/.vite
make init
```

--------------------------------

### Start Backend Server

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Use this command to start only the backend server. The server will be accessible on port 8081.

```bash
make start-backend
```

--------------------------------

### Start backend and frontend servers

Source: https://github.com/deepgram-starters/fastapi-voice-agent/blob/main/README.md

Run the backend and frontend services in separate terminal sessions.

```bash
# Terminal 1 - Backend (port 8081)
./venv/bin/python app.py

# Terminal 2 - Frontend (port 8080)
cd frontend && corepack pnpm run dev -- --port 8080 --no-open
```

--------------------------------

### Environment Configuration Example

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Configure the application using environment variables. The DEEPGRAM_API_KEY is required, while other settings like PORT, HOST, and SESSION_SECRET have sensible defaults or can be auto-generated.

```bash
# Create .env file from sample
cp sample.env .env

# Required configuration
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional configuration (defaults shown)
PORT=8081              # Backend API server port
HOST=0.0.0.0          # Server host binding

# Production security (auto-generated if not set)
SESSION_SECRET=your_secure_random_secret_here
```

--------------------------------

### Agent Function Calling Configuration

Source: https://github.com/deepgram-starters/fastapi-voice-agent/blob/main/AGENTS.md

Example of adding function definitions to the agent settings for tool use.

```json
{
  "agent": {
    "think": {
      "functions": [
        {
          "name": "get_weather",
          "description": "Get current weather",
          "parameters": { "type": "object", "properties": { "city": { "type": "string" } } }
        }
      ]
    }
  }
}
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/deepgram-starters/fastapi-voice-agent/blob/main/AGENTS.md

Examples of commit messages following the conventional commits format. Use these to maintain a consistent commit history.

```git
feat(fastapi-voice-agent): add diarization support
```

```git
fix(fastapi-voice-agent): resolve WebSocket close handling
```

```git
refactor(fastapi-voice-agent): simplify session endpoint
```

```git
chore(deps): update frontend submodule
```

--------------------------------

### Connect to Voice Agent WebSocket with JavaScript

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

JavaScript client example for establishing a bidirectional WebSocket connection to the voice agent. Authentication is performed via the WebSocket subprotocol using a session token. Send configuration messages and handle audio/JSON data.

```javascript
// JavaScript client example for connecting to the voice agent WebSocket
async function connectVoiceAgent() {
  // First, obtain a session token
  const sessionResponse = await fetch('http://localhost:8081/api/session');
  const { token } = await sessionResponse.json();

  // Connect to WebSocket with token in subprotocol
  const ws = new WebSocket(
    'ws://localhost:8081/api/voice-agent',
    [`access_token.${token}`]
  );

  ws.onopen = () => {
    console.log('Connected to voice agent');

    // Send configuration message to Deepgram
    ws.send(JSON.stringify({
      type: 'SettingsConfiguration',
      audio: {
        input: { encoding: 'linear16', sample_rate: 16000 },
        output: { encoding: 'linear16', sample_rate: 24000 }
      },
      agent: {
        listen: { model: 'nova-2' },
        speak: { model: 'aura-asteria-en' },
        think: {
          provider: { type: 'anthropic' },
          model: 'claude-3-haiku-20240307',
          instructions: 'You are a helpful voice assistant.'
        }
      }
    }));
  };

  ws.onmessage = (event) => {
    if (event.data instanceof Blob) {
      // Handle audio data from Deepgram
      playAudio(event.data);
    } else {
      // Handle JSON messages (transcripts, events)
      const message = JSON.parse(event.data);
      console.log('Received:', message.type, message);
    }
  };

  ws.onerror = (error) => {
    console.error('WebSocket error:', error);
  };

  ws.onclose = (event) => {
    console.log(`Connection closed: ${event.code} ${event.reason}`);
  };

  return ws;
}

// Send audio data to the voice agent
function sendAudio(ws, audioBuffer) {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(audioBuffer);
  }
}
```

--------------------------------

### Fetch Application Metadata with cURL

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Retrieve application metadata, such as title, description, and author, by making a GET request to the /api/metadata endpoint.

```bash
# Fetch application metadata
curl -X GET http://localhost:8081/api/metadata

# Response:
# {
#   "title": "FastAPI Voice Agent",
#   "description": "Get started using Deepgram's Voice Agent with this FastAPI demo app",
#   "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
#   "repository": "https://github.com/deepgram-starters/fastapi-voice-agent",
#   "useCase": "voice-agent",
#   "language": "python",
#   "framework": "fastapi",
#   "sdk": "N/A",
#   "tags": ["voice-agent", "conversational-ai", "voice-ai", "voice-bot", "python", "fastapi"]
# }
```

--------------------------------

### Deploy to Fly.io

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Commands to deploy the application to Fly.io. Includes launching the app, setting secrets, and deploying.

```bash
# Deploy to Fly.io
fly launch
fly secrets set DEEPGRAM_API_KEY=your_api_key
fly deploy
```

--------------------------------

### Run Conformance Tests

Source: https://github.com/deepgram-starters/fastapi-voice-agent/blob/main/AGENTS.md

Execute conformance tests for the application. This requires the application to be running.

```bash
# Run conformance tests (requires app to be running)
make test
```

--------------------------------

### Build and Run with Docker

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Commands to build a Docker image for the application and run it as a container. Requires setting the DEEPGRAM_API_KEY environment variable.

```bash
# Or build and run with Docker
docker build -f deploy/Dockerfile -t voice-agent .
docker run -p 8080:8080 -e DEEPGRAM_API_KEY=your_key voice-agent
```

--------------------------------

### Fly.io Deployment Configuration

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Configuration file for deploying the application to Fly.io. Specifies app name, primary region, build settings, and HTTP service configuration.

```toml
# fly.toml - Fly.io deployment configuration
app = 'deepgram-fastapi-voice-agent'
primary_region = 'iad'

[build]
  dockerfile = "deploy/Dockerfile"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = 'stop'
  auto_start_machines = true
  min_machines_running = 0
  processes = ['app']

[[vm]]
  memory = '256mb'
  cpu_kind = 'shared'
  cpus = 1
```

--------------------------------

### Agent Configuration Settings

Source: https://github.com/deepgram-starters/fastapi-voice-agent/blob/main/AGENTS.md

JSON structure for configuring audio, STT, TTS, and LLM providers sent from the frontend.

```json
{
  "type": "Settings",
  "audio": {
    "input": { "encoding": "linear16", "sample_rate": 16000 },
    "output": { "encoding": "linear16", "sample_rate": 16000 }
  },
  "agent": {
    "listen": { "provider": { "type": "deepgram", "model": "nova-3" } },
    "speak": { "provider": { "type": "deepgram", "model": "aura-2-thalia-en" } },
    "think": {
      "provider": { "type": "open_ai", "model": "gpt-4o-mini" },
      "prompt": "You are a helpful assistant."
    }
  }
}
```

--------------------------------

### FastAPI Application Server Configuration

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Core server configuration for the FastAPI application. Load environment variables and define server host and port.

```python
# app.py - Core server configuration
import os
from fastapi import FastAPI
from dotenv import load_dotenv

load_dotenv(override=False)

CONFIG = {
    "port": int(os.environ.get("PORT", 8081)),
    "host": os.environ.get("HOST", "0.0.0.0"),
}

# Run with uvicorn
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host=CONFIG["host"], port=CONFIG["port"])
```

--------------------------------

### Eject Frontend

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Ejects the frontend from the project for standalone development.

```bash
make eject-frontend
```

--------------------------------

### Clean Build Artifacts

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Removes all generated build artifacts and cleans the project.

```bash
make clean
```

--------------------------------

### Show Git Status

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Displays the current status of Git repositories and submodules.

```bash
make status
```

--------------------------------

### Manual Endpoint Checks

Source: https://github.com/deepgram-starters/fastapi-voice-agent/blob/main/AGENTS.md

Perform manual checks on the API endpoints using curl. The output is formatted using Python's json.tool for readability.

```bash
# Manual endpoint check
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
```

```bash
curl -sf http://localhost:8081/api/session | python3 -m json.tool
```

--------------------------------

### Request Session Token with cURL

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Use cURL to request a JWT session token for authenticating WebSocket connections. The token is valid for 1 hour and must be included in subsequent API requests.

```bash
# Request a new session token
curl -X GET http://localhost:8081/api/session

# Response:
# {"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDk4MjM0NTYsImV4cCI6MTcwOTgyNzA1Nn0.abc123..."}

# Use the token in subsequent requests
export SESSION_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
curl -X GET http://localhost:8081/api/metadata \
  -H "Authorization: Bearer $SESSION_TOKEN"
```

--------------------------------

### Live Agent Updates

Source: https://github.com/deepgram-starters/fastapi-voice-agent/blob/main/AGENTS.md

JSON messages used to update agent behavior without reconnecting the WebSocket.

```json
{ "type": "UpdateSpeak", "model": "aura-2-luna-en" }
```

```json
{ "type": "UpdatePrompt", "prompt": "New instructions..." }
```

```json
{ "type": "InjectUserMessage", "content": "text" }
```

--------------------------------

### Update Submodules

Source: https://context7.com/deepgram-starters/fastapi-voice-agent/llms.txt

Updates all Git submodules to their latest versions.

```bash
make update
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.