> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rubrichq.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rubrichq.io/_mcp/server.

# Retell

Test an existing **Retell agent** with no code. RubricHQ connects to your Retell account, starts a web call to your agent, and runs your scenario against it — and can also **pull the agent's config** and **auto-import production calls** for observability.

This is an **external-provider** agent: the bot lives in Retell, and RubricHQ reaches it over Retell's own transport.

---

## 1. Connect Retell (once per workspace)

**Settings → Integrations → Retell** → paste your API key. It's stored encrypted and reused by every agent on Retell.

You can also connect inline from the agent screen when you pick the provider.

---

## 2. Configure the agent

On the agent's **Configuration** tab, choose **Agent Type → Retell** and set the **Agent ID** (e.g. `agent_xxxx…`). The ID field unlocks once Retell is connected for the workspace.

---

## 3. Instructions: Sync from vendor **or** Paste

Two mutually-exclusive options (buttons appear once the provider + Agent ID are set):

### Sync instructions from vendor

Pulls the latest config straight from Retell and fills the agent:

```json
{
  "instructions":  "<the agent's system prompt>",
  "first_message": { "type": "assistant-waits-for-user", "message": "" },
  "language":      "en-US",
  "phone_number":  "+15722238368"
}
```

* **Instructions** — the system prompt, used to generate scenarios and suggest prompt improvements.
* **Opening prompt** — derived from how your agent starts (speaks first vs waits), so our caller adapts.
* **Primary language** — matched to a supported language (locale-tolerant, e.g. `en` ↔ `en-US`).
* **Phone number** — see the note below.

> **Note**
>
> For **Retell**, the phone number isn't on the agent object — RubricHQ looks it up from your Retell phone numbers and matches the one linked to this agent (inbound/outbound).

### Paste instructions

Define the **opening prompt** and **instructions** yourself (just like a self-managed agent), and set primary language + phone number directly. Choosing this **disables instruction auto-sync** so Retell never overwrites what you typed.

---

## 4. Auto-sync (optional)

Two independent toggles under the agent's external-provider settings:

| Toggle                | What it does                                                                                                                                        |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sync instructions** | Re-pulls the Retell agent config on a fixed 24h cadence (disabled when you're pasting instructions).                                                |
| **Fetch calls**       | Imports the agent's **production calls** into RubricHQ observability on your chosen interval, with a configurable **minimum call duration** filter. |

Imported calls get the full observability treatment — transcript, recording, and standard metrics — alongside your test runs.

---

## 5. How a test run works

When you run a scenario/batch against a Retell agent:

1. RubricHQ starts a **web call** to your agent through the Retell API.
2. Our AI caller runs your scenario; we auto-detect whether your agent speaks first and adapt the opening.
3. The call is recorded; **transcript metrics** and (where audio is available) **audio metrics** are computed.

No endpoints to implement on your side — Retell hosts the bot, RubricHQ drives the caller.

---

## Results

Each run shows the **transcript**, **recording**, **call metadata** (end reason, cost, vendor summary, success/sentiment, structured data when present), and **metrics**. Auto-fetched production calls appear in **Observability → Conversations** for the agent.

> **Tip**
>
> Use **Retell** when the agent already lives in Retell. For Vapi assistants see [Vapi](/integrations/vapi); to run your own bot in a LiveKit or Daily room (e.g. Pipecat) see [LiveKit](/integrations/livekit) or [Daily](/integrations/daily).