### Initialize and Start Deno Voice Agent

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

Use these commands to initialize submodules, install dependencies, set up environment variables, and start both the backend and frontend servers.

```bash
make init
test -f .env || cp sample.env .env
make start
```

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

### Initialize Project and Start Server with Makefile

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

Use the Makefile for a streamlined local development setup. 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
```

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

### Initialize and Start Development Server

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

Provides commands for initializing the project, setting up environment variables, and starting the backend and frontend development servers. Supports both Makefile and direct Deno/pnpm commands.

```bash
# Using Makefile (recommended)
make init                    # Initialize submodules and install dependencies
cp sample.env .env           # Create .env file
# Edit .env and add your DEEPGRAM_API_KEY
make start                   # Start both backend and frontend servers

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

```bash
# Using Deno directly
git clone --recurse-submodules https://github.com/deepgram-starters/deno-voice-agent.git
cd deno-voice-agent
deno task cache              # Cache Deno dependencies
cd frontend && corepack pnpm install && cd ..

# Terminal 1 - Start backend with file watching
deno run --allow-net --allow-read --allow-env --watch server.ts

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

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

### Install Frontend Dependencies

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

Install frontend dependencies using pnpm after cloning the repository.

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

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

### Start Deno Voice Agent Separately

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

Start the backend and frontend servers in separate terminals. Ensure the frontend is configured to run on port 8080 and disable auto-opening.

```bash
# Terminal 1 — Backend
deno task start

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

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

### Start Backend and Frontend Servers with Deno

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

Run the backend server using Deno, allowing network, read, and environment access. Simultaneously, start the frontend development server using pnpm, specifying the port and disabling auto-opening.

```bash
# Terminal 1 - Backend (port 8081)
denо run --allow-net --allow-read --allow-env server.ts

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

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

### GET /api/metadata

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

Retrieves metadata about the starter application, including title, description, and repository information.

```APIDOC
## GET /api/metadata

### Description
Returns metadata about the starter application from the deepgram.toml configuration file.

### Method
GET

### Endpoint
/api/metadata

### Response
#### Success Response (200)
- **title** (string) - Application title
- **description** (string) - Application description
- **author** (string) - Author information
- **repository** (string) - GitHub repository URL
- **useCase** (string) - Primary use case
- **language** (string) - Programming language
- **framework** (string) - Framework used
- **tags** (array) - List of relevant tags

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

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

### Clone Repository and Install Dependencies with Deno and pnpm

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

Clone the repository, install frontend dependencies using pnpm, and configure your Deepgram API key. This method is an alternative to using the Makefile.

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

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

### Conventional Commit Examples

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

Standardized commit message formats for the project.

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

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

### GET /api/voice-agent

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

Establishes a WebSocket connection to the voice agent. Configuration options are passed via query parameters to customize the speech recognition and synthesis behavior.

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

### Description
Establishes a WebSocket connection to the voice agent. Configuration options are passed via query parameters to customize the speech recognition and synthesis behavior.

### Method
GET

### Endpoint
/api/voice-agent

### Parameters
#### Query Parameters
- **model** (string) - Optional - The Deepgram model to use (default: 'nova-2')
- **language** (string) - Optional - The language code (default: 'en-US')
- **punctuate** (string) - Optional - Enable punctuation
- **interim_results** (string) - Optional - Enable interim results
- **endpointing** (string) - Optional - Endpointing duration in milliseconds (default: '300')

### Request Example
ws://localhost:8081/api/voice-agent?model=nova-2&language=en-US
```

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

### Request Application Metadata

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

Retrieves metadata about the starter application, such as its title, description, author, and tags, from the deepgram.toml configuration file using a GET request to the /api/metadata endpoint.

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

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

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

### GET /api/session

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

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

```APIDOC
## GET /api/session

### Description
Issues a signed JWT session token for authenticating WebSocket connections. Tokens expire after 1 hour.

### Method
GET

### Endpoint
/api/session

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

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

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

### Docker Deployment Commands

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

Provides Docker commands for building the application image and running the container, including environment variable configuration for API keys and secrets. Also includes steps for deploying to Fly.io.

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

# Run the container
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  -e SESSION_SECRET=your_secret \
  deno-voice-agent

# Deploy to Fly.io
fly launch                   # Initial setup
fly secrets set DEEPGRAM_API_KEY=your_api_key
fly secrets set SESSION_SECRET=your_secret
fly deploy
```

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

### Testing Commands

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

Commands for running conformance tests and verifying API endpoints.

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

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

### Environment Configuration

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

Configure the application using environment variables in a .env file. Ensure DEEPGRAM_API_KEY is set.

```bash
# Required - Your Deepgram API key from https://console.deepgram.com
DEEPGRAM_API_KEY=your_api_key_here

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

# Optional - Server host binding (default: 0.0.0.0)
HOST=0.0.0.0

# Optional - Session secret for JWT signing (auto-generated if not set)
SESSION_SECRET=your_64_character_hex_secret
```

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

### Agent Settings Configuration

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

This JSON object configures the agent's audio input/output, STT, TTS, and LLM models. It is sent from the frontend after connecting.

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

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

### Agent Function Calling Configuration

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

Add a `functions` array to the Settings message to enable function calling. Define function names, descriptions, and parameters.

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

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

### Clean Rebuild Deno Voice Agent

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

Remove frontend build artifacts and reinstall dependencies for a clean rebuild.

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

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

### Server Configuration and Types

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

Defines the TypeScript interfaces for server configuration, error messages, and constants used in the Deno server, including port, host, JWT expiry, and Deepgram agent URL.

```typescript
// Server configuration interface
interface ServerConfig {
  port: number;   // Default: 8081 or PORT env var
  host: string;   // Default: "0.0.0.0" or HOST env var
}

// Error message structure sent to clients
interface ErrorMessage {
  type: "Error";
  description: string;
  code: string;  // e.g., "UNKNOWN_ERROR", "DEEPGRAM_ERROR", "CONNECTION_FAILED"
}

// JWT Configuration
const JWT_EXPIRY = "1h";  // Session tokens expire after 1 hour

// Deepgram Voice Agent endpoint
const DEEPGRAM_AGENT_URL = "wss://agent.deepgram.com/v1/agent/converse";
```

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

### API Endpoints

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

Overview of the available API endpoints for the Deno Voice Agent.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token.

### Method
GET

### Endpoint
/api/session

### Parameters
#### Query Parameters
None

#### Request Body
None

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

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

```APIDOC
## GET /api/metadata

### Description
Returns application metadata, including useCase, framework, and language.

### Method
GET

### Endpoint
/api/metadata

### Parameters
#### Query Parameters
None

#### Request Body
None

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

#### Response Example
```json
{
  "useCase": "voice-agent",
  "framework": "deno",
  "language": "typescript"
}
```
```

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

### Description
Establishes a full-duplex WebSocket connection for voice conversations with an AI agent. Authentication is handled via JWT session tokens using the `access_token.<jwt>` subprotocol.

### Method
WS

### Endpoint
/api/voice-agent

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (Communication is message-based over WebSocket)

### Authentication
JWT session tokens via `access_token.<jwt>` subprotocol.

### Message Types
#### Settings (sent from frontend after connection)
```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 (sent from frontend mid-conversation)
```json
{
  "type": "UpdateSpeak",
  "model": "aura-2-luna-en"
}
```

#### UpdatePrompt (sent from frontend mid-conversation)
```json
{
  "type": "UpdatePrompt",
  "prompt": "New instructions..."
}
```

#### InjectUserMessage (sent from frontend mid-conversation)
```json
{
  "type": "InjectUserMessage",
  "content": "text"
}
```

#### FunctionCallRequest (received from Deepgram Agent API)
```json
{
  "type": "FunctionCallRequest",
  "call": {
    "name": "get_weather",
    "arguments": {
      "city": "New York"
    }
  }
}
```

#### FunctionCallResponse (sent from frontend in response to FunctionCallRequest)
```json
{
  "type": "FunctionCallResponse",
  "response": {
    "city": "New York",
    "weather": "sunny"
  }
}
```

### Response
#### Success Response (200 OK - WebSocket connection established)
Messages are exchanged in a full-duplex manner.

#### Response Example (Example of a message from the agent)
```json
{
  "type": "AgentUtterance",
  "transcript": "Hello there! How can I help you today?"
}
```
```

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

### HTTP API error response documentation

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

Reference list of standard HTTP status codes returned by the server during the initial connection phase.

```text
// HTTP API error responses
// 401 Unauthorized - Invalid or missing JWT token
// 404 Not Found - Endpoint doesn't exist
// 426 Upgrade Required - WebSocket upgrade header missing
// 500 Internal Server Error - Server-side error (e.g., missing deepgram.toml)
```

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

### Connect to WebSocket with Custom Deepgram Parameters

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

Establishes a WebSocket connection to the Deepgram voice agent, allowing customization of speech recognition and synthesis through query parameters. Requires a session token obtained from the /api/session endpoint.

```javascript
// Connect with custom Deepgram parameters
async function connectWithOptions(options = {}) {
  const sessionResponse = await fetch('http://localhost:8081/api/session');
  const { token } = await sessionResponse.json();

  // Build query string with Deepgram parameters
  const params = new URLSearchParams({
    model: options.model || 'nova-2',
    language: options.language || 'en-US',
    punctuate: 'true',
    interim_results: 'true',
    endpointing: options.endpointing || '300',
    ...options.extra
  });

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

  return new Promise((resolve, reject) => {
    ws.onopen = () => resolve(ws);
    ws.onerror = reject;
  });
}

// Example: Connect with Spanish language support
const spanishAgent = await connectWithOptions({
  language: 'es',
  model: 'nova-2'
});
```

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

### Live Agent Setting Updates

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

These JSON messages can be sent from the frontend to update agent settings like voice, prompt, or inject user messages without reconnecting.

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

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

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

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

### Connect to Voice Agent WebSocket

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

Client-side JavaScript function to establish a WebSocket connection to the voice agent. It first retrieves a session token and then connects, sending initial configuration and handling audio/control messages.

```javascript
// Client-side WebSocket connection with authentication
async function connectVoiceAgent() {
  // First, get a session token
  const sessionResponse = await fetch('http://localhost:8081/api/session');
  const { token } = await sessionResponse.json();

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

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

    // Send initial configuration to Deepgram
    const config = {
      type: 'SettingsConfiguration',
      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',
          instructions: 'You are a helpful voice assistant.'
        },
        speak: {
          model: 'aura-asteria-en'
        }
      }
    };
    ws.send(JSON.stringify(config));
  };

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

      // Message types include:
      // - Welcome: Connection established
      // - UserStartedSpeaking: User began talking
      // - AgentThinking: Agent processing
      // - AgentStartedSpeaking: Agent audio incoming
      // - ConversationText: Transcription/response text
      // - Error: Error occurred
    }
  };

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

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

  return ws;
}

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

// Usage
const voiceAgent = await connectVoiceAgent();
// Stream microphone audio to voiceAgent using sendAudioData()
```

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

### Stop Deno Voice Agent Processes

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

Use this command to find and kill processes running on ports 8080 and 8081.

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

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

### WebSocket /api/voice-agent

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

Establishes a bidirectional WebSocket connection to the voice agent. Authentication is handled via a subprotocol containing the JWT token.

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

### Description
Establishes a bidirectional WebSocket connection to Deepgram's Voice Agent API. The server proxies audio and control messages between the client and Deepgram.

### Method
WebSocket

### Endpoint
/api/voice-agent

### Parameters
#### Headers
- **Sec-WebSocket-Protocol** (string) - Required - Must be formatted as `access_token.<token>` where <token> is the JWT obtained from /api/session.
```

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

### Request Session Token

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

Use this curl command to request a signed JWT session token for authenticating WebSocket connections. Tokens expire after 1 hour.

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

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

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

### Handle WebSocket error messages

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

Parses incoming WebSocket messages to identify and react to specific error codes like DEEPGRAM_ERROR or CONNECTION_FAILED.

```javascript
// Handle error messages from the voice agent
ws.onmessage = (event) => {
  if (typeof event.data === 'string') {
    const message = JSON.parse(event.data);

    if (message.type === 'Error') {
      console.error(`Error [${message.code}]: ${message.description}`);

      // Common error codes:
      // - DEEPGRAM_ERROR: Deepgram connection or API error
      // - CONNECTION_FAILED: Failed to establish Deepgram connection
      // - UNKNOWN_ERROR: Unexpected error occurred

      // Handle specific errors
      switch (message.code) {
        case 'DEEPGRAM_ERROR':
          // Attempt reconnection
          reconnect();
          break;
        case 'CONNECTION_FAILED':
          // Show user-friendly message
          showError('Voice service unavailable. Please try again.');
          break;
        default:
          showError(message.description);
      }
    }
  }
};
```

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