> ## 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.
# Gemini Live
> Evaluate a Google Gemini Live voice-to-voice agent without hosting your own endpoint
## Overview
Gemini Live agents are voice-to-voice agents where Coval connects directly to Google's [Gemini Live API](https://ai.google.dev/gemini-api/docs/live) 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 Gemini Live the fastest way to evaluate a Gemini-based agent configuration: tune the prompt, change the voice, bump the temperature, 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 Gemini Live. If your production agent runs on Pipecat, LiveKit, or a custom stack, connect it through the [matching integration](/concepts/agents/overview) instead.
## Configuration Requirements
The only required field for a `MODEL_TYPE_GEMINI_REALTIME` agent is `metadata.gemini_realtime_api_key`. Every other field below is optional — if omitted, Coval applies the default shown.
### Google AI API Key
* **Field**: `gemini_realtime_api_key`
* **Type**: String (required)
* **Purpose**: Authenticates Coval's connection to Gemini Live
* **Format**: Any valid Google AI key. Supports both `AIzaSy…` (AI Studio) and `AQ.…` (Express Mode) prefixes.
* **Security**: Stored encrypted and handled securely
Authentication errors (invalid key, missing Gemini Live access) surface the first time you run a simulation, not at agent save time. If your first simulation fails with an auth error, double-check the key has Gemini Live enabled.
### Agent System Instructions
* **Field**: `gemini_realtime_instructions`
* **Type**: String (optional)
* **Default**: `""` (model default instructions)
* **Purpose**: System prompt sent to Gemini Live as the agent's `system_instruction`
* **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**: `gemini_realtime_model`
* **Type**: String (optional)
* **Default**: `models/gemini-3.1-flash-live-preview` (used when the field is omitted)
* **Purpose**: Selects which Gemini Live model powers the agent
**Available Models:**
| Model ID | Description |
| -------------------------------------- | ------------------------------------------------- |
| `models/gemini-3.1-flash-live-preview` | Gemini 3.1 Flash Live — current recommended model |
| `models/gemini-2.0-flash-live-001` | Gemini 2.0 Flash Live — stable baseline |
### Agent Voice
* **Field**: `gemini_realtime_voice`
* **Type**: String (optional)
* **Default**: `Charon`
* **Purpose**: Prebuilt voice used by the agent
**Available Voices:**
| Voice | Description |
| -------- | ------------------- |
| `Puck` | Upbeat, neutral |
| `Charon` | Neutral, balanced |
| `Kore` | Warm, female |
| `Fenrir` | Deep, male |
| `Aoede` | Bright, female |
| `Leda` | Clear, female |
| `Orus` | Authoritative, male |
| `Zephyr` | Breezy, neutral |
### Temperature
* **Field**: `gemini_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
### 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
Create a key at [Google AI Studio](https://aistudio.google.com/apikey) and confirm it has Gemini Live access. Both `AIzaSy…` (AI Studio classic) and `AQ.…` (Express Mode) keys are supported.
Navigate to [app.coval.dev/agents/create](https://app.coval.dev/coval/agents/create) and select **Gemini Live** under Voice-to-Voice.
Paste your Google AI API key, write your system instructions, pick a model and voice, and adjust temperature if needed.
Create a test set, launch a simulation, and review the transcript and metric outputs.
## Creating via the API
Gemini Live agents can also be created with the [v1 Agents API](/api-reference/v1/agents/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": "Gemini Live Voice Agent",
"model_type": "MODEL_TYPE_GEMINI_REALTIME",
"metadata": {
"gemini_realtime_api_key": "AIzaSy...",
"gemini_realtime_instructions": "You are a helpful customer support agent...",
"gemini_realtime_model": "models/gemini-3.1-flash-live-preview",
"gemini_realtime_voice": "Charon",
"gemini_realtime_temperature": 0.8
}
}'
```
## How Simulations Work
When you launch a simulation against a Gemini Live agent, Coval:
1. Opens a connection to Gemini Live 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**
* Double-check that the key is entered correctly with no extra whitespace
* Confirm the key has Gemini Live access enabled in Google AI Studio
**Agent is unresponsive or cuts off early**
* Increase **Simulation Timeout** if conversations are being truncated
* Check that your system instructions don't tell the agent to end calls immediately
**Voice doesn't sound right**
* Switch to a different voice from the allow-list — each has a distinct character
* Confirm you're using a `native-audio` model, which supports the full voice catalog
**Temperature validation error**
* Temperature must be between `0.0` and `2.0`. Values outside that range are rejected at save time.