# Configuration Guide

> Complete guide to configuring your voice agent including providers, prompts, and advanced settings.

Source: https://edesy.in/docs/voice-agent/getting-started/configuration

This guide covers all configuration options for your voice agent, from basic setup to advanced tuning.

## Configuration Structure

```json
{
  "agent": {
    "name": "Customer Support",
    "language": "en-US",

    // LLM Configuration
    "llmProvider": "gemini-2.5",
    "llmModel": "gemini-2.5-flash-lite",
    "llmTemperature": 0.7,
    "prompt": "You are a helpful assistant...",

    // STT Configuration
    "sttProvider": "deepgram",
    "sttModel": "nova-3",
    "sttConfig": {},

    // TTS Configuration
    "ttsProvider": "cartesia",
    "ttsVoice": "voice-id",
    "ttsConfig": {},

    // Behavior
    "greetingMessage": "Hello! How can I help?",
    "allowInterruptions": true,

    // Tools
    "tools": [],

    // Webhooks
    "webhooks": {}
  }
}
```

## Core Settings

### Agent Identity

```json
{
  "name": "Customer Support",
  "description": "Handles customer inquiries",
  "language": "en-US",
  "timezone": "America/New_York"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Agent display name |
| `description` | string | No | Agent description |
| `language` | string | Yes | BCP-47 language code |
| `timezone` | string | No | IANA timezone |

### Language Codes

| Language | Code |
|----------|------|
| English (US) | en-US |
| English (UK) | en-GB |
| English (India) | en-IN |
| Hindi | hi-IN |
| Spanish | es-ES |
| French | fr-FR |
| German | de-DE |

## LLM Configuration

### Basic Setup

```json
{
  "llmProvider": "gemini-2.5",
  "llmModel": "gemini-2.5-flash-lite",
  "llmTemperature": 0.7
}
```

### Provider Options

| Provider | Models | Best For |
|----------|--------|----------|
| `gemini-2.5` | gemini-2.5-flash-lite | Fastest, cheapest |
| `gemini` | gemini-2.0-flash | Good balance |
| `gemini-live` | Native audio | Lowest latency |
| `gemini-live-2.5` | HD audio | Premium experience |
| `openai` | gpt-4o, gpt-4o-mini | Best reasoning |
| `anthropic` | claude-3.5-sonnet | Long context |
| `openai-azure` | gpt-4o | Enterprise |

### Advanced LLM Config

```json
{
  "llmConfig": {
    "temperature": 0.7,
    "maxTokens": 500,
    "topP": 0.95,
    "topK": 40,
    "stopSequences": [],
    "frequencyPenalty": 0.0,
    "presencePenalty": 0.0
  }
}
```

| Parameter | Range | Default | Description |
|-----------|-------|---------|-------------|
| `temperature` | 0.0-2.0 | 0.7 | Randomness (lower = deterministic) |
| `maxTokens` | 1-4096 | 500 | Maximum response length |
| `topP` | 0.0-1.0 | 0.95 | Nucleus sampling |
| `topK` | 1-100 | 40 | Top-K sampling |

## STT Configuration

### Basic Setup

```json
{
  "sttProvider": "deepgram",
  "sttModel": "nova-3"
}
```

### Provider Options

| Provider | Model | Best For |
|----------|-------|----------|
| `deepgram` | nova-3 | Lowest latency |
| `google` | chirp_2 | Indic languages |
| `azure` | - | Enterprise |
| `elevenlabs` | - | Regional languages |
| `assemblyai` | - | Accuracy |

### Advanced STT Config

```json
{
  "sttConfig": {
    "language": "en-US",
    "punctuate": true,
    "profanityFilter": false,
    "endpointing": 300,
    "interimResults": true,
    "keywords": ["Edesy:2", "voice agent:2"]
  }
}
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `punctuate` | bool | true | Add punctuation |
| `profanityFilter` | bool | false | Filter profanity |
| `endpointing` | int | 300 | Silence (ms) to end |
| `interimResults` | bool | true | Stream partial results |
| `keywords` | array | [] | Boost specific terms |

## TTS Configuration

### Basic Setup

```json
{
  "ttsProvider": "cartesia",
  "ttsVoice": "95856005-0332-41b0-935f-352e296aa0df"
}
```

### Provider Options

| Provider | Best For |
|----------|----------|
| `cartesia` | Lowest latency |
| `elevenlabs` | Premium quality |
| `azure` | Indic languages |
| `google` | Multilingual |
| `openai` | Simple setup |
| `deepgram` | Speed |

### Advanced TTS Config

```json
{
  "ttsConfig": {
    "speed": 1.0,
    "pitch": 0,
    "volume": 100,
    "stability": 0.5,
    "emotion": []
  }
}
```

| Parameter | Range | Default | Description |
|-----------|-------|---------|-------------|
| `speed` | 0.5-2.0 | 1.0 | Speaking rate |
| `pitch` | -20 to +20 | 0 | Voice pitch (%) |
| `volume` | 0-100 | 100 | Output volume |
| `stability` | 0.0-1.0 | 0.5 | Voice consistency |

## System Prompt

### Structure

```json
{
  "prompt": "You are Alex, a customer support agent for Acme Corp.\n\n## Your Role\n- Help customers with their orders\n- Answer product questions\n- Escalate complex issues\n\n## Guidelines\n- Keep responses short (1-2 sentences)\n- Be friendly but professional\n- Never make up information\n\n## Tools\nYou have access to:\n- get_order_status: Look up orders\n- transfer_call: Connect to human"
}
```

### Best Practices

1. **Define persona**: Name, role, personality
2. **Set boundaries**: What to do and not do
3. **Voice guidelines**: Response length, tone
4. **Tool descriptions**: Available capabilities

### Example Prompts

**Customer Support:**
```
You are Alex, a friendly customer support agent.

Rules:
- Keep responses under 30 words
- Be empathetic with frustrated customers
- Transfer to human for: refunds over $100, legal issues, complaints
- Never promise what you can't deliver
```

**Sales Qualifier:**
```
You are a sales development representative.

Goals:
- Understand the prospect's needs
- Qualify using BANT (Budget, Authority, Need, Timeline)
- Schedule demos for qualified leads

Be consultative, not pushy.
```

## Behavior Settings

### Interruptions

```json
{
  "allowInterruptions": true,
  "interruptionConfig": {
    "minSpeechDuration": 200,
    "confidenceThreshold": 0.8
  }
}
```

### Turn Detection

```json
{
  "turnDetection": {
    "mode": "hybrid",
    "silenceDuration": 300,
    "maxTurnDuration": 30000
  }
}
```

### Greeting

```json
{
  "greetingMessage": "Hello! Thanks for calling Acme. How can I help?",
  "greetingDelay": 500
}
```

## Tools (Function Calling)

```json
{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_order_status",
        "description": "Get the status of a customer order",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string",
              "description": "The order ID"
            }
          },
          "required": ["order_id"]
        }
      }
    }
  ]
}
```

## Webhooks

```json
{
  "webhooks": {
    "url": "https://your-server.com/webhook",
    "events": ["call.started", "call.ended", "transcript.updated"],
    "headers": {
      "Authorization": "Bearer token"
    }
  }
}
```

## Recording

```json
{
  "recording": {
    "enabled": true,
    "format": "mp3",
    "channels": "dual",
    "retentionDays": 90
  }
}
```

## Environment Variables

Required environment variables by provider:

```bash
# LLM
GOOGLE_AI_API_KEY=       # Gemini
OPENAI_API_KEY=          # OpenAI
ANTHROPIC_API_KEY=       # Anthropic
AZURE_OPENAI_API_KEY=    # Azure OpenAI
AZURE_OPENAI_ENDPOINT=

# STT
DEEPGRAM_API_KEY=
GOOGLE_CREDENTIALS_PATH=
AZURE_SPEECH_API_KEY=
AZURE_SPEECH_REGION=
ELEVENLABS_API_KEY=
ASSEMBLYAI_API_KEY=

# TTS
CARTESIA_API_KEY=
# (ELEVENLABS, GOOGLE, AZURE same as STT)

# Telephony
TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
EXOTEL_API_KEY=
EXOTEL_API_TOKEN=
PLIVO_AUTH_ID=
PLIVO_AUTH_TOKEN=
```

## Complete Example

```json
{
  "agent": {
    "name": "Acme Support",
    "language": "en-US",

    "llmProvider": "gemini-2.5",
    "llmModel": "gemini-2.5-flash-lite",
    "llmTemperature": 0.7,

    "sttProvider": "deepgram",
    "sttModel": "nova-3",
    "sttConfig": {
      "endpointing": 300,
      "interimResults": true
    },

    "ttsProvider": "cartesia",
    "ttsVoice": "95856005-0332-41b0-935f-352e296aa0df",

    "prompt": "You are a helpful customer support agent for Acme Corp. Keep responses brief and friendly.",

    "greetingMessage": "Hello! Thanks for calling Acme. How can I help you today?",
    "allowInterruptions": true,

    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_order_status",
          "description": "Look up an order by ID",
          "parameters": {
            "type": "object",
            "properties": {
              "order_id": {"type": "string"}
            },
            "required": ["order_id"]
          }
        }
      }
    ],

    "webhooks": {
      "url": "https://api.example.com/webhooks/voice",
      "events": ["call.ended"]
    },

    "recording": {
      "enabled": true,
      "format": "mp3"
    }
  }
}
```

## Next Steps

- [Quick Start](https://edesy.in/docs/voice-agent/getting-started/quick-start) - Deploy your first agent
- [LLM Providers](https://edesy.in/docs/voice-agent/llm) - Choose the right LLM
- [STT Providers](https://edesy.in/docs/voice-agent/stt) - Configure speech recognition
- [TTS Providers](https://edesy.in/docs/voice-agent/tts) - Select voices