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

# WebRTC Connection

> A reusable connection that lets Galtea reach your AI voice agent over WebRTC for voice evaluation.

## What is a WebRTC Connection?

A WebRTC Connection tells Galtea how to reach your AI voice agent over WebRTC. WebRTC is a standard for real-time audio and video over the internet. Instead of calling an HTTP API, Galtea **opens a live WebRTC session with your agent** and runs the conversation as a real voice call. This is **Direct Inference over WebRTC**.

Galtea reaches your agent through [Pipecat Cloud](https://pipecat.ai). You give Galtea two things once: a Pipecat Cloud **public API key** (`pk_...`) and the **agent name** to target. Galtea then uses them to drive voice evaluations against your agent automatically. The simulated caller's language is taken from each **test case** (see [below](#how-the-caller-s-language-is-chosen)), so one connection serves test cases in different languages.

<Note>
  The API key is a secret. Galtea stores it encrypted and the API never returns it. A fetched connection tells you only whether a key is set, through a `has_api_key` boolean. It never shows the key itself.
</Note>

<Warning>
  **Coming soon.** You can create and manage WebRTC connections now, and attach one to a version. Running a voice evaluation over WebRTC is not available yet. A version whose only conversation target is a WebRTC connection cannot run until this path ships. The sections below describe how voice evaluation over WebRTC will work once it is available.
</Warning>

## Use Cases

* **Evaluate voice agents** — Galtea opens a WebRTC session with your agent for each test case, exercising the full voice stack.
* **Multi-turn conversation evaluation** — For Behavior test cases, Galtea drives a full conversation using the test case's persona, goal, and scenario, with the conversation simulator generating each user turn.
* **Single-turn evaluation** — For Accuracy and Security test cases, Galtea speaks the test case's input line into the call and evaluates the agent's reply. This is the voice equivalent of a single-turn HTTP run.
* **Standardize call configuration** — Define a reusable WebRTC connection for repeatable voice evaluations.
* **Manage multiple agents** — Create separate WebRTC connections for different agents or environments.

## Creating a WebRTC Connection

To create a WebRTC Connection:

1. Navigate to your product in the [Galtea Dashboard](https://platform.galtea.ai/)
2. Go to the "WebRTC Connections" section
3. Click "New WebRTC Connection"
4. Configure the connection properties as described below

## WebRTC Connection Properties

<ResponseField name="Name" type="Text" required>
  A unique name for the WebRTC connection within the product. **Example**: "Production Voice Agent" or "Staging Agent".
</ResponseField>

<ResponseField name="API Key" type="Text" required>
  The Pipecat Cloud **public API key** (`pk_...`) Galtea uses to reach your agent. This is the credential its runtime `/start` call needs, **not** the `pcc_pat_` Personal Access Token you use to deploy the agent. This is a secret. Galtea stores it encrypted at rest. The API never returns it, so you cannot read it back. To replace it, set a new value. To check whether a key is stored, read the `has_api_key` boolean on a fetched connection.
</ResponseField>

<ResponseField name="Agent Name" type="Text" required>
  The name of your deployed Pipecat Cloud agent. It must match that agent's name exactly, and it is resolved within the organization that owns the public API key. Galtea passes it to Pipecat Cloud's `/start` call to launch the session; if no deployed agent has this name, the call fails. **Example**: `my-pipecat-agent`.
</ResponseField>

<ResponseField name="Agent Speaks First" type="Checkbox">
  Controls whether the voice agent opens the conversation once the session connects. Leave it **unchecked** (the default) when the simulated caller should speak first, which suits agents that wait for a greeting from the user. **Check** it for interviewer-style agents that greet the caller first.
</ResponseField>

## How the caller's language is chosen

The simulated caller's spoken language is **not** set on the WebRTC connection. It comes from each [test case](/concepts/product/test/case)'s language. Because a WebRTC connection is attached to a [Version](/concepts/product/version) and a version runs many test cases, this lets one connection cover test cases in different languages.

With a multilingual text-to-speech provider, the test case's language drives the synthesis language and the voice is selected automatically (for example, a Spanish test case means the caller speaks Spanish with a natively-accented voice). When a test case has no language set, the provider falls back to its configured default voice.

## Relation to Versions

A WebRTC Connection becomes the **conversation target** of a [Version](/concepts/product/version): when a version references a WebRTC connection, Galtea opens a session with that agent to run each evaluation.

A version's conversation target is **mutually exclusive**. A version connects to your AI product either through an [Endpoint Connection](/concepts/product/endpoint-connection), a [Phone Connection](/concepts/product/phone-connection), **or** a WebRTC Connection, never more than one. Choose an endpoint connection when Galtea should call your HTTP API, a phone connection when Galtea should place a phone call, or a WebRTC connection when Galtea should open a WebRTC session.

## Relation to Voice Evaluation

WebRTC Connections power **voice evaluation**: because Galtea drives a real voice call, the conversation, transcription, and resulting inferences reflect how your agent behaves over the voice channel. This makes WebRTC connections one entry point for evaluating voice agents end-to-end.

WebRTC connections run **any** test type. No extra configuration is required beyond attaching the WebRTC connection to the version:

* **Behavior** test cases run multi-turn: the conversation simulator drives each user turn from the test case's persona, goal, and scenario.
* **Accuracy** and **Security** test cases run single-turn: Galtea speaks the test case's input line into the call and evaluates the agent's reply.

<Note>
  For single-turn (Accuracy/Security) tests scored by **deterministic metrics**, leave **Agent Speaks First** unchecked (the default). When the agent speaks first, the call has two turns (the agent's greeting plus the scripted line), which deterministic metrics, designed for a single turn, cannot score correctly. Multi-turn (Behavior) tests are unaffected.
</Note>

The API automatically transcribes the agent's audio responses using speech-to-text, so no manual transcript preparation is required. Each recorded agent turn is transcribed before evaluation runs, and the written transcript is what metrics score. Your agent's voice output is evaluated as accurately as any text-based agent.

Both sides of every turn are recorded and stored on the `InferenceResult` for that turn:

* **Agent audio** (what your agent said): stored as a content-parts envelope on `actualOutput`; access the envelope via the SDK's `.actual_output_data` field and the scored transcript via `.actual_output`.
* **Simulated user audio** (what the synthetic caller said): stored as a content-parts envelope on `input`; access the envelope via the SDK's `.input_data` field and the spoken transcript via `.input`.

This means the full voice conversation, both the synthetic user side and the agent side, can be played back turn by turn in the dashboard's audio player and read programmatically via the SDK. See [InferenceResult](/concepts/product/version/session/inference-result) for the envelope shapes.

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive names">
    Choose names that clearly identify the agent's purpose and environment, such as "Production Voice Agent" or "Staging Agent".
  </Accordion>

  <Accordion title="Keep the API key secret">
    The Pipecat Cloud API key is write-only. You set it on create or update, and the API never returns it. Store the key in your own secret manager too, because Galtea cannot show it back to you. To rotate it, set a new value on the connection.
  </Accordion>

  <Accordion title="Set the call's language on the test case">
    Set each test case's language to the language your agent operates in. With a multilingual text-to-speech provider the simulated caller then speaks that language with a natively-accented voice (for example, Spanish), with no per-connection configuration needed.
  </Accordion>

  <Accordion title="Set who speaks first">
    If your agent greets the caller (interviewer-style), check **Agent Speaks First**. Leave it unchecked when your agent waits for the user to initiate the conversation.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Concepts overview" icon="diagram-project" iconType="solid" href="/concepts/overview">
    How Galtea's concepts connect — diagram + per-entity quick reference.
  </Card>

  <Card title="Endpoint Connection" icon="plug" href="/concepts/product/endpoint-connection">
    Connect to your AI product over an HTTP API instead of WebRTC.
  </Card>

  <Card title="Phone Connection" icon="phone" href="/concepts/product/phone-connection">
    Reach your AI agent over the phone instead of WebRTC.
  </Card>

  <Card title="WebRTC Connection Service SDK" icon="tower-broadcast" href="/sdk/api/webrtc-connection/service">
    Manage WebRTC connections programmatically using the Python SDK.
  </Card>

  <Card title="Version" icon="code-branch" href="/concepts/product/version">
    Attach a WebRTC connection to a version for voice evaluation.
  </Card>
</CardGroup>