Configuration Guide

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

Configuration Structure

{
  "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

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

Language Codes

LLM Configuration

Basic Setup

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

Provider Options

Advanced LLM Config

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

STT Configuration

Basic Setup

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

Provider Options

Advanced STT Config

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

TTS Configuration

Basic Setup

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

Provider Options

Advanced TTS Config

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

System Prompt

Structure

{
  "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

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

Turn Detection

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

Greeting

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

Tools (Function Calling)

{
  "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

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

Recording

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

Environment Variables

Required environment variables by provider:

# 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

{
  "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 - Deploy your first agent
• LLM Providers - Choose the right LLM
• STT Providers - Configure speech recognition
• TTS Providers - Select voices