> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Deepgram Voice Agent

> Evaluate a Deepgram Voice Agent without hosting your own endpoint

## Overview

Deepgram Voice Agent agents are voice-to-voice agents where Coval connects directly to Deepgram's [Voice Agent API](https://developers.deepgram.com/docs/voice-agent) 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.

<Info>
  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](/concepts/agents/overview) instead.
</Info>

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

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

### 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.

<Note>
  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**.
</Note>

### 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**:

```json theme={null}
[
  {
    "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**:

```json theme={null}
{
  "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

<Steps>
  <Step title="Get a Deepgram API key">
    Create a key in the [Deepgram Console](https://console.deepgram.com/) and confirm the project has Voice Agent API access.
  </Step>

  <Step title="Create the agent in Coval">
    Open **Agents** in the sidebar, click **New Agent**, and select **Deepgram Voice Agent** under **Voice to Voice**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Run a simulation">
    Create a test set, launch a simulation, and review the transcript and metric outputs.
  </Step>
</Steps>

## Creating via the API

Deepgram Voice Agent agents can also be created with the [v1 Agents API](/api-reference/agents/connect-an-agent):

```bash theme={null}
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:

1. 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
2. Plays the simulated user's turns into the live session
3. Captures the agent's audio responses and transcribes them
4. Records every tool call, answering the ones without an `endpoint` with a simulated success response
5. Records the full conversation transcript
6. 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