Pipecat

Live monitoring Voice simulations Chat simulations

Overview

The Pipecat integration monitors voice agents built on the open-source Pipecat framework. Drop the roark_analytics[pipecat] observer into your pipeline and call lifecycle, transcripts, tool calls, and a recording are forwarded to Roark automatically. The same observer works whether you run Pipecat yourself or on Pipecat Cloud: the wiring is identical, so you pick your deployment when you connect the integration and instrument your pipeline once. The observer talks only to Roark’s own API; it never changes how your agent runs.

Deployment only matters for simulations. Monitoring (importing your production calls) is identical for self-hosted and Pipecat Cloud. If you only want monitoring, you can skip the simulation configuration below.

Prerequisites

Before setting up the integration, ensure you have:

A Pipecat voice agent (running on your own infrastructure or on Pipecat Cloud).
Python 3.10 or newer.
Access to your Roark project’s Agents page to connect the integration and mint an API key.

Setup Instructions

Step 1: Connect the integration in Roark

Go to Agents, click Connect Agent, choose Existing Platform, and pick Pipecat. Select the Self-hosted or Pipecat Cloud tab, give the integration a name, and (optionally) fill in the simulation configuration for that deployment (see Simulations below). On connect, Roark mints a project API key bound to this integration and shows it once. Copy it now: it’s what the observer authenticates with, and Roark can’t show it again.

Step 2: Install the observer

pip install "roark_analytics[pipecat]"

Step 3: Wire the observer into your pipeline

Add RoarkObserver to your Pipecat pipeline. Two rules:

Put roark.audio_processor after transport.output() so the observer captures the bot’s post-TTS audio.
Pass observers=[roark] on PipelineParams.

from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat_roark import RoarkObserver

SYSTEM_PROMPT = "You are a friendly voice assistant. Keep replies short."

async def bot(runner_args):
    roark = RoarkObserver(
        api_key="<YOUR_ROARK_API_KEY>",
        agent_id="pipecat-demo",
        agent_name="Pipecat Demo",
        agent_prompt=SYSTEM_PROMPT,
        runner_args=runner_args,
    )

    # roark.audio_processor must sit AFTER transport.output() so the bot channel
    # captures post-TTS audio. The observer is wired via PipelineParams.observers.
    pipeline = Pipeline(
        [
            transport.input(),
            stt,
            context_aggregator.user(),
            llm,
            tts,
            transport.output(),
            roark.audio_processor,
            context_aggregator.assistant(),
        ]
    )

    task = PipelineTask(
        pipeline,
        params=PipelineParams(
            enable_metrics=True,
            enable_usage_metrics=True,
            observers=[roark],
        ),
    )

    runner = PipelineRunner(handle_sigint=runner_args.handle_sigint)
    await runner.run(task)

The observer authenticates with the key from Step 1, sent as the x-roark-api-key header. Rather than hard-coding it, read it from the environment (api_key=os.environ["ROARK_API_KEY"]). On Pipecat Cloud, set ROARK_API_KEY as a deployment secret.

agent_id and agent_name identify the agent in Roark. Agents are registered automatically on the first observed call, and agent_prompt is tracked as a prompt revision, so prompt changes show up in Roark over time.

Step 4: Verify the connection

Place a call to your agent. Within a few moments it appears in Call History with its transcript, recording, and any tool calls, then gets scored by your active collectors.

How It Works

The observer POSTs call lifecycle events (call-started, call-ended) to Roark’s API, authenticated by your integration-bound key. Audio is streamed as chunks to Roark-issued presigned URLs and assembled into a recording when the call ends. Transcript and tool calls are sent in Pipecat’s native format and mapped to Roark’s model server-side. Because the key is bound to the integration, every call is attributed to the right integration and agent with no extra configuration.

What Gets Synced

Calls: lifecycle, timing, and metadata for each conversation.
Recording: the mixed audio, assembled from the streamed chunks.
Transcript: turn-by-turn, from Pipecat’s context messages.
Tool calls: function invocations captured during the call.
Agent + prompt: lazily registered from agent_id / agent_name, with agent_prompt tracked as a revision.

Simulations

To run simulations against a Pipecat agent, Roark joins it over WebRTC. Add the simulation configuration when you connect the integration (or edit it later). This is the one part that differs by deployment.

Self-hosted (SmallWebRTC)
Pipecat Cloud (Daily)

Roark reaches your agent through its SmallWebRTC signaling endpoint.

Field	Description
Signaling URL	Your SmallWebRTC offer endpoint. Roark POSTs an SDP offer here (`http(s)` or `ws(s)`).
Auth token	Optional bearer token for the signaling server. Stored encrypted.
Append agent ID	Append each synced agent’s id as a URL path segment, so one host can route to many bots. On by default.

Roark creates a WebRTC simulation endpoint for each synced agent automatically.

Roark starts a session through Pipecat Cloud, which runs your agent over Daily.

Field	Description
Public API key	Your Pipecat Cloud public API key, used to start sessions. Stored encrypted.
Start body	Optional JSON forwarded as the agent `body` on the Pipecat Cloud `/start` request.
Room properties	Optional JSON forwarded as the Daily `dailyRoomProperties`.

The Pipecat Cloud start URL is derived from each synced agent’s name (its Pipecat Cloud deployment name), so there’s nothing else to configure per agent.

Getting Started

Simulations

Observability

Metrics

Config as Code

Recipes

Integrations

Enterprise

SDKs & Developer Tools

Resources

Overview

Prerequisites

Setup Instructions

Step 1: Connect the integration in Roark

Step 2: Install the observer

Step 3: Wire the observer into your pipeline

Step 4: Verify the connection

How It Works

What Gets Synced

Simulations

Next Steps

Run a simulation

Set up collectors

​Overview

​Prerequisites

​Setup Instructions

​Step 1: Connect the integration in Roark

​Step 2: Install the observer

​Step 3: Wire the observer into your pipeline

​Step 4: Verify the connection

​How It Works

​What Gets Synced

​Simulations

​Next Steps

Run a simulation

Set up collectors

Overview

Prerequisites

Setup Instructions

Step 1: Connect the integration in Roark

Step 2: Install the observer

Step 3: Wire the observer into your pipeline

Step 4: Verify the connection

How It Works

What Gets Synced

Simulations

Next Steps