OpenAI Realtime

​

Overview

​

Configuration Requirements

​

OpenAI API Key

• Field: openai_realtime_api_key
• Type: String (required)
• Purpose: Authenticates Coval’s connection to the OpenAI Realtime API
• Format: A valid OpenAI API key (starts with sk-) with Realtime API access enabled
• Security: Stored encrypted and handled securely

​

Agent System Instructions

• Field: openai_realtime_instructions
• Type: String (optional)
• Default: "" (model default instructions)
• Purpose: System prompt sent as session instructions to the Realtime model
• Use Cases: Role definition, behavior guidelines, response formatting
• Example: "You are a helpful customer support agent. Always be polite and provide accurate information."

​

Model

• Field: openai_realtime_model
• Type: String (optional)
• Default: gpt-realtime-2 (used when the field is omitted)
• Purpose: Selects which OpenAI Realtime model powers the agent

​

Agent Voice

• Field: openai_realtime_voice
• Type: String (optional)
• Default: alloy
• Purpose: Prebuilt voice used by the agent

​

Temperature

• Field: openai_realtime_temperature
• Type: Number (optional)
• Default: 0.8
• Range: 0.0 (deterministic) to 2.0 (very random)
• Purpose: Controls randomness in the agent’s responses

​

Web Search

• Field: openai_realtime_web_search_enabled
• Type: Boolean (optional)
• Default: false
• Purpose: Allows the agent to search the web for up-to-date information during the conversation. In the app, this is the Web Search checkbox under Advanced Settings.

​

Simulation Timeout

• Field: simulation_timeout_seconds
• Type: Integer (optional)
• Default: 900 (15 minutes)
• Range: 1 to 1800 (30 minutes)
• Purpose: Maximum duration for a single simulated conversation

​

Setup Instructions

​

Creating via the API

curl -X POST https://api.coval.dev/v1/agents \
  -H "x-api-key: YOUR_COVAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "OpenAI Realtime Voice Agent",
    "model_type": "MODEL_TYPE_OPENAI_REALTIME",
    "metadata": {
      "openai_realtime_api_key": "sk-...",
      "openai_realtime_instructions": "You are a helpful customer support agent...",
      "openai_realtime_model": "gpt-realtime-2",
      "openai_realtime_voice": "alloy",
      "openai_realtime_temperature": 0.8,
      "openai_realtime_web_search_enabled": false
    }
  }'

​

How Simulations Work

1. Opens a connection to the OpenAI Realtime API using your API key, model, voice, and system instructions
2. Plays the simulated user’s turns into the live session
3. Captures the agent’s audio responses and transcribes them
4. Records the full conversation transcript
5. Runs your configured metrics against the transcript

​

Troubleshooting

• Confirm the key is valid in your OpenAI dashboard and starts with sk-
• Verify your OpenAI account has Realtime API access

• Voice must match one of the allow-listed values above. Other strings are rejected at save time.
• marin requires a GPT Live model

• Temperature must be between 0.0 and 2.0. Values outside that range are rejected at save time.

• Increase Simulation Timeout if conversations are being cut short
• Check that your system instructions don’t tell the agent to end calls immediately