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

# Roark

> Call analytics and observability for Pipecat voice agents — capture call lifecycle, transcripts, tool calls, and recordings

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="roarkhq" maintainerUrl="https://github.com/roarkhq" repo="https://github.com/roarkhq/sdk-roark-analytics-python-pipecat" />

## Overview

`RoarkObserver` is a [Roark](https://roark.ai) analytics observer for Pipecat.
Drop one observer into your pipeline and Roark captures the call lifecycle,
transcripts, tool calls, and a stereo audio recording — no other code changes
required.

<CardGroup cols={2}>
  <Card title="Source Repository" icon="github" href="https://github.com/roarkhq/sdk-roark-analytics-python-pipecat">
    Source code, examples, and issues for the Roark integration
  </Card>

  <Card title="PyPI Package" icon="cube" href="https://pypi.org/project/pipecat-roark/">
    The `pipecat-roark` package on PyPI
  </Card>

  <Card title="Roark" icon="book" href="https://roark.ai">
    Learn more about Roark call analytics
  </Card>

  <Card title="Documentation" icon="book" href="https://docs.roark.ai/documentation/integrations/pipecat">
    Roark's full setup guide for the Pipecat integration
  </Card>
</CardGroup>

## Installation

This is a community-maintained package distributed separately from `pipecat-ai`:

```bash theme={null}
pip install pipecat-roark
```

## Prerequisites

### Roark Account Setup

Before using the Roark observer, you need:

1. **Roark Account**: Sign up at [Roark](https://roark.ai)
2. **API Key**: Create one on the API keys page in your Roark project

### Required Environment Variables

* `ROARK_API_KEY`: Your Roark API key (e.g. `rk_live_...`). It can also be
  passed directly as the `api_key` argument to `RoarkObserver`.

## Configuration

`RoarkObserver` is configured through its constructor:

<ParamField path="api_key" type="str" required>
  Roark API key (e.g. `rk_live_...`). Sent as a bearer token to the Roark API.
</ParamField>

<ParamField path="agent_id" type="str" required>
  Customer-stable agent identifier. Roark lazy-registers the agent the first
  time it sees a given `agent_id`.
</ParamField>

<ParamField path="agent_name" type="str" default="None">
  Display name for the agent on the Roark dashboard.
</ParamField>

<ParamField path="agent_prompt" type="str" default="None">
  System prompt for the agent. Persisted as the agent's prompt revision.
</ParamField>

<ParamField path="audio_buffer_processor" type="AudioBufferProcessor" default="None">
  Bring-your-own `AudioBufferProcessor` to control sample rate, channels, or
  buffer size. If omitted, the observer creates a default (stereo, \~256 KB
  chunks; sample rate adopted from the pipeline's `StartFrame`) accessible via
  `observer.audio_processor`.
</ParamField>

<ParamField path="pipecat_call_id" type="str" default="random UUID">
  Stable call identifier carried on Roark records as `pipecatCallId`. Pass the
  same value to `PipelineTask(conversation_id=...)` when OpenTelemetry tracing
  is enabled to correlate Roark calls with traces.
</ParamField>

## Setup

Drop `RoarkObserver` into your pipeline's `observers=[...]` list. Splice the
auto-created `roark.audio_processor` **after `transport.output()`** so it sees
the bot's audio post-TTS:

```python theme={null}
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat_roark import RoarkObserver

roark = RoarkObserver(
    api_key="rk_live_...",
    agent_id="support-bot-v3",
    agent_name="Support Bot v3",
    agent_prompt=SYSTEM_PROMPT,
)

pipeline = Pipeline([
    transport.input(), stt, context_aggregator.user(), llm, tts,
    transport.output(),
    roark.audio_processor,          # after transport.output() — L=user, R=bot
    context_aggregator.assistant(),
])

task = PipelineTask(pipeline, params=PipelineParams(observers=[roark]))
```

That's it — transcripts, tool calls, and the stereo recording flow to Roark
automatically. The observer never raises into the pipeline; failures are logged
and swallowed so your call keeps running even if Roark is unreachable.

<Note>
  `RoarkObserver` is runtime-agnostic — the same observer wiring works whether
  your Pipecat agent runs self-hosted or is deployed to Pipecat Cloud. See the
  [source
  repository](https://github.com/roarkhq/sdk-roark-analytics-python-pipecat) for
  advanced topics such as bringing your own `AudioBufferProcessor`, handling
  WebRTC disconnects with `aflush()`, and correlating with OpenTelemetry
  tracing.
</Note>

## Compatibility

Tested with Pipecat v0.0.108 (compatible with `>= 0.0.40, < 1`) and Python
3.10+. Check the [source
repository](https://github.com/roarkhq/sdk-roark-analytics-python-pipecat) for
the latest tested version and changelog.