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

# Pipecat Cloud

> Connect your Pipecat Cloud agent to Coval to run Voice AI simulations

## Overview

The Pipecat Cloud connection lets you run Coval simulations against agents hosted on [Pipecat Cloud](https://docs.pipecat.daily.co). Once connected, Coval can automatically call your Pipecat agent, simulate realistic conversations, and evaluate its performance — no manual testing required.

## Configuration Requirements

### Agent Name

* **Field**: `agent_name`
* **Type**: String (required)
* **Purpose**: The name of the Pipecat Cloud agent that Coval will call during simulations
* **Format**: Must exactly match the agent name in your Pipecat Cloud dashboard
* **Example**: `"customer-service-agent"`, `"sales-assistant"`

### Pipecat API Key

* **Field**: `pipecat_api_key`
* **Type**: String (required)
* **Purpose**: Authentication key that allows Coval to connect to your Pipecat Cloud agent
* **Format**: Valid API key string from your Pipecat account
* **Security**: Stored encrypted and handled securely
* **Example**: `"pk_live_abc123def456..."`

### Custom Data

* **Field**: `custom_data`
* **Type**: String (optional)
* **Purpose**: Additional context passed to your Pipecat agent at the start of each simulation
* **Format**: Valid JSON string
* **Use Cases**: Agent-specific parameters, session context, custom settings
* **Example**: `{"department": "support", "language": "en", "priority": "high"}`

## Setup Instructions

1. **Deploy your agent to Pipecat Cloud**
   * Follow the [Pipecat Cloud Quickstart](https://docs.pipecat.daily.co/quickstart) to deploy your agent
   * Confirm your agent is listed in the Pipecat Cloud dashboard

2. **Connect it to Coval**
   * Go to [app.coval.dev/coval/agents/create](https://app.coval.dev/coval/agents/create)
   * Enter the exact agent name as it appears in Pipecat Cloud
   * Input your Pipecat API key
   * Add any required custom data in JSON format

3. **Run a simulation**
   * Create a test set with scenarios for your agent
   * Launch a simulation to verify the connection works end-to-end

## How Simulations Work

When you launch a simulation, Coval:

1. Authenticates with Pipecat Cloud using your API key
2. Starts a session with your specified agent (along with any custom data)
3. Simulates a realistic voice conversation using your test set and persona configuration
4. Records the full interaction and runs your configured evaluation metrics

## Troubleshooting

**Common Issues:**

* **Authentication Failures**: Verify your Pipecat API key is valid and has the correct permissions
* **Invalid Custom Data**: Ensure the JSON format is valid