Deepgram Voice Agent

Overview

Deepgram Voice Agent agents are voice-to-voice agents where Coval connects directly to Deepgram’s Voice Agent API on your behalf. Deepgram runs the whole listen, think, and speak pipeline on its side, so you provide an API key, a system prompt, and the settings that describe your agent — Coval handles everything else. No webhook, no SIP trunk, and no self-hosted server required. This makes it the fastest way to evaluate a Deepgram-based agent configuration: change the prompt, swap the speech-recognition or voice model, add a tool definition, and re-run the same test set to see how the change affects behavior.

Use this connection when you want to evaluate an agent built directly on the Deepgram Voice Agent API. If your production agent runs on Pipecat, LiveKit, or a custom stack, connect it through the matching integration instead.

Configuration Requirements

The only required field for a MODEL_TYPE_DEEPGRAM_REALTIME agent is metadata.deepgram_realtime_api_key. Every other field below is optional — if omitted, Coval applies the default shown. Unlike the OpenAI Realtime, Gemini Live, and Grok Realtime connections, there are no single model, voice, or temperature fields. Deepgram’s API takes one Settings message that describes the full pipeline, so those choices live in the Voice pipeline fields and the Settings override described below.

Deepgram API Key

Field: deepgram_realtime_api_key
Type: String (required)
Purpose: Authenticates Coval’s connection to the Deepgram Voice Agent API
Format: Any Deepgram API key with Voice Agent API access, created in the Deepgram Console
Security: Stored encrypted and handled securely

Authentication errors (invalid key, missing Voice Agent access) surface the first time you run a simulation, not at agent save time.

Agent System Prompt

Field: deepgram_realtime_prompt
Type: String (optional)
Default: "" (falls back to any prompt set in the Settings override)
Purpose: Defines how the agent behaves. Sent as agent.think.prompt in the Settings message, and takes precedence over a prompt in the Settings override.
Example: "You are a helpful customer support agent. Always be polite and provide accurate information."

Voice pipeline

In the app, the Voice pipeline section edits the most common parts of the Settings message without writing JSON. Each choice is written into deepgram_realtime_settings for you:

Field	Writes to	Default
Speech recognition model	`agent.listen.provider.model`	`nova-3`
Language model provider and Language model	`agent.think.provider`	A Deepgram-managed OpenAI model
Agent voice model	`agent.speak.provider.model`	`flux-kit-en`
Agent greeting	`agent.greeting`	None

Model fields accept any current Deepgram model ID, so you are not limited to the suggestions in the dropdown — choose Custom model ID… to type one. Coval pairs each model with the provider version it needs (Nova and Aura models use v1; Flux models use v2). Set an Agent greeting when the agent should speak before the persona does.

If the Settings override contains invalid JSON, provider fallbacks, a custom endpoint, or a third-party voice provider, the guided fields pause so they never overwrite values they don’t understand. Keep editing those agents under Advanced Settings.

Agent Tool Definitions

Field: deepgram_realtime_functions
Type: JSON array (optional). In the app, under Advanced Settings.
Default: None
Purpose: Tools the agent may call, sent as agent.think.functions. Each item needs a name and may include description, parameters, and endpoint.
Example:

[
  {
    "name": "get_weather",
    "description": "Get the weather for a location",
    "parameters": {
      "type": "object",
      "properties": { "location": { "type": "string" } },
      "required": ["location"]
    }
  }
]

How a tool call is handled depends on whether the tool declares an endpoint:

With an endpoint — Deepgram calls your endpoint and feeds the real result back to the agent. Coval records the call in the transcript.
Without an endpoint — Coval records the call in the transcript and returns a simulated success response ({"status": "success"}) so the agent’s post-tool conversation continues. Coval does not execute any customer code.

Deepgram Settings Override

Field: deepgram_realtime_settings
Type: JSON object (optional). In the app, Full Deepgram Settings JSON under Advanced Settings.
Default: {}
Purpose: Deep-merged over Coval’s default Settings message before the session starts. Use it for anything the guided fields don’t cover: provider endpoints, fallbacks, turn-taking, keyterms, audio sample rates, third-party voices, and any newer Deepgram field. Nested objects merge key by key; lists and scalar values replace the default outright.
Precedence: The Agent System Prompt and Agent Tool Definitions fields win over duplicate values here.
Example:

{
  "agent": {
    "listen": { "provider": { "type": "deepgram", "model": "flux-general-en" } },
    "speak": { "provider": { "type": "deepgram", "version": "v2", "model": "flux-kit-en" } },
    "greeting": "Thanks for calling! How can I help?"
  }
}

Coval’s default Settings message uses Deepgram’s documented defaults for a minimal agent — 16 kHz linear16 audio in both directions, nova-3 for speech recognition, a Deepgram-managed OpenAI language model, and the flux-kit-en voice — so an override only needs the keys you want to change.

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

Get a Deepgram API key

Create a key in the Deepgram Console and confirm the project has Voice Agent API access.

Create the agent in Coval

Open Agents in the sidebar, click New Agent, and select Deepgram Voice Agent under Voice to Voice.

Configure the agent

Paste your Deepgram API key, write the system prompt, and pick the speech recognition, language, and voice models under Voice pipeline. Add tool definitions or a full Settings override under Advanced Settings if you need them.

Run a simulation

Create a test set, launch a simulation, and review the transcript and metric outputs.

Creating via the API

Deepgram Voice Agent agents can also be created with the v1 Agents 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": "Deepgram Voice Agent",
    "model_type": "MODEL_TYPE_DEEPGRAM_REALTIME",
    "metadata": {
      "deepgram_realtime_api_key": "YOUR_DEEPGRAM_API_KEY",
      "deepgram_realtime_prompt": "You are a helpful customer support agent...",
      "deepgram_realtime_functions": [
        {
          "name": "get_weather",
          "description": "Get the weather for a location",
          "parameters": {
            "type": "object",
            "properties": { "location": { "type": "string" } },
            "required": ["location"]
          }
        }
      ],
      "deepgram_realtime_settings": {
        "agent": {
          "listen": { "provider": { "type": "deepgram", "model": "nova-3" } },
          "greeting": "Thanks for calling! How can I help?"
        }
      },
      "simulation_timeout_seconds": 900
    }
  }'

deepgram_realtime_functions and deepgram_realtime_settings also accept a JSON-encoded string.

How Simulations Work

When you launch a simulation against a Deepgram Voice Agent, Coval:

Opens a connection to the Deepgram Voice Agent API using your API key and sends one Settings message built from your prompt, tool definitions, and Settings override
Plays the simulated user’s turns into the live session
Captures the agent’s audio responses and transcribes them
Records every tool call, answering the ones without an endpoint with a simulated success response
Records the full conversation transcript
Runs your configured metrics against the transcript

Troubleshooting

Invalid or missing API key

Confirm the key is valid in the Deepgram Console and the project has Voice Agent API access
Authentication errors surface on the first simulation, not when you save the agent

Tool definitions or Settings rejected on save

deepgram_realtime_functions must be a JSON array of objects, and every object needs a non-empty name
deepgram_realtime_settings must be a JSON object

Agent uses a different voice or model than expected

Check Full Deepgram Settings JSON: the guided Voice pipeline fields read from and write to the same keys, while the prompt and tool-definition fields override duplicates in the JSON

Agent is unresponsive or cuts off early

Set an Agent greeting if the agent should speak first; otherwise it waits for the persona
Increase Simulation Timeout if conversations are being cut short
Check that your system prompt doesn’t tell the agent to end calls immediately

Simulated Conversations

Evaluate

Analyze

Review

Cookbooks

Sofia

Reference

Overview

Configuration Requirements

Deepgram API Key

Agent System Prompt

Voice pipeline

Agent Tool Definitions

Deepgram Settings Override

Simulation Timeout

Setup Instructions

Creating via the API

How Simulations Work

Troubleshooting

​Overview

​Configuration Requirements

​Deepgram API Key

​Agent System Prompt

​Voice pipeline

​Agent Tool Definitions

​Deepgram Settings Override

​Simulation Timeout

​Setup Instructions

​Creating via the API

​How Simulations Work

​Troubleshooting

Overview

Configuration Requirements

Deepgram API Key

Agent System Prompt

Voice pipeline

Agent Tool Definitions

Deepgram Settings Override

Simulation Timeout

Setup Instructions

Creating via the API

How Simulations Work

Troubleshooting