Skip to main content

​
Overview

RoarkObserver is a Roark 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.

Source Repository

Source code, examples, and issues for the Roark integration

PyPI Package

The pipecat-roark package on PyPI

Roark

Learn more about Roark call analytics

Documentation

Roark’s full setup guide for the Pipecat integration

​
Installation

This is a community-maintained package distributed separately from pipecat-ai: 
pip install pipecat-roark

​
Prerequisites

​
Roark Account Setup

Before using the Roark observer, you need:
  1. Roark Account: Sign up at Roark
  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:
​
api_key
str
required
Roark API key (e.g. rk_live_...). Sent as a bearer token to the Roark API.
​
agent_id
str
required
Customer-stable agent identifier. Roark lazy-registers the agent the first time it sees a given agent_id.
​
agent_name
str
default:"None"
Display name for the agent on the Roark dashboard.
​
agent_prompt
str
default:"None"
System prompt for the agent. Persisted as the agent’s prompt revision.
​
audio_buffer_processor
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.
​
pipecat_call_id
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.

​
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: 
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.
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 for advanced topics such as bringing your own AudioBufferProcessor, handling WebRTC disconnects with aflush(), and correlating with OpenTelemetry tracing.

​
Compatibility

Tested with Pipecat v0.0.108 (compatible with >= 0.0.40, < 1) and Python 3.10+. Check the source repository for the latest tested version and changelog.