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

# Pipecat

> Instrument a Pipecat voice agent with the roark_analytics[pipecat] observer, self-hosted or on Pipecat Cloud

<Badge color="green">Live monitoring</Badge> <Badge color="green">Voice simulations</Badge> <Badge color="gray" stroke>Chat simulations</Badge>

## Overview

The Pipecat integration monitors voice agents built on the open-source [Pipecat](https://github.com/pipecat-ai/pipecat) framework. Drop the [`roark_analytics[pipecat]`](https://pypi.org/project/roark-analytics/) 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.

<Note>
  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.
</Note>

***

## 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](#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

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
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`.

```python theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
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.

<Note>
  `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.
</Note>

### Step 4: Verify the connection

Place a call to your agent. Within a few moments it appears in [Call History](/documentation/observability/live-monitoring) with its transcript, recording, and any tool calls, then gets scored by your active [collectors](/documentation/metrics/metric-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](/documentation/simulation-testing/overview) against a Pipecat agent, Roark joins it over [WebRTC](/documentation/simulation-testing/webrtc). Add the simulation configuration when you connect the integration (or edit it later). This is the one part that differs by deployment.

<Tabs>
  <Tab title="Self-hosted (SmallWebRTC)">
    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.
  </Tab>

  <Tab title="Pipecat Cloud (Daily)">
    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.
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Run a simulation" icon="play" href="/documentation/simulation-testing/overview">
    Test your Pipecat agent with synthetic callers over WebRTC
  </Card>

  <Card title="Set up collectors" icon="radar" href="/documentation/metrics/metric-collectors">
    Score every incoming call automatically
  </Card>
</CardGroup>