### Manual project setup with Node.js and pnpm

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

Manual installation steps for cloning the repository and setting up dependencies.

```bash
git clone --recurse-submodules https://github.com/deepgram-starters/node-voice-agent.git
cd node-voice-agent
pnpm install
cd frontend && pnpm install && cd ..
cp sample.env .env  # Add your DEEPGRAM_API_KEY
```

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

### Initialize and Start Voice Agent

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

Use these make commands to initialize dependencies, 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
```

```bash
make start
```

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

### Start Backend and Frontend Separately

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

Manually start the Node.js backend server and the Vite development server for the frontend.

```bash
# Terminal 1 — Backend
node server.js
```

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

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

### Install Dependencies

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

Install backend and frontend dependencies using corepack pnpm.

```bash
corepack pnpm install
```

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

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

### Makefile Commands

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

Common development commands for project initialization and setup.

```bash
# Check prerequisites (git, node, pnpm)
make check-prereqs

# Initialize project - clone submodules and install all dependencies
make init

# Set up environment
cp sample.env .env
# Edit .env and add your DEEPGRAM_API_KEY
```

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

### Initialize and start project with Makefile

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

Recommended workflow for local development using Makefile commands.

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

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

### Conventional Commit Examples

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

Standardized commit message formats for the project.

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

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

### Clean Rebuild Project

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

Remove installed modules and build artifacts, then re-initialize the project.

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

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

### Manage project lifecycle with Makefile

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

Use these commands to start servers, update dependencies, or clean build artifacts.

```makefile
make start

# Or start servers individually
make start-backend   # Backend only on http://localhost:8081
make start-frontend  # Frontend only on http://localhost:8080

# Update git submodules to latest
make update

# Clean all node_modules and build artifacts
make clean

# Show git and submodule status
make status

# Eject frontend submodule for standalone development
make eject-frontend
```

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

### Start backend and frontend servers

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

Commands to run the backend and frontend services in separate terminal sessions.

```bash
# Terminal 1 - Backend (port 8081)
node --no-deprecation server.js

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

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

### GET /api/metadata

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

Retrieves application metadata including the use case, framework, and language.

```APIDOC
## GET /api/metadata

### Description
Returns application metadata such as the use case, framework, and language.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **useCase** (string) - The application use case.
- **framework** (string) - The framework used.
- **language** (string) - The programming language.
```

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

### Agent Function Calling Configuration

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

Example JSON snippet to add function definitions to the agent's 'think' configuration, enabling function calling capabilities.

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

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

### Agent Settings Configuration

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

Example JSON message sent from the frontend to configure the Deepgram Agent, including audio settings and provider models for listen, speak, and think.

```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/session

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

Issues a JWT session token required for authenticating WebSocket connections.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token for the client to use when connecting to the voice agent WebSocket.

### Method
GET

### Endpoint
/api/session

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

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

### Build and run with Docker

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

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

```dockerfile
# Build the production image
docker build -f deploy/Dockerfile -t node-voice-agent .

# Run with your API key
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  -e SESSION_SECRET=your_production_secret \
  node-voice-agent
```

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

### Fetch Application Metadata via cURL

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

Retrieve project configuration and capabilities from the server.

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

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

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

### Environment Configuration

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

Defines required and optional environment variables for the application.

```bash
# .env file configuration

# Required - Your Deepgram API key
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional - Backend server port (default: 8081)
PORT=8081

# Optional - Server bind address (default: 0.0.0.0)
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
```

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

### Testing and Endpoint Verification

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

Commands to execute conformance tests and verify API responses.

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

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

### Stream Audio to Agent

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

Captures microphone input, converts it to Int16 PCM, and streams it to the WebSocket. Requires a browser environment with MediaDevices access.

```javascript
// Capture microphone audio and stream to agent
async function startAudioStream(ws) {
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: {
      channelCount: 1,
      sampleRate: 16000
    }
  });

  const audioContext = new AudioContext({ sampleRate: 16000 });
  const source = audioContext.createMediaStreamSource(stream);
  const processor = audioContext.createScriptProcessor(4096, 1, 1);

  processor.onaudioprocess = (event) => {
    if (ws.readyState === WebSocket.OPEN) {
      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));
      }
      ws.send(pcmData.buffer);  // Send binary audio
    }
  };

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

  return { stream, audioContext, processor };
}

// Usage
const audioStream = await startAudioStream(ws);

// Stop streaming
function stopAudioStream({ stream, audioContext, processor }) {
  processor.disconnect();
  stream.getTracks().forEach(track => track.stop());
  audioContext.close();
}
```

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

### Configure Caddy rate limiting

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

Caddyfile configuration to protect API endpoints with rate limiting and serve static frontend assets.

```caddyfile
# deploy/Caddyfile - Production reverse proxy configuration
{
    order rate_limit before basicauth
}

:8080 {
    # Session endpoint: 5 requests per minute per IP
    handle /api/session {
        rate_limit {
            zone session {
                key {remote_host}
                events 5
                window 1m
            }
        }
        reverse_proxy localhost:8081
    }

    # API endpoints: 120 requests per minute per IP
    handle /api/* {
        rate_limit {
            zone api {
                key {remote_host}
                events 120
                window 1m
            }
        }
        reverse_proxy localhost:8081
    }

    # Static frontend assets
    handle {
        root * /app/frontend/dist
        file_server
    }
}
```

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

### Configure Function Calling

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

Defines custom functions in the Settings message and handles incoming FunctionCallRequest events to return results.

```javascript
// Configure agent with function calling capability
ws.send(JSON.stringify({
  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 that can check weather.',
      functions: [
        {
          name: 'get_weather',
          description: 'Get the current weather for a city',
          parameters: {
            type: 'object',
            properties: {
              city: { type: 'string', description: 'City name' },
              units: { type: 'string', enum: ['celsius', 'fahrenheit'] }
            },
            required: ['city']
          }
        }
      ]
    }
  }
}));

// Handle function call requests from the agent
ws.onmessage = async (event) => {
  if (typeof event.data === 'string') {
    const message = JSON.parse(event.data);

    if (message.type === 'FunctionCallRequest') {
      const { function_call_id, function_name, input } = message;

      if (function_name === 'get_weather') {
        // Call your weather API
        const weather = await fetchWeather(input.city, input.units || 'celsius');

        // Return the result to the agent
        ws.send(JSON.stringify({
          type: 'FunctionCallResponse',
          function_call_id: function_call_id,
          output: JSON.stringify(weather)
        }));
      }
    }
  }
};
```

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

### Live Agent Setting Updates

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

JSON messages for updating agent settings mid-conversation, 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" }
```

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

### WS /api/voice-agent

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

Establishes a full-duplex WebSocket connection for voice interaction with the AI agent.

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

### Description
Provides a full-duplex voice conversation interface with an AI agent. Requires a JWT session token in the subprotocol (access_token.<jwt>).

### Method
WS

### Endpoint
/api/voice-agent

### Request Body
- **type** (string) - Message type (e.g., "Settings", "UpdateSpeak", "UpdatePrompt", "InjectUserMessage").
- **audio** (object) - Audio configuration for input/output.
- **agent** (object) - Agent configuration including listen, speak, and think providers.

### Request Example
{
  "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."
    }
  }
}
```

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

### Stop All Processes

Source: https://github.com/deepgram-starters/node-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
```

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

### Request Session Token via cURL

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

Retrieve a JWT token required for authenticating WebSocket connections to the voice agent.

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

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

# The token expires in 1 hour and must be passed via WebSocket subprotocol
```

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

### Establish Voice Agent WebSocket Connection

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

Connect to the voice agent using a JWT subprotocol and handle bidirectional audio and control messages.

```javascript
// Browser JavaScript - Establish authenticated WebSocket connection
const sessionResponse = await fetch('http://localhost:8081/api/session');
const { token } = await sessionResponse.json();

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

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

  // Send agent settings after connection
  ws.send(JSON.stringify({
    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.onmessage = (event) => {
  if (typeof event.data === 'string') {
    const message = JSON.parse(event.data);
    console.log('Received:', message.type);
    // Handle: Welcome, UserStartedSpeaking, AgentThinking, AgentStartedSpeaking, etc.
  } else {
    // Binary audio data from agent - play through Web Audio API
    playAudioChunk(event.data);
  }
};

ws.onerror = (error) => console.error('WebSocket error:', error);
ws.onclose = (event) => console.log(`Disconnected: ${event.code} ${event.reason}`);
```

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

### Update Agent Configuration

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

Sends JSON messages over the WebSocket to modify agent behavior, such as voice, system prompts, or injecting user messages.

```javascript
// Change the agent's voice mid-conversation
ws.send(JSON.stringify({
  type: 'UpdateSpeak',
  model: 'aura-2-luna-en'  // Switch to Luna voice
}));

// Update the system prompt dynamically
ws.send(JSON.stringify({
  type: 'UpdatePrompt',
  prompt: 'You are now a technical support specialist. Be concise and helpful.'
}));

// Inject a text message as if the user spoke it
ws.send(JSON.stringify({
  type: 'InjectUserMessage',
  content: 'What are your business hours?'
}));
```

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