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

# Grok Realtime

> Evaluate an xAI Grok voice-to-voice agent without hosting your own endpoint

## Overview

Grok Realtime agents are voice-to-voice agents where Coval connects directly to xAI's [Grok Voice Agent API](https://docs.x.ai/docs/guides/voice) on your behalf. You provide an API key, an agent prompt, a voice, and a model — Coval handles everything else. No webhook, no SIP trunk, and no self-hosted server required.

This makes Grok Realtime the fastest way to evaluate a Grok-based agent configuration: tune the prompt, change the voice, 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 Grok 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_GROK_REALTIME` agent is `metadata.grok_realtime_api_key`. Every other field below is optional — if omitted, Coval applies the default shown.

### xAI API Key

* **Field**: `grok_realtime_api_key`
* **Type**: String (required)
* **Purpose**: Authenticates Coval's connection to the Grok Voice Agent API
* **Format**: An xAI API key with Grok Voice Agent API access. Must start with `xai-`.
* **Security**: Stored encrypted and handled securely

### Agent System Instructions

* **Field**: `grok_realtime_instructions`
* **Type**: String (optional)
* **Default**: `""` (model default instructions)
* **Purpose**: System prompt sent as the session instructions to the Grok voice 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**: `grok_realtime_model`
* **Type**: String (optional)
* **Default**: `grok-voice-think-fast-1.0` (used when the field is omitted)
* **Purpose**: Selects which Grok voice model powers the agent

**Available Models:**

| Model ID                    | Description                                                                |
| --------------------------- | -------------------------------------------------------------------------- |
| `grok-voice-think-fast-1.0` | Grok Voice Think Fast 1.0 — xAI's flagship voice model                     |
| `grok-voice-latest`         | Grok Voice (Latest) — alias that always points to xAI's newest voice model |

### Agent Voice

* **Field**: `grok_realtime_voice`
* **Type**: String (optional)
* **Default**: `ara`
* **Purpose**: Prebuilt voice used by the agent

**Available Voices:**

| Voice | Description                 |
| ----- | --------------------------- |
| `eve` | Energetic, upbeat, female   |
| `ara` | Warm, friendly, female      |
| `rex` | Confident, clear, male      |
| `sal` | Smooth, balanced, neutral   |
| `leo` | Authoritative, strong, male |

<Note>
  There is no temperature setting for Grok Realtime agents. The Grok Voice Agent API does not expose a temperature knob, so tune response style through the system instructions instead.
</Note>

### 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 an xAI API key">
    Create a key in the [xAI Console](https://console.x.ai/) and confirm it has Grok Voice Agent API access. Keys start with `xai-`.
  </Step>

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

  <Step title="Configure the agent">
    Paste your xAI API key, write your system instructions, and pick a model and voice.
  </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

Grok Realtime 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": "Grok Realtime Voice Agent",
    "model_type": "MODEL_TYPE_GROK_REALTIME",
    "metadata": {
      "grok_realtime_api_key": "xai-...",
      "grok_realtime_instructions": "You are a helpful customer support agent...",
      "grok_realtime_model": "grok-voice-think-fast-1.0",
      "grok_realtime_voice": "ara",
      "simulation_timeout_seconds": 900
    }
  }'
```

## How Simulations Work

When you launch a simulation against a Grok Realtime agent, Coval:

1. Opens a connection to the Grok Voice Agent 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

**Invalid or missing API key**

* The key must start with `xai-` — the agent form flags keys without that prefix
* Confirm the key is valid in the xAI Console and has Grok Voice Agent API access

**Voice rejected on save**

* Voice must be one of `eve`, `ara`, `rex`, `sal`, or `leo`. Other strings are rejected at save time.

**Responses are too random or too flat**

* Grok Realtime has no temperature setting. Adjust the system instructions — for example, ask for concise, consistent answers, or give examples of the tone you want.

**Agent is unresponsive or cuts off early**

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