Pipecat Automated Testing

Overview

Test your Pipecat agents with automated session management. Cekura handles session creation and management automatically.

No-code
Code

Run tests directly from the frontend without writing code.

Configure Pipecat credentials

Go to your agent settings and configure Pipecat integration:

Required fields:

Provider: Select “Pipecat” as your voice integration provider.
Assistant ID: (Optional) Your Pipecat assistant identifier. If left empty, the system will use default assistant settings
Pipecat Cloud API Key: Your authentication key from Pipecat Cloud. This key authenticates requests to the Pipecat API and is required to create automated sessions. The key will override any API key specified in the agent settings if provided here.
Pipecat Agent Name: A descriptive name for your Pipecat agent (e.g., “my-agent”). This helps identify your agent in the Pipecat dashboard and logs.
Agent Configuration (JSON): Additional configuration passed to your Pipecat agent. This corresponds to the request body sent to the Pipecat start endpoint when creating a new session.
Room Properties (JSON): Configuration for the Daily.co room that will host your WebRTC session. These properties control room behavior and SIP settings. A minimal example is shown in the screenshot. See the Daily Room Configuration API for all available room properties and detailed options.

Run tests from frontend

In the Configure Run dialog, select WebRTC under Voice connections and click Run.

Cekura automatically:

Creates unique sessions for each scenario
Manages session lifecycle
Executes tests and cleans up resources

Greyed out connection options have not been configured in Agent Settings yet — set them up there to enable them.

View results

Results appear in your dashboard. Track test status, metrics, and conversation details in real-time.

Use the API to integrate Pipecat testing into your workflow.

Prerequisites

Configure Pipecat credentials in your agent settings:

Required fields:

Provider: Select “Pipecat” as your voice integration provider.
Assistant ID: (Optional) Your Pipecat assistant identifier. If left empty, the system will use default assistant settings
Pipecat Cloud API Key: Your authentication key from Pipecat Cloud. This key authenticates requests to the Pipecat API and is required to create automated sessions. The key will override any API key specified in the agent settings if provided here.
Pipecat Agent Name: A descriptive name for your Pipecat agent (e.g., “my-agent”). This helps identify your agent in the Pipecat dashboard and logs.
Agent Configuration (JSON): Additional configuration passed to your Pipecat agent. This corresponds to the request body sent to the Pipecat start endpoint when creating a new session.
Room Properties (JSON): Configuration for the Daily.co room that will host your WebRTC session. These properties control room behavior and SIP settings. A minimal example is shown in the screenshot. See the Daily Room Configuration API for all available room properties and detailed options.

Configuration Fields Reference

When setting up Pipecat integration, you’ll configure the following fields in your agent settings:

Core Settings

Field	Required	Description
Provider	Yes	Voice integration provider - select “Pipecat”
Assistant ID	No	Your Pipecat assistant identifier for routing requests

Pipecat Cloud Settings

Field	Required	Description
Pipecat Cloud API Key	Yes	Authentication key from Pipecat Cloud. Get your API key from the Pipecat dashboard under Settings → API Keys. This key enables Cekura to create and manage sessions on your behalf.
Pipecat Agent Name	Yes	Identifier for your agent (e.g., “my-agent”). Used in logs and the Pipecat dashboard.

Advanced Configuration

Field	Required	Description
Agent Configuration (JSON)	No	Request body for the Pipecat start endpoint. Configure LLM settings, voice parameters, prompts, and agent behavior.
Room Properties (JSON)	No	Daily.co room configuration controlling WebRTC session behavior, SIP settings, and room features.

API Endpoint

POST https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_pipecat_v2/

Authentication

Include your API key in the request header:

X-CEKURA-API-KEY: <YOUR_API_KEY>

Request Parameters

scenarios (array, required): Array of test configurationsEach scenario object contains:

scenario (number, required): Scenario ID

frequency (number, optional): Number of times to run each scenario. Defaults to 1 if not specified.

Examples

Single Run (cURL)

curl -X POST \
  'https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_pipecat_v2/' \
  -H 'X-CEKURA-API-KEY: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "scenarios": [
      {
        "scenario": 30
      }
    ],
    "frequency": 1
  }'

Multiple Runs (cURL)

curl -X POST \
  'https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_pipecat_v2/' \
  -H 'X-CEKURA-API-KEY: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "scenarios": [
      {
        "scenario": 30
      },
      {
        "scenario": 31
      }
    ],
    "frequency": 1
  }'

Python Example

import requests

API_KEY = "<YOUR_API_KEY>"
BASE_URL = "https://api.cekura.ai/test_framework"

headers = {
    "X-CEKURA-API-KEY": API_KEY,
    "Content-Type": "application/json",
}

payload = {
    "scenarios": [
        {
            "scenario": 30,
        },
        {
            "scenario": 31,
        },
    ],
    "frequency": 1,
}

resp = requests.post(
    f"{BASE_URL}/v1/scenarios/run_scenarios_pipecat_v2/",
    headers=headers,
    json=payload,
)
result = resp.json()
print(result)

Response

{
  "id": 17759,
  "name": "",
  "agent": 5,
  "status": "in_progress",
  "success_rate": 0.0,
  "run_as_text": false,
  "is_cronjob": false,
  "runs": [
    {
      "id": 39128,
      "status": "running",
      "scenario": 11735,
      "number": null,
      "inbound_number": "+18646190758",
      "scenario_name": "Health Check-in Outbound Call",
      "test_profile_data": null
    }
  ],
  "created_at": "2025-11-08T12:44:17.122269Z",
  "updated_at": "2025-11-08T12:44:17.122520Z"
}

Monitor Results

Poll for results using the List Runs with IDs API.

Accessing Test Profile Data in Your Agent

In the automated flow, Cekura creates the Pipecat session on your behalf. When a test profile is assigned to the scenario, Cekura merges the profile’s main_agent_variables section directly into the Agent Configuration JSON (SessionParams.data). Values in testing_agent_variables stay on Cekura’s simulated caller and are not sent to your agent.

Session Data Structure

Given a test profile with this sectioned information:

{
  "main_agent_variables": {
    "user_id": "U-42",
    "account_id": "ACC-12345"
  },
  "testing_agent_variables": {
    "customer_name": "John Doe",
    "story": "Calling about her latest statement"
  }
}

your agent’s SessionParams.data becomes:

{
  "your_existing_config_key": "value",
  "user_id": "U-42",
  "account_id": "ACC-12345"
}

Only main_agent_variables keys are flattened. customer_name / story are kept on the simulator. If a main_agent_variables key matches an existing key in the Agent Configuration, the test profile value takes precedence.

Accessing Test Profile Fields in Your Agent

Since main_agent_variables are top-level keys in session_data, access them directly:

async def main(session_data: dict):
    # main_agent_variables are merged directly into session_data
    user_id = session_data.get("user_id", "")
    account_id = session_data.get("account_id", "")

    # Use the variables to customize your agent behavior

Only main_agent_variables are flattened into your Agent Configuration JSON — never testing_agent_variables. Put any value your agent needs to read at call start (e.g., user_id, account_id) into main_agent_variables. Persona facts the simulated caller should use (e.g., customer_name, date_of_birth) belong in testing_agent_variables so they don’t leak into your agent’s config.

Key Terminology

Pipecat Cloud: The hosted platform for deploying and managing Pipecat agents. Get your API key at pipecat.daily.co
Daily.co: WebRTC infrastructure provider that powers Pipecat’s voice and video capabilities. See Daily docs
Room URL: The Daily.co WebRTC endpoint where the test session occurs
Meeting Token: Authentication credential for joining a Daily.co room
Agent Configuration: JSON payload sent to Pipecat’s start endpoint to configure agent behavior
Room Properties: Daily.co room settings that control session features and behavior

​Overview

​Prerequisites

​Configuration Fields Reference

​Core Settings

​Pipecat Cloud Settings

​Advanced Configuration

​API Endpoint

​Authentication

​Request Parameters

​Examples

​Single Run (cURL)

​Multiple Runs (cURL)

​Python Example

​Response

​Monitor Results

​Accessing Test Profile Data in Your Agent

​Session Data Structure

​Accessing Test Profile Fields in Your Agent

​Key Terminology

​Next Steps

Overview

Prerequisites

Configuration Fields Reference

Core Settings

Pipecat Cloud Settings

Advanced Configuration

API Endpoint

Authentication

Request Parameters

Examples

Single Run (cURL)

Multiple Runs (cURL)

Python Example

Response

Monitor Results

Accessing Test Profile Data in Your Agent

Session Data Structure

Accessing Test Profile Fields in Your Agent

Key Terminology

Next Steps