### Quick Start Initialization

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/configuration.md

Automated setup using the provided Makefile to clone, configure, and start the application.

```bash
# 1. Clone and initialize
make init

# 2. Copy sample environment file
cp sample.env .env

# 3. Edit .env and add your API key
# DEEPGRAM_API_KEY=your_api_key_here

# 4. Start servers
make start
```

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

### Install via Makefile

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Recommended installation method that automates dependency management and environment setup.

```bash
# Clone repository
git clone --recurse-submodules https://github.com/deepgram-starters/flask-voice-agent.git
cd flask-voice-agent

# Initialize (install all dependencies)
make init

# Copy environment template
cp sample.env .env

# Edit .env and add your API key
# DEEPGRAM_API_KEY=your_api_key_here
```

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

### Manual environment setup

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

Clone the repository and install dependencies manually using Python and pnpm.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/flask-voice-agent.git
cd flask-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
```

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

### Initialize and start via Makefile

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

Use the provided Makefile to initialize the environment and start the application.

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

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

### Install Manually

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Step-by-step installation for environments where Makefile automation is not preferred.

```bash
# Clone repository
git clone --recurse-submodules https://github.com/deepgram-starters/flask-voice-agent.git
cd flask-voice-agent

# Create and activate Python virtual environment
python3 -m venv venv
source venv/bin/activate
# On Windows: venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

# Initialize frontend submodule
git submodule update --init --recursive

# Install frontend dependencies
cd frontend
corepack pnpm install
cd ..

# Copy environment template
cp sample.env .env

# Edit .env and add your API key
# DEEPGRAM_API_KEY=your_api_key_here
```

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

### Start Frontend Development Server

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

Command to start the frontend development server using pnpm.

```bash
cd frontend && corepack pnpm run dev -- --port 8080 --no-open
```

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

### Start Flask Backend Separately

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

Command to start the Flask backend server independently.

```bash
./venv/bin/python app.py
```

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

### Initialize and Start Flask Voice Agent

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

Commands to initialize the project, set up environment variables, and start both the backend and frontend servers.

```bash
make init
test -f .env || cp sample.env .env  # then set DEEPGRAM_API_KEY
make start
```

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

### Install Backend and Frontend Dependencies

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

Commands to install backend Python dependencies using pip and frontend Node.js dependencies using pnpm.

```bash
python3 -m venv venv && ./venv/bin/pip install -r requirements.txt
cd frontend && corepack pnpm install
```

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

### Start Local Development

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

Initializes the backend on port 8081 and the frontend on port 8080.

```bash
make start
```

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

### Start Frontend Manually

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Starts the Vite frontend development server in a dedicated terminal.

```bash
cd frontend
corepack pnpm run dev -- --port 8080 --no-open
```

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

### Start Backend Manually

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Starts the Flask backend server in a dedicated terminal.

```bash
source venv/bin/activate
python app.py
```

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

### Build Frontend Assets

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Install dependencies and build the frontend if the root endpoint returns a 404.

```bash
cd frontend
corepack pnpm install
corepack pnpm run build
cd ..
curl http://localhost:8081/
```

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

### GET /

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/endpoints.md

Serves the built frontend index.html file.

```APIDOC
## GET /

### Description
Serves the built frontend `index.html` file.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **Content-Type** (text/html) - Serves `frontend/dist/index.html` if it exists.

#### Error Response (404)
- **Message** (string) - Returned if `frontend/dist/index.html` does not exist.

### Request Example
```bash
curl http://localhost:8081/
```
```

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

### Manual Environment Setup

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/configuration.md

Step-by-step commands to configure a Python virtual environment and launch the Flask server manually.

```bash
# 1. Create Python virtual environment
python3 -m venv venv
source venv/bin/activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Create .env file
cp sample.env .env
# Edit .env and add DEEPGRAM_API_KEY

# 4. Run Flask server
python app.py
```

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

### Run backend and frontend servers

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

Start 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
```

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

### Python WebSocket Client Implementation

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/endpoints.md

Example demonstrating session token retrieval, WebSocket connection, configuration, and binary audio streaming.

```python
import websocket
import requests
import json

# Step 1: Get JWT session token
session_response = requests.get('http://localhost:8081/api/session')
token = session_response.json()['token']

# Step 2: Open WebSocket with token in subprotocol
ws_url = 'ws://localhost:8081/api/voice-agent'
ws = websocket.create_connection(
    ws_url,
    header=[f'Sec-WebSocket-Protocol: access_token.{token}']
)

# Step 3: Send Settings message to configure agent
settings = {
    "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."
        }
    }
}
ws.send(json.dumps(settings))

# Step 4: Send audio (binary)
with open('audio.pcm', 'rb') as f:
    audio_data = f.read()
    ws.send_binary(audio_data)

# Step 5: Receive responses
while True:
    msg = ws.recv()
    print(f"Received: {msg}")

# Step 6: Close
ws.close()
```

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

### Connect and interact with voice_agent

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/api-reference.md

Example demonstrating how to authenticate, send settings, and stream audio to the voice_agent endpoint.

```python
import websocket
import requests
import json

# Get token
token = requests.get('http://localhost:8081/api/session').json()['token']

# Connect with token
ws = websocket.create_connection(
    'ws://localhost:8081/api/voice-agent',
    header=[f'Sec-WebSocket-Protocol: access_token.{token}']
)

# Send settings
settings = {
    "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."
        }
    }
}
ws.send(json.dumps(settings))

# Receive response
msg = ws.recv()
print(msg)

# Send audio
with open('audio.pcm', 'rb') as f:
    ws.send_binary(f.read())

# Cleanup
ws.close()
```

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

### Define Environment Variables in .env

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/configuration.md

Example configuration file for local development environment variables.

```bash
DEEPGRAM_API_KEY=my_api_key_here
PORT=8081
HOST=0.0.0.0
# SESSION_SECRET only needed in production
# SESSION_SECRET=my_secret_key_here
```

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

### Fetch Metadata in Python

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/endpoints.md

Example of using the requests library to retrieve and access application metadata.

```python
import requests

response = requests.get('http://localhost:8081/api/metadata')
metadata = response.json()
print(f"Framework: {metadata['framework']}")
```

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

### GET /api/metadata

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/INDEX.md

Retrieves application metadata.

```APIDOC
## GET /api/metadata

### Description
Returns application metadata.

### Method
GET

### Endpoint
/api/metadata
```

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

### Fetch Session Token in Python

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/endpoints.md

Example of using the requests library to retrieve a session token from the local API.

```python
import requests
import json

# Fetch session token
response = requests.get('http://localhost:8081/api/session')
token = response.json()['token']
print(f"Token: {token}")
```

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

### GET /api/metadata

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Retrieves metadata information about the Flask Voice Agent service.

```APIDOC
## GET /api/metadata

### Description
Returns configuration and service metadata for the Flask Voice Agent.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Service title
- **description** (string) - Service description
- **useCase** (string) - The use case identifier
- **language** (string) - Implementation language
- **framework** (string) - Web framework used

#### Response Example
{
  "title": "Flask Voice Agent",
  "description": "Flask WebSocket proxy for Deepgram's Voice Agent API",
  "useCase": "voice-agent",
  "language": "python",
  "framework": "flask"
}
```

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

### GET /api/metadata

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/types.md

Retrieves metadata information about the Flask Voice Agent application.

```APIDOC
## GET /api/metadata

### Description
Returns configuration and descriptive metadata about the running Flask Voice Agent application.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Application name
- **description** (string) - Short description of the application
- **author** (string) - Author contact and URL
- **repository** (string) - GitHub repository URL
- **useCase** (string) - Deepgram use case
- **language** (string) - Primary language
- **framework** (string) - Web framework
- **sdk** (string) - SDK information
- **tags** (array) - Array of searchable tag strings

#### Response Example
{
  "title": "Flask Voice Agent",
  "description": "Flask WebSocket proxy for Deepgram's Voice Agent API",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/flask-voice-agent",
  "useCase": "voice-agent",
  "language": "python",
  "framework": "flask",
  "sdk": "N/A",
  "tags": ["voice-agent", "conversational-ai", "voice-ai", "voice-bot", "python", "flask"]
}
```

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

### GET /api/metadata

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/endpoints.md

Returns application metadata from deepgram.toml.

```APIDOC
## GET /api/metadata

### Description
Returns application metadata from deepgram.toml.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Application name
- **description** (string) - Short description
- **author** (string) - Author contact information
- **repository** (string) - GitHub repository URL
- **useCase** (string) - Deepgram use case category (always "voice-agent")
- **language** (string) - Primary language (always "python")
- **framework** (string) - Web framework (always "flask")
- **sdk** (string) - SDK used (always "N/A")
- **tags** (array) - Searchable tags

#### Response Example
{
  "title": "Flask Voice Agent",
  "description": "Flask WebSocket proxy for Deepgram's Voice Agent API",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/flask-voice-agent",
  "useCase": "voice-agent",
  "language": "python",
  "framework": "flask",
  "sdk": "N/A",
  "tags": ["voice-agent", "conversational-ai", "voice-ai", "voice-bot", "python", "flask"]
}

#### Error Response (500)
- **error** (string) - Error code
- **message** (string) - Error description
```

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

### GET /api/session

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/endpoints.md

Issues a JWT token for WebSocket authentication.

```APIDOC
## GET /api/session

### Description
Issues a JWT token for WebSocket authentication.

### Method
GET

### Endpoint
/api/session

### Response
#### Success Response (200)
- **token** (string) - JWT token (HS256, valid for 3600 seconds). Base64url encoded.

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

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

### GET /api/metadata Response

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/endpoints.md

The expected JSON response structure containing application metadata.

```json
{
  "title": "Flask Voice Agent",
  "description": "Flask WebSocket proxy for Deepgram's Voice Agent API",
  "author": "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)",
  "repository": "https://github.com/deepgram-starters/flask-voice-agent",
  "useCase": "voice-agent",
  "language": "python",
  "framework": "flask",
  "sdk": "N/A",
  "tags": ["voice-agent", "conversational-ai", "voice-ai", "voice-bot", "python", "flask"]
}
```

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

### Commit Conventional Messages

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

Examples of commit messages following the conventional commits format.

```text
feat(flask-voice-agent): add diarization support
fix(flask-voice-agent): resolve WebSocket close handling
refactor(flask-voice-agent): simplify session endpoint
chore(deps): update frontend submodule
```

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

### Resolve Port Conflicts

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Identify and terminate processes occupying the required port, or start the application on an alternative port.

```bash
# Find process using port 8081
lsof -i :8081

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=8082 python app.py
```

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

### GET /api/metadata

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

Retrieves application metadata, including use case, framework, and language. This endpoint does not require authentication.

```APIDOC
## GET /api/metadata

### Description
Returns metadata about the voice agent application, such as its intended use case, the backend framework, and the programming language.

### Method
GET

### Endpoint
/api/metadata

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **useCase** (string) - The primary use case of the application.
- **framework** (string) - The backend framework used (e.g., Flask).
- **language** (string) - The programming language used (e.g., Python).

#### Response Example
```json
{
  "useCase": "Voice Agent",
  "framework": "Flask",
  "language": "Python"
}
```
```

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

### CONNECTION_FAILED Response

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/errors.md

Response returned for general failures during WebSocket proxy setup or message forwarding.

```json
{
  "type": "Error",
  "description": "Failed to establish proxy connection",
  "code": "CONNECTION_FAILED"
}
```

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

### Initialize Flask application

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/api-reference.md

Sets up the Flask application instance with CORS and WebSocket support.

```python
app = Flask(__name__)
CORS(app)
sock = Sock(app)
```

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

### Initialize Application CONFIG Dictionary

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/configuration.md

Structure of the internal configuration dictionary built at application startup.

```python
CONFIG = {
    'deepgram_api_key': str,           # From DEEPGRAM_API_KEY env var
    'deepgram_agent_url': str,         # Hardcoded: wss://agent.deepgram.com/v1/agent/converse
    'port': int,                        # From PORT env var (default 8081)
    'host': str,                        # From HOST env var (default 0.0.0.0)
}
```

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

### Deploy via Docker

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/INDEX.md

Builds the container image and executes the service with required environment variables.

```bash
# Build Docker image
docker build -t flask-voice-agent deploy/

# Run with environment variables
docker run \
  -e DEEPGRAM_API_KEY=... \
  -e SESSION_SECRET=... \
  -p 80:80 \
  flask-voice-agent
```

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

### GET /api/session

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Retrieves a session token required for authenticating WebSocket connections.

```APIDOC
## GET /api/session

### Description
Retrieves a session token used to authenticate the WebSocket connection to the voice agent.

### Method
GET

### Endpoint
/api/session

### Response
#### Success Response (200)
- **token** (string) - The JWT session token.

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

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

### Initialize Flask Application Configuration

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/architecture.md

The startup sequence for the Flask application, covering environment variable loading, configuration building, and server initialization.

```text
1. Load .env file (python-dotenv)
   ↓
2. Build CONFIG dict from environment
   {
     'deepgram_api_key': os.environ.get('DEEPGRAM_API_KEY'),
     'deepgram_agent_url': 'wss://agent.deepgram.com/v1/agent/converse',
     'port': int(os.environ.get('PORT', 8081)),
     'host': os.environ.get('HOST', '0.0.0.0'),
   }
   ↓
3. Validate CONFIG['deepgram_api_key']
   If missing: exit with error message
   ↓
4. Generate SESSION_SECRET (if not provided)
   SESSION_SECRET = os.environ.get("SESSION_SECRET") or secrets.token_hex(32)
   ↓
5. Create Flask app
   app = Flask(__name__)
   CORS(app)
   sock = Sock(app)
   ↓
6. Register route handlers
   ├─ GET /
   ├─ GET /api/session
   ├─ GET /api/metadata
   └─ WS /api/voice-agent
   ↓
7. Start Flask development server
   app.run(host=CONFIG['host'], port=CONFIG['port'], debug=debug)
```

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

### GET /api/session

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

Retrieves a JWT token required for authenticating WebSocket connections.

```APIDOC
## GET /api/session

### Description
Retrieves a JWT token with 1 hour validity for authenticating subsequent WebSocket connections.

### Method
GET

### Endpoint
/api/session

### Response
#### Success Response (200)
- **token** (string) - JWT token for authentication
```

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

### Initialize CONFIG dictionary

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/api-reference.md

Initializes the runtime configuration using environment variables with fallback defaults.

```python
CONFIG = {
    'deepgram_api_key': os.environ.get('DEEPGRAM_API_KEY'),
    'deepgram_agent_url': 'wss://agent.deepgram.com/v1/agent/converse',
    'port': int(os.environ.get('PORT', 8081)),
    'host': os.environ.get('HOST', '0.0.0.0'),
}
```

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

### Deploy Agent with Docker

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Build and run the agent container using the provided Docker configuration.

```bash
# Build Docker image
docker build -t flask-voice-agent deploy/

# Run container
docker run -e DEEPGRAM_API_KEY=your_key -p 80:80 flask-voice-agent
```

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

### GET /api/session

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/INDEX.md

Retrieves a session token required for authenticating WebSocket connections to the voice agent.

```APIDOC
## GET /api/session

### Description
Fetches an access token used to authenticate the WebSocket connection.

### Method
GET

### Endpoint
/api/session

### Response
#### Success Response (200)
- **token** (string) - The access token required for the WebSocket handshake.
```

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

### GET /api/session

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/INDEX.md

Retrieves a short-lived JWT session token required for authenticating WebSocket connections.

```APIDOC
## GET /api/session

### Description
Issues a short-lived (1h) JWT token used for WebSocket authentication.

### Method
GET

### Endpoint
/api/session
```

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

### Send Settings and Audio Frames

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/INDEX.md

Initializes the agent with a JSON settings payload followed by binary audio frames.

```json
# First message (JSON)
{
  "type": "Settings",
  "audio": {"input": {"encoding": "linear16", "sample_rate": 16000}, ...},
  "agent": {"listen": {...}, "speak": {...}, "think": {...}}
}

# Then messages (binary PCM or more JSON)
[binary audio frame 1]
[binary audio frame 2]
```

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

### Configuration Hierarchy

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/INDEX.md

Visualizes the flow of configuration from environment variables to runtime application behavior.

```text
Environment (system)
    ↓
.env file
    ↓
CONFIG dict (in app.py)
    ↓
Flask app configuration
    ↓
Runtime behavior
```

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

### GET /api/session Response

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/endpoints.md

The expected JSON response structure when successfully requesting a session token.

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

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

### Fix 404 Not Found Error

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/errors.md

Commands to build the frontend when the index.html file is missing.

```bash
cd frontend
corepack pnpm install
corepack pnpm run build
cd ..
```

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

### GET /api/session

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

Issues a JSON Web Token (JWT) session token. This endpoint does not require authentication.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token for authenticating WebSocket connections.

### Method
GET

### Endpoint
/api/session

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **token** (string) - The issued JWT session token.

#### Response Example
```json
{
  "token": "<your_jwt_token>"
}
```
```

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

### Handle Welcome Message Response

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/deepgram-integration.md

The server returns a WelcomeMessage upon successful initialization; the request_id should be stored for debugging purposes.

```json
{
  "type": "WelcomeMessage",
  "request_id": "uuid-1234..."
}
```

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

### Agent Function Calling Configuration

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

JSON snippet demonstrating how to define functions for the agent to call, including their names, descriptions, and parameters.

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

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

### Server Welcome Message

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/endpoints.md

Initial response from the server upon successful connection.

```json
{
  "type": "WelcomeMessage",
  "request_id": "abc-123"
}
```

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

### Monkey-patch WebSocket subprotocol selection

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/api-reference.md

Overrides the default subprotocol selection to support JWT-bearing subprotocols starting with 'access_token.'.

```python
def _choose_subprotocol_with_token(self, ws_request):
    for proto in ws_request.subprotocols:
        if proto.startswith("access_token."):
            return proto
    return _original_choose_subprotocol(self, ws_request)
```

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

### Settings

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/deepgram-integration.md

Configures the agent session immediately after the WebSocket connection is established.

```APIDOC
## Settings

### Description
Sent once after WebSocket connects to configure the agent.

### Parameters
- **type** (string) - Required - Must be "Settings"
- **audio.input.encoding** (string) - Required - Audio codec (e.g., "linear16")
- **audio.input.sample_rate** (integer) - Required - STT sample rate (8000 or 16000)
- **audio.output.encoding** (string) - Required - Audio codec (e.g., "linear16")
- **audio.output.sample_rate** (integer) - Required - TTS sample rate (8000 or 16000)
- **agent.listen.provider.type** (string) - Required - STT provider (e.g., "deepgram")
- **agent.listen.provider.model** (string) - Required - STT model
- **agent.speak.provider.type** (string) - Required - TTS provider
- **agent.speak.provider.model** (string) - Required - TTS voice model
- **agent.think.provider.type** (string) - Required - LLM provider
- **agent.think.provider.model** (string) - Required - LLM model
- **agent.think.prompt** (string) - Required - System prompt
- **agent.think.functions** (array) - Optional - Function definitions
```

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

### GET /api/session

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/types.md

Retrieves a JWT session token required for establishing a WebSocket connection to the Deepgram Voice Agent.

```APIDOC
## GET /api/session

### Description
Retrieves a JWT session token used to authenticate the WebSocket connection via the `Sec-WebSocket-Protocol` header.

### Method
GET

### Endpoint
/api/session

### Response
#### Success Response (200)
- **token** (string) - JWT token (HS256)

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

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

### Initialize WebSocket Support

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/configuration.md

Enables native WebSocket support using the flask-sock library.

```python
sock = Sock(app)
```

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

### Project File Structure

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Visual representation of the project directory layout and key components.

```text
app.py                      # Main Flask app (317 lines)
├─ CONFIG                   # Configuration dict
├─ SESSION_SECRET           # JWT signing key
├─ validate_ws_token()      # JWT validation
├─ serve_index()            # GET /
├─ get_session()            # GET /api/session
├─ metadata()               # GET /api/metadata
└─ voice_agent(ws)          # WS /api/voice-agent (main handler)

requirements.txt            # Python packages
deepgram.toml              # Project metadata
sample.env                 # Environment template
frontend/                  # Git submodule
├─ main.js                # Frontend logic
├─ index.html             # UI
└─ package.json           # NPM config
deploy/                    # Production files
├─ Dockerfile             # Container
└─ Caddyfile              # Reverse proxy
```

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

### GET /api/metadata

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/errors.md

Retrieves metadata from the deepgram.toml file. Returns a 500 error if the file is missing, inaccessible, or malformed.

```APIDOC
## GET /api/metadata

### Description
Retrieves metadata from the deepgram.toml file. If the file cannot be read, is malformed, or lacks the [meta] section, a 500 error is returned.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Error Response (500)
- **error** (string) - INTERNAL_SERVER_ERROR
- **message** (string) - Failed to read metadata from deepgram.toml
```

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

### GET /api/metadata Error Response

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/endpoints.md

The JSON structure returned when an internal server error occurs while reading metadata.

```json
{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "Failed to read metadata from deepgram.toml"
}
```

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

### Build and Run Docker Container

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

Builds the production image and runs it with the required Deepgram API key, exposing the service on port 80.

```bash
docker build -t flask-voice-agent deploy/
docker run -e DEEPGRAM_API_KEY=... -p 80:80 flask-voice-agent
```

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

### Connect WebSocket in Python

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Establishes a WebSocket connection, sends agent settings, and injects a text message using the websocket-client library.

```python
import websocket
import requests
import json
import time

# 1. Get token
session_response = requests.get('http://localhost:8081/api/session')
token = session_response.json()['token']
print(f"Token: {token}")

# 2. Connect WebSocket
ws = websocket.create_connection(
    'ws://localhost:8081/api/voice-agent',
    header=[f'Sec-WebSocket-Protocol: access_token.{token}']
)
print("Connected!")

# 3. Send settings
settings = {
    "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."
        }
    }
}
ws.send(json.dumps(settings))

# 4. Receive welcome message
welcome = ws.recv()
print(f"Welcome: {welcome}")

# 5. Send text message
text_msg = {
    "type": "InjectUserMessage",
    "content": "What is the capital of France?"
}
ws.send(json.dumps(text_msg))

# 6. Receive response
response = ws.recv()
print(f"Response: {response}")

# 7. Close connection
ws.close()
```

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

### Run Project Tests and Endpoint Checks

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

Commands to execute conformance tests and verify API endpoints using curl.

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

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

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

### Application File Structure

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/INDEX.md

Maps the source code organization within the project directory.

```text
app.py                          # Main application (317 lines)
├─ Lines 1-46: Imports & monkey-patch
├─ Lines 47-73: Environment & CONFIG validation
├─ Lines 79-95: JWT validation function
├─ Lines 101-108: Flask app setup
├─ Lines 114-120: GET / (serve_index)
├─ Lines 123-131: GET /api/session (get_session)
├─ Lines 138-157: GET /api/metadata (metadata)
├─ Lines 164-288: WS /api/voice-agent (voice_agent)
└─ Lines 294-316: Server startup

requirements.txt                # Python dependencies
deepgram.toml                  # Project metadata & build config
sample.env                     # Environment template
frontend/                      # Git submodule (not included)
deploy/                        # Production files
```

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

### Configure Default Application Settings

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/configuration.md

Defines environment variables and the resolved configuration dictionary for the application.

```python
# From .env or environment
DEEPGRAM_API_KEY = "your_api_key"
PORT = 8081
HOST = "0.0.0.0"
SESSION_SECRET = "a1b2c3d4..." # Generated if not provided

# Hardcoded
DEEPGRAM_AGENT_URL = "wss://agent.deepgram.com/v1/agent/converse"
JWT_EXPIRY = 3600

# Resolved CONFIG dict
CONFIG = {
    'deepgram_api_key': 'your_api_key',
    'deepgram_agent_url': 'wss://agent.deepgram.com/v1/agent/converse',
    'port': 8081,
    'host': '0.0.0.0',
}
```

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

### Configure API Key Environment Variable

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/errors.md

Commands to set the required API key in the environment or .env file.

```bash
export DEEPGRAM_API_KEY=your_api_key_here
# OR
echo "DEEPGRAM_API_KEY=your_api_key_here" > .env
python app.py
```

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

### Handle Deepgram Error Responses

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/deepgram-integration.md

Example of the JSON error structure returned by Deepgram and the corresponding JavaScript logic to handle these errors on the client side.

```json
{
  "type": "Error",
  "code": "INVALID_SETTINGS",
  "message": "Unknown model: gpt-5"
}
```

```javascript
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'Error') {
    console.error(`${msg.code}: ${msg.message}`);
  }
};
```

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

### Caddyfile Configuration Structure

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/architecture.md

Visual representation of the Caddyfile reverse proxy configuration for production deployment.

```text
Caddyfile:
├─ Reverse proxy (port 80/443)
├─ Rate limiting (per IP)
├─ Static file serving (frontend dist/)
└─ Backend proxy (localhost:8081)
```

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

### Clean Rebuild Project

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

Command to perform a clean rebuild by removing virtual environment, node modules, and Vite cache, then re-initializing.

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

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

### Production Deployment Configuration

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/configuration.md

Environment variables required for production, including a secure session secret generation.

```bash
export DEEPGRAM_API_KEY=your_api_key
export SESSION_SECRET=$(python3 -c "import secrets; print(secrets.token_hex(32))")
export FLASK_DEBUG=0
python app.py
```

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

### Connect WebSocket in JavaScript

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Establishes a browser-based WebSocket connection, handles incoming messages, and sends configuration and text messages.

```javascript
async function startConversation() {
  // 1. Get token
  const sessionResponse = await fetch('/api/session');
  const { token } = await sessionResponse.json();
  console.log(`Token: ${token}`);

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

  ws.onopen = () => {
    console.log('Connected!');

    // 3. Send settings
    const settings = {
      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."
        }
      }
    };
    ws.send(JSON.stringify(settings));
  };

  ws.onmessage = (event) => {
    try {
      const msg = JSON.parse(event.data);
      if (msg.type === 'Error') {
        console.error(`${msg.code}: ${msg.description}`);
      } else {
        console.log(`Message: ${JSON.stringify(msg)}`);
      }
    } catch (e) {
      // Binary audio data
      console.log(`Audio received: ${event.data.byteLength} bytes`);
    }
  };

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

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

  // 4. Send text message after a short delay
  setTimeout(() => {
    const textMsg = {
      type: "InjectUserMessage",
      content: "What is the capital of France?"
    };
    ws.send(JSON.stringify(textMsg));
  }, 1000);
}

// Start when ready
startConversation();
```

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

### Environment Configuration Variables

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

Required and optional environment variables for server operation and API authentication.

```text
Environment variables:
  DEEPGRAM_API_KEY     (required) — API authentication
  PORT                 (default 8081) — Server port
  HOST                 (default 0.0.0.0) — Bind address
  SESSION_SECRET       (auto-generated) — JWT signing key
```

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

### Fetch Metadata via cURL

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Retrieves configuration and service metadata for the voice agent.

```bash
curl http://localhost:8081/api/metadata | jq
```

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

### UpdatePrompt Configuration

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/deepgram-integration.md

Modifies the system prompt for the LLM mid-conversation.

```json
{
  "type": "UpdatePrompt",
  "prompt": "You are a sarcastic assistant who gives short answers."
}
```

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

### Configure Agent Function Calling

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/deepgram-integration.md

Define available functions within the agent settings to enable tool use capabilities.

```json
{
  "agent": {
    "think": {
      "functions": [
        {
          "name": "get_weather",
          "description": "Get current weather for a city",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string", "description": "City name" },
              "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
            },
            "required": ["city"]
          }
        },
        {
          "name": "set_timer",
          "description": "Set a timer for N seconds",
          "parameters": {
            "type": "object",
            "properties": {
              "seconds": { "type": "integer" }
            },
            "required": ["seconds"]
          }
        }
      ]
    }
  }
}
```

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

### Fetch Session Token and Connect via WebSocket

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/INDEX.md

Retrieves an authentication token via curl and establishes a WebSocket connection using the Sec-WebSocket-Protocol header.

```bash
# Fetch token
TOKEN=$(curl -s http://localhost:8081/api/session | jq -r .token)

# Use in WebSocket URL
ws://localhost:8081/api/voice-agent
Header: Sec-WebSocket-Protocol: access_token.${TOKEN}
```

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

### Configure Agent Function Calling

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Define available functions in the frontend settings message to enable agent tool usage.

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

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

### WelcomeMessage Response

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/deepgram-integration.md

Sent by Deepgram to confirm successful configuration after receiving the initial Settings message.

```json
{
  "type": "WelcomeMessage",
  "request_id": "abc-def-123"
}
```

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

### Agent Settings Configuration

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

JSON configuration object sent from the frontend to the backend to set up agent parameters for listening, speaking, and thinking.

```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."
    }
  }
}
```

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

### Fetch Root Endpoint via cURL

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/endpoints.md

Use this command to verify the root endpoint is serving the frontend application.

```bash
curl http://localhost:8081/
```

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

### Enable Verbose Logging in Flask

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/deepgram-integration.md

Configure Python logging to capture connection events during the voice agent lifecycle.

```python
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

# In voice_agent():
logger.debug(f"Creating Deepgram connection...")
deepgram_ws = websocket.create_connection(...)
logger.debug(f"Deepgram connection established: {deepgram_ws}")
```

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

### Authentication Flow Sequence

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

The step-by-step process for establishing a secure WebSocket connection using JWT tokens.

```text
1. GET /api/session → JWT token (1 hour validity)
2. WebSocket with Sec-WebSocket-Protocol: access_token.<token>
3. Server validates JWT and connects to Deepgram
4. Bidirectional message forwarding
```

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

### Define Settings Message Schema

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/types.md

JSON object sent from the client to configure audio settings and agent providers.

```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."
    }
  }
}
```

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

### Diagnose WebSocket Connectivity

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Commands to verify backend availability and port usage when WebSocket connections are refused.

```bash
curl http://localhost:8081/api/metadata
```

```bash
lsof -i :8081
```

```bash
python app.py
```

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

### Implement client to Deepgram main thread

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/api-reference.md

Logic for receiving messages from the client and forwarding them to Deepgram.

```python
while not stop_event.is_set():
    try:
        data = ws.receive(timeout=1.0)
        if data is None:
            if stop_event.is_set():
                break
            continue
        if isinstance(data, bytes):
            deepgram_ws.send_binary(data)
        else:
            deepgram_ws.send(data)
    except Exception as e:
        if not stop_event.is_set():
            print(f'Error in client receive loop: {e}')
        break
```

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

### Customize Agent System Prompt

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Define the agent's persona and behavioral guidelines within the UI system prompt field.

```text
You are a helpful customer support representative.
Your name is Alex.
Be concise and friendly.
Ask clarifying questions if needed.
```

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

### Handle Missing API Key Error

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/configuration.md

Console output displayed when the required DEEPGRAM_API_KEY is missing.

```text
======================================================================
ERROR: Deepgram API key not found!
======================================================================

Please set your API key using one of these methods:

1. Create a .env file (recommended):
   DEEPGRAM_API_KEY=your_api_key_here

2. Environment variable:
   export DEEPGRAM_API_KEY=your_api_key_here

Get your API key at: https://console.deepgram.com
======================================================================
```

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

### Initialize SESSION_SECRET

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/api-reference.md

Generates a session secret from environment variables or a random hex string for JWT signing.

```python
SESSION_SECRET = os.environ.get("SESSION_SECRET") or secrets.token_hex(32)
```

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

### Monitor Production Logs

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Filter application logs for error patterns to troubleshoot connection or provider issues.

```bash
# Terminal
tail -f app.log | grep -i error
```

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

### Configure LLM Provider

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Specify an alternative LLM provider and model in the agent settings message.

```json
{
  "agent": {
    "think": {
      "provider": {
        "type": "anthropic",
        "model": "claude-opus"
      }
    }
  }
}
```

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

### WelcomeMessage

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/types.md

A JSON object sent from Deepgram to the client upon successful connection.

```APIDOC
## WelcomeMessage

### Description
Indicates a successful connection to the Deepgram Agent API.

### Response
- **type** (string) - Message type: "WelcomeMessage"
- **request_id** (string) - Unique request identifier for logging and support
```

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

### Define Application Metadata

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/configuration.md

Stores application details in a TOML file for retrieval via the /api/metadata endpoint.

```toml
[meta]
title = "Flask Voice Agent"
description = "Flask WebSocket proxy for Deepgram's Voice Agent API"
author = "Deepgram DX Team <devrel@deepgram.com> (https://developers.deepgram.com)"
repository = "https://github.com/deepgram-starters/flask-voice-agent"
useCase = "voice-agent"
language = "python"
framework = "flask"
sdk = "N/A"
tags = ["voice-agent", "conversational-ai", "voice-ai", "voice-bot", "python", "flask"]
```

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

### WebSocket Upgrade Header

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/errors.md

Required format for the Sec-WebSocket-Protocol header when connecting to the voice agent.

```text
Sec-WebSocket-Protocol: access_token.<fresh_token>
```

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

### Retrieve Application Metadata

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/api-reference.md

Fetches application metadata from the /api/metadata endpoint.

```python
import requests

response = requests.get('http://localhost:8081/api/metadata')
if response.status_code == 200:
    metadata = response.json()
    print(f"Framework: {metadata['framework']}")
```

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

### Verify API Key Configuration

Source: https://github.com/deepgram-starters/flask-voice-agent/blob/main/_autodocs/quickstart.md

Set the Deepgram API key via environment variable if the server fails to locate it.

```bash
export DEEPGRAM_API_KEY=your_api_key
```