### Install Frontend Dependencies

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

Install Node.js dependencies for the frontend using pnpm.

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

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

### Install Backend Dependencies

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

Restore .NET NuGet packages for the backend project.

```bash
dotnet restore
```

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

### Initialize and Start Deepgram Voice Agent

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

Use these commands to initialize dependencies, set up environment variables, and start both the backend and frontend servers for the voice agent.

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

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

### Initialize and Run Application with Make

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

Use these Makefile targets to check prerequisites, initialize the project, set up environment variables, and start the backend and frontend servers. Ensure you copy and edit the .env file with your Deepgram API key.

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

```bash
# Initialize project - clone submodules and install dependencies
make init
```

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

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

```bash
# Start servers separately
make start-backend   # Terminal 1 - Backend on port 8081
make start-frontend  # Terminal 2 - Frontend on port 8080
```

```bash
# Run contract conformance tests (app must be running)
make test
```

```bash
# Clean build artifacts
make clean
```

```bash
# Update submodules to latest
make update
```

```bash
# Show repository and submodule status
make status
```

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

### Start Deepgram Voice Agent Frontend Separately

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

Run the frontend development server using pnpm.

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

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

### Conventional Commit Examples

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

Standardized commit message formats for the project.

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

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

### Start Deepgram Voice Agent Backend Separately

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

Run the C# backend server independently using the .NET CLI.

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

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

### GET /api/metadata

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

Retrieves application configuration and metadata details from the server's deepgram.toml file.

```APIDOC
## GET /api/metadata

### Description
Returns metadata about the application including use case, framework, language, and other configuration details.

### 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) - The defined use case
- **language** (string) - Programming language
- **framework** (string) - Backend framework
- **sdk** (string) - SDK information
- **tags** (array) - List of relevant tags

#### Response Example
{
  "title": "C# Voice Agent",
  "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/csharp-voice-agent",
  "useCase": "voice-agent",
  "language": "csharp",
  "framework": "dotnet",
  "sdk": "N/A",
  "tags": ["voice-agent", "conversational-ai"]
}
```

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

### GET /health

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

A simple health check endpoint used for monitoring and container orchestration.

```APIDOC
## GET /health

### Description
Provides a simple health check endpoint for monitoring and container orchestration platforms.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Service status
- **service** (string) - Service name

#### Response Example
{
  "status": "ok",
  "service": "voice-agent"
}
```

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

### GET /api/session

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

Issues a JWT session token required for authenticating WebSocket connections to the voice agent. The token expires after 1 hour.

```APIDOC
## GET /api/session

### Description
Issues a JWT session token for authenticating WebSocket connections. The token expires after 1 hour and must be passed via the WebSocket subprotocol header.

### Method
GET

### Endpoint
/api/session

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

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

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

### Configure Environment Variables

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

Set required API keys and server configuration in the .env file.

```bash
# Required - Get your key at https://console.deepgram.com
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional server configuration
PORT=8081              # Backend server port
HOST=0.0.0.0           # Backend bind address
FRONTEND_PORT=8080     # Frontend dev server port
```

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

### Deploy to Fly.io

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

Command to deploy the application to Fly.io. Ensure your Fly.io environment is set up and configured.

```bash
# Deploy to Fly.io
fly deploy
```

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

### Build and Run Docker Image

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

Build a Docker image for the application and run it as a container. This includes setting necessary environment variables like DEEPGRAM_API_KEY and SESSION_SECRET. The Caddyfile within the Dockerfile configures rate limiting and reverse proxying.

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

# Run the container
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key_here \
  -e SESSION_SECRET=your_production_secret \
  deepgram-voice-agent
```

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

### Configure Agent Settings

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

Initialize the voice agent by sending a Settings message over the WebSocket connection to define STT, TTS, and LLM parameters.

```javascript
// Full settings configuration with all options
const agentSettings = {
  type: "Settings",
  audio: {
    input: {
      encoding: "linear16",    // PCM audio format
      sample_rate: 16000       // 16kHz sample rate
    },
    output: {
      encoding: "linear16",
      sample_rate: 16000
    }
  },
  agent: {
    // Speech-to-Text configuration
    listen: {
      provider: {
        type: "deepgram",
        model: "nova-3"        // Options: nova-3, nova-2
      }
    },
    // Text-to-Speech configuration
    speak: {
      provider: {
        type: "deepgram",
        model: "aura-2-thalia-en"  // Any aura-* voice model
      }
    },
    // Language Model configuration
    think: {
      provider: {
        type: "open_ai",       // Options: open_ai, anthropic
        model: "gpt-4o-mini"   // Options: gpt-4o-mini, gpt-4o, etc.
      },
      prompt: "You are a friendly customer service agent for a coffee shop. Help customers with their orders and answer questions about the menu."
    }
  }
};

ws.send(JSON.stringify(agentSettings));
```

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

### Testing and Endpoint Verification

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

Commands to execute conformance tests and verify 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
```

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

### Fetch Application Metadata

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

Retrieves configuration details and service metadata from the deepgram.toml file.

```bash
# Fetch application metadata
curl -s http://localhost:8081/api/metadata | python3 -m json.tool
```

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

### Agent Function Calling Configuration

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

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

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

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

### Frontend Submodule Git Commands

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

Commands to commit and push changes to the frontend submodule and update the parent repository reference.

```bash
cd frontend && git add . && git commit -m "feat: description"
```

```bash
cd frontend && git push origin main
```

```bash
cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"
```

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

### Implement Function Calling

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

Define custom functions within the agent settings and handle incoming FunctionCallRequest events to provide tool-based responses.

```javascript
// Configure agent with function calling
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 helpful assistant with access to weather data.",
      functions: [
        {
          name: "get_weather",
          description: "Get current weather for a city",
          parameters: {
            type: "object",
            properties: {
              city: { type: "string", description: "City name" },
              units: { type: "string", enum: ["celsius", "fahrenheit"] }
            },
            required: ["city"]
          }
        },
        {
          name: "get_forecast",
          description: "Get 5-day weather forecast",
          parameters: {
            type: "object",
            properties: {
              city: { type: "string" },
              days: { type: "number", minimum: 1, maximum: 5 }
            },
            required: ["city"]
          }
        }
      ]
    }
  }
};

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

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

    if (msg.type === 'FunctionCallRequest') {
      // Execute the function
      let result;
      if (msg.function_name === 'get_weather') {
        result = { temperature: 72, condition: "sunny", humidity: 45 };
      } else if (msg.function_name === 'get_forecast') {
        result = { forecast: ["sunny", "cloudy", "rain", "sunny", "sunny"] };
      }

      // Send response back to agent
      const response = {
        type: "FunctionCallResponse",
        function_call_id: msg.function_call_id,
        output: JSON.stringify(result)
      };
      ws.send(JSON.stringify(response));
    }
  }
};
```

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

### Establish WebSocket Voice Connection

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

Connects to the voice agent and sends initial configuration settings. Handles bidirectional JSON messages and binary audio streams.

```javascript
// Complete WebSocket connection example with authentication
async function connectVoiceAgent() {
  // Step 1: Get session token
  const response = await fetch('http://localhost:8081/api/session');
  const { token } = await response.json();

  // Step 2: Connect 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');

    // Step 3: Send initial settings 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 assistant."
        }
      }
    };
    ws.send(JSON.stringify(settings));
  };

  ws.onmessage = (event) => {
    if (event.data instanceof Blob) {
      // Binary audio data from agent - play it
      playAudio(event.data);
    } else {
      // JSON message - handle events
      const msg = JSON.parse(event.data);
      console.log('Received:', msg.type, msg);
    }
  };

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

  return ws;
}
```

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

### WS /api/voice-agent

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

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

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

### Description
Establishes a full-duplex WebSocket connection for real-time voice conversations. Requires JWT authentication via the `access_token.<jwt>` subprotocol.

### Method
WS

### Endpoint
/api/voice-agent

### Parameters
#### Path Parameters
- **access_token.<jwt>** (string) - Required - The JWT token obtained from /api/session passed as a subprotocol.

### Request Body
- **type** (string) - Message type (e.g., "Settings")
- **audio** (object) - Audio configuration
- **agent** (object) - Agent configuration (listen, speak, think providers)
```

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

### Caddyfile Configuration

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

Configuration details for Caddy, used as a reverse proxy and for rate limiting. It specifies rate limits for different API endpoints and forwards requests to the backend.

```plaintext
# The Caddyfile configures:
# - Rate limiting: 5 req/min on /api/session, 120 req/min on /api/*
# - Reverse proxy to backend on port 8081
# - Static file serving for frontend
# - Health check endpoint at /health
```

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

### Live Agent Settings Updates

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

Send these JSON messages 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" }
```

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

### Update Agent Settings Live

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

Modify agent behavior during an active session by sending specific update commands without requiring a reconnection.

```javascript
// Change the agent's voice during conversation
const updateVoice = {
  type: "UpdateSpeak",
  model: "aura-2-luna-en"
};
ws.send(JSON.stringify(updateVoice));

// Change the system prompt dynamically
const updatePrompt = {
  type: "UpdatePrompt",
  prompt: "You are now a technical support specialist. Help users troubleshoot their devices."
};
ws.send(JSON.stringify(updatePrompt));

// Inject a text message as if the user spoke it
const injectMessage = {
  type: "InjectUserMessage",
  content: "I'd like to change my order to a large coffee instead"
};
ws.send(JSON.stringify(injectMessage));
```

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

### Clean Rebuild Deepgram Voice Agent

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

Remove build artifacts and node modules, then re-initialize dependencies for a clean build.

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

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

### Retrieve Session Token

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

Fetches a JWT session token required for WebSocket authentication. The token must be passed as a subprotocol header.

```bash
# Request a new session token
curl -s http://localhost:8081/api/session | python3 -m json.tool
```

```javascript
// Use the token in a WebSocket connection (JavaScript example)
const response = await fetch('http://localhost:8081/api/session');
const { token } = await response.json();

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

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

### Check Service Health

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

Verifies the operational status of the voice agent service.

```bash
# Check service health
curl -s http://localhost:8081/health | python3 -m json.tool
```

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

### Agent Settings Configuration

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

This JSON object configures the Deepgram Voice Agent's behavior, including audio settings, STT, TTS, and LLM providers. Send this message after connecting to the WebSocket.

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

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

### Stop Deepgram Voice Agent Processes

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

Terminate backend and frontend processes by finding and killing their PIDs on specified ports.

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

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