roark-analytics-python-livekit

A Roark analytics integration for LiveKit Agents. Drop one helper into your agent entrypoint — Roark captures call lifecycle, transcripts, tool calls, metrics, and a stereo audio recording. No other code changes required.

• Tested with livekit-agents 1.x
• Python 3.10+
• Built for self-hosted LiveKit — works against your own livekit-server and in local console mode

Maintained by Roark. File issues at https://github.com/roarkhq/sdk-roark-analytics-python-livekit/issues.

Contents

• Quick start
• How it works
• Examples
• Kill switches
• Troubleshooting
• Configuration reference
• Development
• License

Quick start

1. Install

pip install roark-analytics-python-livekit

2. Configure

Set one env var:

ROARK_API_KEY=rk_live_...

The Roark API key is all you configure — the helpers know their own service endpoints.

3. Wire observe_session

from livekit.agents import Agent, AgentSession, JobContext
from roark_analytics_python_livekit import observe_session

SYSTEM_PROMPT = "You are a friendly voice assistant."

class Assistant(Agent):
    def __init__(self):
        super().__init__(instructions=SYSTEM_PROMPT)

async def entrypoint(ctx: JobContext):
    # Connect before observe_session: the room sid (used as the call id) is only
    # available once connected.
    await ctx.connect()

    session = AgentSession(stt=..., llm=..., tts=...)

    await observe_session(
        ctx, session,
        api_key="rk_live_...",
        agent_id="support-bot-v3",
        agent_name="Support Bot v3",
        agent_prompt=SYSTEM_PROMPT,
    )

    await session.start(room=ctx.room, agent=Assistant())

That's it — transcripts, tool calls, metrics, and the stereo recording flow to Roark automatically.

How it works

The helper subscribes to the standard AgentSession event surface and ships a compact event timeline to Roark:

Failures are logged and swallowed — the helpers never raise into the session. Your agent keeps running even if Roark is unreachable.

Examples

A complete, runnable self-hosted example ships in examples/ — a uv project with a Roark-instrumented support agent plus a short README. The simplest way to try it is local console mode (mic + speakers, no LiveKit server or browser needed):

cd examples
uv sync
cp .env.example .env      # fill in provider keys + ROARK_API_KEY
uv run --env-file .env agent.py console

See examples/README.md for local-server mode (a self-hosted livekit-server + a room client). Everything runs on your own machine — no LiveKit Cloud.

Kill switches

Use these env vars to disable Roark instrumentation at runtime without touching code:

Treated as off: false, 0, no, off (case-insensitive). Anything else (including the variable being absent) keeps the feature enabled.

Troubleshooting

Configuration reference

Development

pip install -e ".[dev]"
pytest
ruff check .

License

MIT — see LICENSE.