LiveKit (self-hosted)

Live monitoring Voice simulations Chat simulations

Overview

The self-hosted LiveKit integration monitors voice agents built on the open-source LiveKit Agents framework that run against your own LiveKit server. Drop the roark-analytics[livekit] helper into your agent entrypoint and call lifecycle, transcripts, tool calls, and a recording are forwarded to Roark automatically — no other code changes required. The SDK talks only to Roark’s own API; it never connects to your LiveKit server.

Using LiveKit Cloud? You can use this SDK there too, but the dashboard-managed webhook integration is usually simpler — see LiveKit Cloud.

Prerequisites

A LiveKit Agents worker (Python 3.10+, livekit-agents 1.x)
Your own LiveKit server
A Roark API key with WRITE scope (generate one)

Setup Instructions

Step 1: Install the SDK

pip install "roark-analytics[livekit]"

Step 2: Configure your API key

The only setting you need to provide is your Roark API key.

.env

# Roark API key — create one on the API keys page in your Roark project.
ROARK_API_KEY=rk_live_replace_me

Variable	Required	Purpose
`ROARK_API_KEY`	Yes	Roark API key with WRITE scope. Pass it to the helper as `api_key=`.
`ROARK_OBSERVABILITY_ENABLED`	No	Set to `false` to make `observe_session` a no-op. See Kill switch.

Step 3: Wire `observe_session` into your entrypoint

Call observe_session(...) before session.start() so the audio taps are installed before the session begins streaming frames. That single call wires up everything:

import os

from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import cartesia, openai, silero, speechmatics

from roark_analytics_python_livekit import observe_session

SYSTEM_PROMPT = "You are a friendly voice assistant. Keep replies short — they are spoken aloud."


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


async def entrypoint(ctx: JobContext) -> None:
    # Connect first — Roark keys the call on the LiveKit room sid (RM_…),
    # which is also what links OpenTelemetry traces to the call.
    await ctx.connect()

    session = AgentSession(
        stt=speechmatics.STT(),
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=cartesia.TTS(),
        vad=silero.VAD.load(),
    )

    # --- Roark analytics ---------------------------------------------------
    # Must be called BEFORE session.start(). Failures are logged and
    # swallowed — your agent keeps running even if Roark is unreachable.
    await observe_session(
        ctx,
        session,
        api_key=os.environ["ROARK_API_KEY"],
        agent_id="support-bot-v1",
        agent_name="Support Bot",
        agent_prompt=SYSTEM_PROMPT,
    )
    # -----------------------------------------------------------------------

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


if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))

That’s the full integration — agent registration, transcripts, tool calls, and the recording are all handled by the helper.

Argument	Required	Description
`ctx`	Yes	The `JobContext` passed to your agent entrypoint.
`session`	Yes	The `AgentSession` you’re about to `start()`.
`api_key`	Yes	Your Roark API key (WRITE scope).
`agent_id`	Yes	Stable, customer-defined agent identifier. Used for lazy registration.
`agent_name`	No	Display name shown in the Roark dashboard.
`agent_prompt`	No	System prompt — persisted as the agent’s prompt revision, so changes are tracked over time.
`**metadata`	No	Free-form metadata forwarded on `call-started` for Roark-side correlation.

Step 4: Verify the connection

Run your worker against your LiveKit server and place a test call:

python agent.py dev

As the call runs you should see Roark log lines, then the recording upload begin after a few seconds of audio:

tapping user audio input (...)
tapping agent audio output (...)
call-started: ...

Within a few seconds you should also see, in your Roark dashboard:

The agent appear under the LiveKit source filter
The call appear in the calls table with status In Progress
After the call ends — the transcript, tool invocations, and recording attached to the call

How It Works

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

Phase	Source	What’s captured
Session start	`JobContext.connect()`	`call-started`, keyed on the LiveKit room sid (`RM_…`). Agent is lazy-registered the first time Roark sees an `agent_id`.
Transcripts	`conversation_item_added`	Message role + content, for both user and assistant turns.
Tool calls	`function_tools_executed`	Paired `tool_call` / `tool_result` records, keyed by `tool_call_id`.
Recording	Taps on `session.input.audio` (user) + `session.output.audio` (agent)	Audio streamed to Roark during the call.
Session end	`ctx.add_shutdown_callback(...)`	Flushes pending state, drains in-flight uploads, POSTs `call-ended`.

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

What Gets Synced

Calls — Lifecycle with timing and end reason
Agents — Lazy-registered on first sight using the agent_id / agent_name you pass
Prompts — System prompt captured at call start as a prompt revision
Transcripts — Per-turn messages with role, content, and timestamp
Tool Invocations — Tool call IDs, names, JSON arguments, and results
Recordings — Audio recording of the call

Roark only sees what the helper forwards. If you remove observe_session from a worker — or set ROARK_OBSERVABILITY_ENABLED=false — no data flows for those calls.

Agent Management

LiveKit agents are lazy-registered the first time the helper reports them:

The first call-started event with a new agent_id creates the agent in Roark
Subsequent events update the agent’s name and prompt if they change
These agents appear on the agents page under the LiveKit source filter

Once an agent exists, it can be used in simulations, run plans, and agent reports just like agents from any other provider.

Kill Switch

Disable instrumentation at runtime without touching code. Set ROARK_OBSERVABILITY_ENABLED=false to make observe_session a no-op (it returns None). Values treated as off: false, 0, no, off (case-insensitive); anything else (or the variable being absent) keeps it enabled.

Troubleshooting

Calls aren't finalizing on Roark

The helper registers a shutdown callback on the JobContext, which fires when LiveKit ends the job. If your transport tears down without firing the hook, call await state.aflush(reason="...") explicitly from your own disconnect handler — aflush() is idempotent, so the normal shutdown path will no-op if both fire.

state = await observe_session(ctx, session, api_key=..., agent_id=...)
# ... later, from your disconnect handler:
await state.aflush(reason="client-disconnected")

Transcripts arrive empty

Transcripts come from the conversation_item_added event on AgentSession. If you use a custom pipeline that bypasses AgentSession.start(room=…, agent=…), that event may never fire — verify by adding your own session.on("conversation_item_added", print) listener.

Recording is missing one side

The user side is tapped from session.input.audio; the agent side from session.output.audio. Because the taps are installed by observe_session, it must be called before session.start(). Check worker logs for the tapping user audio input / tapping agent audio output lines — if one is missing, that side will be silent on the merged recording.

No calls or recordings reaching Roark

Confirm api_key is a WRITE-scope key and that ROARK_OBSERVABILITY_ENABLED is not set to a falsy value.

Next Steps

Enable Tracing

Send OpenTelemetry traces — they auto-link to the call via the room sid

Run Simulations

Test your LiveKit agents

Configure Evaluators

Set up evaluation criteria

LiveKit Cloud

Use the dashboard-managed webhook integration instead

Getting Started

Observability

Metrics

Simulations

Recipes

Integrations

SDKs & Libraries

Resources

LiveKit (self-hosted)

Overview

Prerequisites

Setup Instructions

Step 1: Install the SDK

Step 2: Configure your API key

Step 3: Wire `observe_session` into your entrypoint

Step 4: Verify the connection

How It Works

What Gets Synced

Agent Management

Kill Switch

Troubleshooting

Next Steps

Enable Tracing

Run Simulations

Configure Evaluators

LiveKit Cloud

​Overview

​Prerequisites

​Setup Instructions

​Step 1: Install the SDK

​Step 2: Configure your API key

​Step 3: Wire observe_session into your entrypoint

​Step 4: Verify the connection

​How It Works

​What Gets Synced

​Agent Management

​Kill Switch

​Troubleshooting

​Next Steps

Enable Tracing

Run Simulations

Configure Evaluators

LiveKit Cloud

Overview

Prerequisites

Setup Instructions

Step 1: Install the SDK

Step 2: Configure your API key

Step 3: Wire `observe_session` into your entrypoint

Step 4: Verify the connection

How It Works

What Gets Synced

Agent Management

Kill Switch

Troubleshooting

Next Steps