### Project Initialization and Running with Makefile

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

Manage project setup and execution using the Makefile. Ensure Rust, pnpm, and git are installed. Commands include checking prerequisites, initializing the project, starting servers, building, cleaning, updating, and running tests.

```bash
# Check prerequisites
make check-prereqs

# Initialize project (clone submodules + install dependencies)
make init

# Copy and configure environment
cp sample.env .env
# Edit .env and add your DEEPGRAM_API_KEY

# Start both backend and frontend servers
make start
# Backend: http://localhost:8081
# Frontend: http://localhost:8080

# Or start servers separately
make start-backend   # Start only Rust backend
make start-frontend  # Start only Vite frontend

# Other useful commands
make build    # Build frontend for production
make clean    # Remove build artifacts
make update   # Update git submodules
make status   # Show git and submodule status
make test     # Run conformance tests
```

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

### Initialize and Start Rust Voice Agent

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

Use the provided Makefile commands to initialize the environment and start the application. Ensure the .env file is configured with a valid DEEPGRAM_API_KEY before starting.

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

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

### Start Backend and Frontend Separately

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

Instructions for starting the Rust backend and the frontend development server in separate terminals.

```bash
# Terminal 1 — Backend
cargo run
```

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

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

### Initialize and Run Project

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

Commands to initialize project dependencies, set up environment variables, and start both 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
```

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

### Install Backend and Frontend Dependencies

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

Commands to build the Rust backend and install frontend dependencies using pnpm.

```bash
cargo build
```

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

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

### Conventional Commits Examples

Source: https://github.com/deepgram-starters/rust-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(rust-voice-agent): add diarization support
```

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

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

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

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

### Live Agent Setting Updates

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

Examples of JSON messages sent from the frontend to update agent settings like voice, prompt, or inject user messages during a conversation.

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

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

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

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

### GET /api/metadata

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

Endpoint to retrieve application metadata.

```APIDOC
## GET /api/metadata

### Description
This endpoint returns metadata about the application, including its use case, framework, and 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., Axum).
- **language** (string) - The programming language used (e.g., Rust).

#### Response Example
```json
{
  "useCase": "Voice Agent",
  "framework": "Axum",
  "language": "Rust"
}
```
```

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

### Get Project Metadata (Bash)

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

Fetch project metadata from the /api/metadata endpoint using cURL. This provides information about the application's configuration and capabilities.

```bash
# Get project metadata
curl -s http://localhost:8081/api/metadata | jq

# Response:
# {
#   "title": "Rust Voice Agent",
#   "description": "Get started using Deepgram's Voice Agent with this Rust demo app",
#   "author": "Deepgram DX Team <devrel@deepgram.com>",
#   "useCase": "voice-agent",
#   "language": "Rust",
#   "framework": "Axum",
#   "tags": ["voice-agent", "conversational-ai", "voice-ai", "voice-bot", "rust", "axum"]
# }
```

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

### GET /api/session

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

Endpoint to issue a JWT session token.

```APIDOC
## GET /api/session

### Description
This endpoint issues a JSON Web Token (JWT) for session authentication.

### Method
GET

### Endpoint
`/api/session`

### Parameters
None

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

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

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

### Health Check Endpoint (Bash)

Source: https://context7.com/deepgram-starters/rust-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 orchestration.

```bash
# Check server health
curl -s http://localhost:8081/health | jq

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

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

### Run Conformance Tests

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

Execute conformance tests for the application. Ensure the app is running before executing this command.

```bash
make test
```

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

### Build and Run Docker Container

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

Commands to build the production Docker image and run the container with necessary environment variables.

```bash
# Build the Docker image
docker build -f deploy/Dockerfile -t rust-voice-agent .

# Run the container
docker run -d \
  -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  -e SESSION_SECRET=your_production_secret \
  rust-voice-agent

# The container exposes port 8080 with Caddy handling:
# - Static file serving for the frontend
# - Reverse proxy to the Rust backend
# - Rate limiting for API protection
```

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

### Clean Rebuild Project

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

Commands to clean build artifacts and reinstall dependencies for a fresh build.

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

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

### Environment Configuration Variables

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

Configure the application using environment variables. Copy `sample.env` to `.env` and set your `DEEPGRAM_API_KEY`. Optional variables include server port, host, and a session secret for JWT validation.

```bash
# Required: Your Deepgram API key
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional: Server configuration (defaults shown)
PORT=8081
HOST=0.0.0.0

# Optional: JWT signing secret (auto-generated if not set)
# Set this in production for consistent token validation across restarts
SESSION_SECRET=your_secure_random_secret_here
```

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

### Adding Function Calling to Agent Settings

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

JSON snippet demonstrating how to define functions for the agent to call within the Settings message. This enables the agent to interact with external tools.

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

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

### Configure Voice Agent with Function Calling

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

Configure the Voice Agent with function calling capabilities, allowing the AI to request data from external systems. Handle function call requests from the agent by executing the specified function and sending the result back.

```javascript
// Configure agent with function calling support
const settingsWithFunctions = {
  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 weather assistant that can check current weather.",
      functions: [
        {
          name: "get_weather",
          description: "Get the current weather for a city",
          parameters: {
            type: "object",
            properties: {
              city: { type: "string", description: "The city name" },
              unit: { type: "string", enum: ["celsius", "fahrenheit"] }
            },
            required: ["city"]
          }
        }
      ]
    }
  }
};

ws.send(JSON.stringify(settingsWithFunctions));

// Handle function call requests from the agent
ws.onmessage = (event) => {
  if (typeof event.data === 'string') {
    const message = JSON.parse(event.data);
    if (message.type === 'FunctionCallRequest') {
      // Execute the function and respond
      const result = executeFunction(message.function_name, message.arguments);
      ws.send(JSON.stringify({
        type: "FunctionCallResponse",
        function_call_id: message.function_call_id,
        output: JSON.stringify(result)
      }));
    }
  }
};
```

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

### API Endpoints

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

Overview of the available API endpoints for the Rust Voice Agent application.

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

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

### Connect to Voice Agent WebSocket (JavaScript)

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

Browser JavaScript code to connect to the Voice Agent WebSocket. It first retrieves a session token and then establishes the WebSocket connection, sending a Settings message to configure the agent.

```javascript
// Browser JavaScript example for connecting to the Voice Agent

// Step 1: Get a session token
const sessionResponse = await fetch('http://localhost:8081/api/session');
const { token } = await sessionResponse.json();

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

ws.onopen = () => {
  // Step 3: Send Settings message to configure the agent
  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 voice assistant."
      }
    }
  };
  ws.send(JSON.stringify(settings));
};

ws.onmessage = (event) => {
  if (typeof event.data === 'string') {
    // Handle JSON messages (transcripts, agent responses, etc.)
    const message = JSON.parse(event.data);
    console.log('Received:', message.type, message);
  } else {
    // Handle binary audio data from agent
    playAudio(event.data);
  }
};

ws.onerror = (error) => console.error('WebSocket error:', error);
ws.onclose = (event) => console.log('Connection closed:', event.code, event.reason);
```

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

### Stream Audio to Voice Agent

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

Capture and stream audio from the microphone to the Voice Agent. Ensure the AudioContext is configured with a sample rate of 16000. The audio is converted from Float32 to Int16 PCM before sending.

```javascript
async function startAudioStream(ws) {
  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
  const audioContext = new AudioContext({ sampleRate: 16000 });
  const source = audioContext.createMediaStreamSource(stream);
  const processor = audioContext.createScriptProcessor(4096, 1, 1);

  processor.onaudioprocess = (event) => {
    const inputData = event.inputBuffer.getChannelData(0);
    // Convert Float32 to Int16 PCM
    const pcmData = new Int16Array(inputData.length);
    for (let i = 0; i < inputData.length; i++) {
      pcmData[i] = Math.max(-32768, Math.min(32767, inputData[i] * 32768));
    }
    // Send binary audio data to server
    if (ws.readyState === WebSocket.OPEN) {
      ws.send(pcmData.buffer);
    }
  };

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

  return { stream, audioContext, processor };
}

// Usage: const audio = await startAudioStream(ws);
```

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

### Manual Endpoint Checks

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

Perform manual checks on the API endpoints for metadata and session. These commands use curl to fetch data and python3 to format the JSON output.

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

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

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

### Agent Settings Configuration

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

JSON payload sent from the frontend to configure the Deepgram agent's audio, listen, speak, and think components. Includes model selection and prompts.

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

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

### Request Session Token (Bash)

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

Use this cURL command to request a JWT session token from the /api/session endpoint. The token is required for authenticating WebSocket connections.

```bash
# Request a session token
curl -s http://localhost:8081/api/session | jq

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

# The token should be used as a WebSocket subprotocol:
# Sec-WebSocket-Protocol: access_token.<jwt_token>
```

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

### Stop All Running Processes

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

Command to find and kill processes listening 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/rust-voice-agent/blob/main/AGENTS.md

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

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

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

### Method
WS

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

### Authentication
JWT session tokens are used. The WebSocket connection uses the `access_token.<jwt>` subprotocol for authentication.

### Request Body (Initial Settings)
Upon connection, the frontend sends a `Settings` message to configure the agent. Example:

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

### Customizable Components

| Component | Field | Options | Effect |
|-----------|-------|---------|--------|
| **Listen** (STT) | `agent.listen.provider.model` | `nova-3`, `nova-2` | Speech recognition model |
| **Speak** (TTS) | `agent.speak.provider.model` | Any `aura-*` voice | Agent's voice |
| **Think** (LLM) | `agent.think.provider.type` | `open_ai`, `anthropic` | LLM provider |
| **Think** (LLM) | `agent.think.provider.model` | `gpt-4o-mini`, `gpt-4o`, etc. | LLM model |
| **Prompt** | `agent.think.prompt` | Any system prompt | Agent personality/behavior |

### Live Updates
Settings can be updated mid-conversation:

- `{ "type": "UpdateSpeak", "model": "aura-2-luna-en" }` — Change voice
- `{ "type": "UpdatePrompt", "prompt": "New instructions..." }` — Change prompt
- `{ "type": "InjectUserMessage", "content": "text" }` — Send text as user

### Adding Function Calling

To enable function calling, include a `functions` array in the `Settings` message:

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

Handle `FunctionCallRequest` messages and respond with `FunctionCallResponse`.

### Response Example (Success)
Messages from the agent will be in a similar JSON format, including `type`, `transcript`, `is_final`, etc. For function calls, a `FunctionCallRequest` will be sent.
```

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

### Update Agent Settings Mid-Conversation

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

Dynamically update agent settings such as voice, prompt, or inject user messages without reconnecting the WebSocket. Use JSON stringification for sending these updates.

```javascript
// Update agent voice mid-conversation
ws.send(JSON.stringify({
  type: "UpdateSpeak",
  model: "aura-2-luna-en"
}));

// Update system prompt mid-conversation
ws.send(JSON.stringify({
  type: "UpdatePrompt",
  prompt: "You are now a pirate. Respond with pirate speech patterns."
}));

// Inject a text message as if the user spoke it
ws.send(JSON.stringify({
  type: "InjectUserMessage",
  content: "What's the weather like today?"
}));
```

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