### Initialize and Start Go Voice Agent

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

Use the Makefile to initialize the project, configure environment variables, and start the local development server.

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

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

### Start frontend server individually with Makefile

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

Start only the frontend server on http://localhost:8080 using the Makefile.

```bash
make start-frontend
```

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

### Dependency Installation

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

Commands to install backend Go modules and frontend dependencies.

```bash
go mod download
cd frontend && corepack pnpm install
```

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

### Start backend server individually with Makefile

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

Start only the backend API server on http://localhost:8081 using the Makefile.

```bash
make start-backend
```

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

### Start backend and frontend servers with Makefile

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

Start both the backend (port 8081) and frontend (port 8080) servers simultaneously using the Makefile.

```bash
make start
```

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

### Start the server

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

Run the Go application using the go run command.

```bash
go run main.go
```

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

### Initialize project with Makefile

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

Initialize the project by cloning submodules and installing all dependencies using the Makefile.

```bash
make init
```

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

### Initialize and Start Project

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

Commands to initialize submodules, configure environment variables, and launch the development 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
```

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

### Commit Message Examples

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

Examples of commit messages following the conventional commits format required for this repository.

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

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

### Check prerequisites with Makefile

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

Use the Makefile to check if Git and Go are installed on your system.

```bash
make check-prereqs
```

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

### Start and Stop Commands

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

Utility commands for managing the lifecycle of the backend and frontend processes.

```bash
make start
```

```bash
# Terminal 1 — Backend
go run .

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

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

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

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

### Function Calling Configuration

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

Example of adding function definitions to the agent settings for tool usage.

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

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

### Environment Configuration

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

Example of required and optional environment variables for configuring the server. `DEEPGRAM_API_KEY` is mandatory.

```bash
# Required environment variables
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional environment variables with defaults
PORT=8081                    # Backend API server port
HOST=0.0.0.0                 # Server host binding
SESSION_SECRET=your_secret   # JWT signing secret (auto-generated if not set)

```

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

### GET /api/metadata

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

Endpoint to retrieve application metadata.

```APIDOC
## GET /api/metadata

### Description
Returns application metadata, including use case, framework, and language information.

### Method
GET

### Endpoint
`/api/metadata`

### Authentication
None
```

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

### GET /api/metadata

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

Retrieves project metadata from the deepgram.toml configuration file.

```APIDOC
## GET /api/metadata

### Description
Returns project metadata from the deepgram.toml configuration file, including title, description, and tags.

### 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) - Use case identifier
- **language** (string) - Programming language
- **framework** (string) - Framework used
- **sdk** (string) - SDK information
- **tags** (array) - List of project tags

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

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

### GET /api/session

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

### Method
GET

### Endpoint
`/api/session`

### Authentication
None
```

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

### Connect to Voice Agent WebSocket

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

JavaScript example demonstrating how to connect to the voice agent WebSocket. It first fetches a session token and then establishes the WebSocket connection using the token as a subprotocol. The first message sent is a configuration object for the Deepgram agent.

```javascript
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 WebSocket with token as 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 configuration to Deepgram (first message)
    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' },
        speak: { model: 'aura-asteria-en' }
      }
    };
    ws.send(JSON.stringify(config));
  };

  ws.onmessage = (event) => {
    if (event.data instanceof Blob) {
      // Binary audio data from Deepgram TTS
      playAudio(event.data);
    } else {
      // JSON messages (transcripts, agent responses, etc.)
      const message = JSON.parse(event.data);
      console.log('Received:', message.type, message);
    }
  };

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

  return ws;
}

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

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

### GET /health

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

A simple health check endpoint for monitoring and load balancer probes.

```APIDOC
## GET /health

### Description
Returns a JSON status indicating the server is running.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The current status of the server (e.g., "ok").
```

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

### Project Metadata Response

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

Example JSON response containing project metadata. This information is useful for frontends to display project details.

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

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

### Session Token Error Response

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

Example JSON error response when failing to issue a session token.

```json
{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "Failed to issue session token"
}
```

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

### Session Token Response

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

Example JSON response containing the JWT session token. This token must be passed as a WebSocket subprotocol.

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDk4NDQ4MDAsImV4cCI6MTcwOTg0ODQwMH0.signature"
}
```

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

### Health Check Response

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

Example JSON response from the health check endpoint, indicating the server is running.

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

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

### Metadata Error Response

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

Example JSON error response when the `deepgram.toml` file or its `[meta]` section is missing.

```json
{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "Failed to read metadata from deepgram.toml"
}
```

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

### GET /api/session

Source: https://context7.com/deepgram-starters/go-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 are valid for 1 hour and use HS256 signing.

### Method
GET

### Endpoint
/api/session

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

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

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

### Build Docker image

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

Build a Docker image for the Go Voice Agent application using a multi-stage Dockerfile.

```bash
docker build -f deploy/Dockerfile -t go-voice-agent .
```

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

### Deploy to Fly.io

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

Deploy the application to Fly.io by launching, setting secrets, and deploying.

```bash
fly launch
fly secrets set DEEPGRAM_API_KEY=your_api_key
fly secrets set SESSION_SECRET=your_production_secret
fly deploy
```

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

### Copy sample environment and add API key

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

Copy the sample environment file and edit it to include your Deepgram API key.

```bash
cp sample.env .env
# Edit .env and set DEEPGRAM_API_KEY=your_key
```

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

### Show project status with Makefile

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

Display the current project status using the Makefile.

```bash
make status
```

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

### Agent Configuration Settings

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

JSON structure sent from the frontend to configure audio and agent parameters upon 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."
    }
  }
}
```

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

### Create .env file

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

Create a .env file to store your Deepgram API key and server configuration.

```bash
cat > .env << 'EOF'\nDEEPGRAM_API_KEY=dg_abc123xyz\nPORT=8081\nHOST=0.0.0.0\nSESSION_SECRET=my-production-secret-key\nEOF
```

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

### Run Docker container

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

Run the Docker container, exposing port 8080 and setting necessary environment variables.

```bash
docker run -p 8080:8080 \
  -e DEEPGRAM_API_KEY=your_api_key \
  -e SESSION_SECRET=your_production_secret \
  go-voice-agent
```

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

### Eject frontend with Makefile

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

Eject the frontend from its submodule into a regular directory using the Makefile.

```bash
make eject-frontend
```

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

### Testing and Endpoint Verification

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

Commands to execute conformance tests and manually verify API endpoints using curl.

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

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

### Clean build artifacts with Makefile

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

Remove build artifacts from the project using the Makefile.

```bash
make clean
```

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

### Update submodules with Makefile

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

Update project submodules to their latest versions using the Makefile.

```bash
make update
```

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

### API Endpoints

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

Overview of the available API endpoints for the Go 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. |
```

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

### Request Project Metadata

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

Use this cURL command to retrieve project metadata, such as title, description, and tags, from the `deepgram.toml` configuration file.

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

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

### Deepgram TOML Configuration

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

The deepgram.toml file configures project metadata and lifecycle commands for Deepgram tooling.

```toml
[meta]
title = "Go Voice Agent"
description = "Get started using Deepgram's Voice Agent with this Go demo app"
author = "Deepgram DX Team <devrel@deepgram.com>"
repository = "https://github.com/deepgram-starters/go-voice-agent"
useCase = "voice-agent"
language = "go"
framework = "go"
sdk = "N/A"
tags = ["voice-agent", "conversational-ai", "voice-ai", "voice-bot", "go"]

[check]
command = ["command -v git", "command -v go"]
message = "Prerequisites checked"

[install]
command = "go mod tidy"
message = "Dependencies installed"

[install.config]
sample = "sample.env"
output = ".env"

[start]
command = ["go run main.go", "cd frontend && pnpm run dev -- --port 8080 --no-open"]
parallel = true
message = "Application running on http://localhost:8080"
```

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

### WS /api/voice-agent

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

Establishes a bidirectional WebSocket proxy to Deepgram's Voice Agent API, requiring a JWT token as a subprotocol.

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

### Description
Establishes a bidirectional WebSocket proxy to Deepgram's Voice Agent API. All messages (audio binary data and JSON control messages) are forwarded transparently.

### Method
WS

### Endpoint
/api/voice-agent

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

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

### Request Session Token

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

Use this cURL command to request a JWT session token for authenticating WebSocket connections. Tokens are valid for 1 hour.

```bash
curl -X GET http://localhost:8081/api/session
```

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

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

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

Details on the full-duplex WebSocket API for 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`

### Authentication
JWT (using `access_token.<jwt>` subprotocol)

### Request Body (Settings Message Example)
Sent from the frontend after connecting 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."
    }
  }
}
```

### Request Body (Live Updates Examples)
Sent from the frontend to update settings mid-conversation.

- **Update Speak Model:**
```json
{
  "type": "UpdateSpeak",
  "model": "aura-2-luna-en"
}
```

- **Update Prompt:**
```json
{
  "type": "UpdatePrompt",
  "prompt": "New instructions..."
}
```

- **Inject User Message:**
```json
{
  "type": "InjectUserMessage",
  "content": "text"
}
```

### Request Body (Function Calling Example)
Adding function definitions to the Settings message.

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

### Response (Function Call Request Example)
Received from Deepgram when a function call is triggered.

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

### Response (Function Call Response Example)
Sent from the frontend to provide the result of a function call.

```json
{
  "type": "FunctionCallResponse",
  "response": {
    "content": "The weather in New York is sunny."
  }
}
```
```

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

### Live Update Messages

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

JSON messages used to modify agent behavior or send text without reconnecting.

```json
{ "type": "UpdateSpeak", "model": "aura-2-luna-en" }
{ "type": "UpdatePrompt", "prompt": "New instructions..." }
{ "type": "InjectUserMessage", "content": "text" }
```

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

### Health Check Request

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

A simple cURL command for a health check. This endpoint is used for monitoring and load balancer health probes.

```bash
curl -X GET http://localhost:8081/health
```

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