### Initialize and Start Servers

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

Use these make 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
```

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

### Start Backend and Frontend Separately

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

Instructions for starting the backend and frontend servers in separate terminals. Ensure the frontend is configured to run on port 8080.

```bash
# Terminal 1 — Backend
./build/app

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

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

### Install Backend and Frontend Dependencies

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

Commands to install C++ dependencies using CMake and vcpkg, and Node.js dependencies for the frontend using pnpm.

```bash
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" && cmake --build build
cd frontend && corepack pnpm install
```

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

### Initialize and Start C++ Voice Agent

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

Use this Makefile command to initialize the project, copy the sample environment file, and start the local development server. Ensure your DEEPGRAM_API_KEY is added to the .env file.

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

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

### Conventional Commits Examples

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

Examples of commit messages following the conventional commits format. Ensure all commits adhere to this standard for consistency.

```bash
feat(cpp-voice-agent): add diarization support
```

```bash
fix(cpp-voice-agent): resolve WebSocket close handling
```

```bash
refactor(cpp-voice-agent): simplify session endpoint
```

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

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

### Agent Function Calling Configuration

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

Example JSON snippet demonstrating how to configure function calling for the agent by defining available functions in the Settings message.

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

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

### Get Project Metadata

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

Retrieve project metadata, including title, description, author, and repository URL, by making a GET request to the /api/metadata endpoint. This data is parsed from the `deepgram.toml` configuration file.

```bash
# Get project metadata from deepgram.toml
curl -X GET http://localhost:8081/api/metadata
```

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

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

### Agent Settings Configuration

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

Example JSON payload sent from the frontend to configure agent settings, including audio input/output, STT, TTS, and LLM 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."
    }
  }
}
```

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

### GET /api/metadata

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

Endpoint to retrieve application metadata.

```APIDOC
## GET /api/metadata

### Description
Returns metadata about the application, including its use case, framework, and programming language.

### Method
GET

### Endpoint
`/api/metadata`

### Parameters
None

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

#### Response Example
```json
{
  "useCase": "Voice Agent",
  "framework": "Crow",
  "language": "C++"
}
```
```

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

### Connect to Voice Agent via WebSocket with Token

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

Example of how to use the obtained session token to establish a WebSocket connection to the voice agent. The token is passed as a subprotocol in the WebSocket connection.

```javascript
const response = await fetch('/api/session');
const { token } = await response.json();

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

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

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

### GET /api/session

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

Endpoint to issue a JWT session token.

```APIDOC
## GET /api/session

### Description
Issues a JSON Web Token (JWT) for session authentication. This token is used to authenticate WebSocket connections.

### Method
GET

### Endpoint
`/api/session`

### Parameters
None

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

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

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

### GET /api/metadata

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

Retrieves project metadata parsed from the deepgram.toml configuration file, including application details and tags.

```APIDOC
## GET /api/metadata

### Description
Returns project metadata parsed from the deepgram.toml configuration file, providing information about the application.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Project title
- **description** (string) - Project description
- **author** (string) - Author information
- **repository** (string) - Repository URL
- **useCase** (string) - Primary use case
- **language** (string) - Programming language
- **framework** (string) - Backend framework
- **tags** (array) - List of project tags

#### Response Example
{
  "title": "C++ Voice Agent Starter",
  "description": "Get started using Deepgram's Voice Agent with this C++ demo app",
  "author": "Deepgram DX Team <devrel@deepgram.com>",
  "repository": "https://github.com/deepgram-starters/cpp-voice-agent",
  "useCase": "voice-agent",
  "language": "C++",
  "framework": "Crow",
  "tags": ["voice-agent", "conversational-ai"]
}
```

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

### GET /health

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

Returns the server health status, used by monitoring systems and load balancers to verify service availability.

```APIDOC
## GET /health

### Description
Returns the server health status for monitoring and load balancer health checks.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The current health status of the server.

#### Response Example
{
  "status": "ok"
}
```

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

### Docker Health Check Configuration

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

Example of how to configure a Docker health check to periodically verify the server's health status by calling the /health endpoint. The check fails if the curl command returns a non-zero exit code.

```dockerfile
HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:8081/health || exit 1
```

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

### GET /api/session

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

Issues a signed JWT session token required for authenticating WebSocket connections to the voice agent. The token is valid for 1 hour.

```APIDOC
## GET /api/session

### Description
Issues a signed JWT session token for authenticating WebSocket connections. The token is valid for 1 hour and uses HMAC-SHA256 signing.

### Method
GET

### Endpoint
/api/session

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

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

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

### Check Server Health Status

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

Perform a health check on the server by sending a GET request to the /health endpoint. This is useful for monitoring and load balancer health checks, ensuring the service is ready to receive traffic.

```bash
# Check server health status
curl -X GET http://localhost:8081/health
```

```json
# Response:
# {"status":"ok"}
```

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

### Manage Development Lifecycle with Makefile

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

Commands for building, testing, and running the backend and frontend services.

```bash
# Check all prerequisites are installed
make check-prereqs
# Output: All prerequisites installed

# Initialize project (clone submodules, build backend, install frontend deps)
make init

# Build the C++ backend only
make install

# Build frontend for production
make build

# Start both backend (port 8081) and frontend (port 8080) servers
make start

# Start backend API server only
make start-backend

# Start frontend dev server only
make start-frontend

# Run contract conformance tests
make test

# Update git submodules to latest
make update

# Clean all build artifacts
make clean

# Show repository and submodule status
make status

# Eject frontend submodule to regular directory (irreversible)
make eject-frontend
```

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

### Build C++ Backend with CMake

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

Commands to configure and build the C++ backend, along with the dependency manifest.

```bash
# Configure with vcpkg toolchain
cmake -B build -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake

# Build release binary
cmake --build build --config Release

# Run the server
./build/cpp-voice-agent
```

```json
// vcpkg.json - Package dependencies
{
  "name": "cpp-voice-agent",
  "version-string": "1.0.0",
  "dependencies": [
    "crow",
    "boost-beast",
    "boost-asio",
    "nlohmann-json",
    "openssl"
  ]
}
```

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

### Run Conformance Tests

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

Execute the project's conformance tests. This command requires the application to be running.

```bash
make test
```

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

### Caddyfile Rate Limiting and Fly.io Deployment

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

Configuration for Caddy's rate limiting rules and a command to deploy the application to Fly.io.

```bash
# Caddyfile rate limits applied in production:
# - /api/session: 5 requests/minute per IP
# - /api/*: 120 requests/minute per IP
# - /health: No rate limit (for health checks)

# Deploy to Fly.io
fly deploy
```

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

### Configure Project Environment and Internal Settings

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

Defines environment variables for the server and the internal C++ configuration structure.

```bash
# sample.env - Copy to .env and configure
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional settings with defaults
PORT=8081
HOST=0.0.0.0

# Set in production for consistent token validation across restarts
SESSION_SECRET=your_64_char_hex_secret_here
```

```cpp
// AppConfig structure used internally
struct AppConfig {
    std::string deepgram_api_key;           // Required: Your Deepgram API key
    std::string deepgram_agent_host = "agent.deepgram.com";
    std::string deepgram_agent_path = "/v1/agent/converse";
    int         port                = 8081;
    std::string host                = "0.0.0.0";
    std::string session_secret;             // Auto-generated if not set
};
```

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

### Build and Run Docker Container

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

Builds a Docker image for the C++ Voice Agent and runs it as a container, exposing port 8080 and setting the Deepgram API key.

```docker
# Build and run production container
docker build -f deploy/Dockerfile -t cpp-voice-agent .
docker run -p 8080:8080 -e DEEPGRAM_API_KEY=your_key cpp-voice-agent
```

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

### Clean Rebuild Project

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

Remove build artifacts and reinstall dependencies for a clean rebuild of the project.

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

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

### CMake Configuration for C++ Voice Agent

Source: https://github.com/deepgram-starters/cpp-voice-agent/blob/main/CMakeLists.txt

This CMakeLists.txt file configures the build for the C++ voice agent. It specifies the C++ standard, finds necessary dependencies via vcpkg, and defines the executable target with its linked libraries.

```cmake
cmake_minimum_required(VERSION 3.20)
project(cpp-voice-agent LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# ---- Dependencies via vcpkg ----
find_package(Crow CONFIG REQUIRED)
find_package(Boost REQUIRED COMPONENTS system)
find_package(nlohmann_json CONFIG REQUIRED)
find_package(OpenSSL REQUIRED)

# ---- Build target ----
add_executable(cpp-voice-agent src/main.cpp)

target_link_libraries(cpp-voice-agent
    PRIVATE
        Crow::Crow
        Boost::system
        nlohmann_json::nlohmann_json
        OpenSSL::SSL
        OpenSSL::Crypto
)
```

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

### Connect to Voice Agent via WebSocket

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

Establishes a connection to the voice agent using a session token subprotocol and handles bidirectional audio/JSON streaming.

```javascript
// Complete WebSocket voice agent connection example

// Step 1: Get session token
const tokenResponse = await fetch('/api/session');
const { token } = await tokenResponse.json();

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

ws.binaryType = 'arraybuffer';

ws.onopen = () => {
  // Step 3: Send configuration to Deepgram
  ws.send(JSON.stringify({
    type: 'Settings',
    audio: {
      input: {
        encoding: 'linear16',
        sample_rate: 16000
      },
      output: {
        encoding: 'linear16',
        sample_rate: 24000,
        container: 'none'
      }
    },
    agent: {
      listen: { model: 'nova-2' },
      think: {
        provider: { type: 'open_ai' },
        model: 'gpt-4o-mini'
      },
      speak: { model: 'aura-asteria-en' }
    }
  }));
};

ws.onmessage = (event) => {
  if (event.data instanceof ArrayBuffer) {
    // Binary: audio data from Deepgram (play through speaker)
    const audioData = new Int16Array(event.data);
    playAudio(audioData);
  } else {
    // JSON: transcription, agent response, or status messages
    const message = JSON.parse(event.data);
    console.log('Received:', message.type, message);
  }
};

// Step 4: Send audio data (from microphone)
navigator.mediaDevices.getUserMedia({ audio: true })
  .then(stream => {
    const audioContext = new AudioContext({ sampleRate: 16000 });
    const source = audioContext.createMediaStreamSource(stream);
    const processor = audioContext.createScriptProcessor(4096, 1, 1);

    processor.onaudioprocess = (e) => {
      const float32Data = e.inputBuffer.getChannelData(0);
      const int16Data = new Int16Array(float32Data.length);
      for (let i = 0; i < float32Data.length; i++) {
        int16Data[i] = Math.max(-32768, Math.min(32767, float32Data[i] * 32768));
      }
      if (ws.readyState === WebSocket.OPEN) {
        ws.send(int16Data.buffer);
      }
    };

    source.connect(processor);
    processor.connect(audioContext.destination);
  });

ws.onclose = (event) => {
  console.log('Disconnected:', event.reason);
};
```

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

### API Endpoints

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

Overview of the available API endpoints for the C++ Voice Agent.

```APIDOC
## API Endpoints

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `/api/session` | GET | None | Issue JWT session token |
| `/api/metadata` | GET | None | Return app metadata (useCase, framework, language) |
| `/api/voice-agent` | WS | JWT | Full-duplex voice conversation with an AI agent. |
```

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

### Live Agent Setting Updates

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

JSON messages for updating agent settings mid-conversation without requiring a reconnect, such as changing the voice, prompt, or injecting user messages.

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

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

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

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

### Manual Endpoint Checks

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

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

```bash
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 for WebSocket Authentication

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

Use this cURL command to request a JWT session token. This token is required for authenticating WebSocket connections to the voice agent API. The token is valid for 1 hour and uses HMAC-SHA256 signing.

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

```json
# Response:
# {"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MDk4NTI0MDAsImlhdCI6MTcwOTg0ODgwMH0.signature"}
```

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

### Stop All Running Servers

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

Command to stop any processes running on ports 8080 and 8081.

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

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

### WebSocket API - /api/voice-agent

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

Details for the WebSocket endpoint used for full-duplex voice conversations with the AI agent.

```APIDOC
## WS /api/voice-agent

### Description
This endpoint facilitates a full-duplex voice conversation with an AI agent. It acts as a WebSocket proxy, forwarding messages between the browser and Deepgram's Agent API.

### Method
WS

### Endpoint
`/api/voice-agent`

### Parameters
#### Query Parameters
- **access_token** (string) - Required - JWT token for authentication. The subprotocol should be `access_token.<jwt>`.

### Request Body
Messages are sent as JSON objects. Key message types include:

#### Settings Message
Sent after connection to configure the agent.
```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."
    }
  }
}
```

#### UpdateSpeak Message
Updates the TTS voice mid-conversation.
```json
{
  "type": "UpdateSpeak",
  "model": "aura-2-luna-en"
}
```

#### UpdatePrompt Message
Updates the agent's system prompt mid-conversation.
```json
{
  "type": "UpdatePrompt",
  "prompt": "New instructions..."
}
```

#### InjectUserMessage Message
Injects a user message directly into the conversation flow.
```json
{
  "type": "InjectUserMessage",
  "content": "text"
}
```

#### Function Call Response
Responds to a `FunctionCallRequest`.
```json
{
  "type": "FunctionCallResponse",
  "response": { "data": "..." }
}
```

### Response
#### Success Response (1000)
- **type** (string) - Message type (e.g., `AgentSaid`, `FunctionCallRequest`, `ErrorResponse`).

#### AgentSaid Message Example
```json
{
  "type": "AgentSaid",
  "content": "Hello! How can I help you today?"
}
```

#### FunctionCallRequest Example
```json
{
  "type": "FunctionCallRequest",
  "call": {
    "name": "get_weather",
    "arguments": { "city": "New York" }
  }
}
```

#### ErrorResponse Example
```json
{
  "type": "ErrorResponse",
  "message": "An error occurred."
}
```
```

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