LiveKit

Parlot stays OpenTelemetry–first: agent telemetry uses OTLP and standard / Parlot semantic attributes. Session audio is stored in Cloudflare R2 via LiveKit Room Composite Egress; Parlot confirms uploads with lazy R2 HEAD reconcile when you open the session.

Session transcript, turns, waterfall, usage, and close outcome come from OTLP (agent parlotize()). Audio confirmation (audio_available) happens when you open GET /v1/sessions/:id and the object already exists in R2.

Get instrumentation working

Two steps are required for full Parlot behavior.

1. parlotize() at import (required)

Call before constructing AgentSession — patches AgentSession.__init__, sets up OTLP export to PARLOT_ENDPOINT, and installs turn/handoff/close event hooks.

from parlot.instrumentation.livekit import parlotize

parlotize("my-agent")

from livekit.agents import AgentSession, JobContext, WorkerOptions, cli


async def entrypoint(ctx: JobContext):
    await ctx.connect()

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

parlotize() builds a TracerProvider with an OTLP exporter, registers it with livekit.agents.telemetry, fetches GET /v1/telemetry/bootstrap (when PARLOT_API_KEY is set), patches JobContext.connect to refresh room metadata and start egress when recording is enabled, and auto-installs AgentSession event hooks (semantic/commit layer) plus span processing (pipeline/waterfall layer).

Session bootstrap runs on LiveKit agent_state_changed when the agent transitions initializing → listening (the Starting phase of AgentSession lifecycle). That mints one Parlot session.id, starts a parlot.session span for ingestion, and stamps platform.ref.* keys. Room metadata refresh and egress run after bootstrap (or immediately on JobContext.connect if bootstrap already completed). The session closes via the AgentSession close event.

agent_id is a required positional argument — a stable deployment identity stamped on session.agent_id. Pass version= for deployment version. Shared kwargs are documented in Python SDK Reference; LiveKit-only options (record, auto_escalate_sip, …) are on the Interactive API Reference. See also Concepts.

Reliable patterns for LiveKit job processes:

parlotize("restaurant-agent", version="0.1.0")

For per-tenant or per-region deploys without a code change, pass the id from your manifest:

import os

parlotize(os.environ["PARLOT_AGENT_ID"])

Pass version= when you want a real deployment label; otherwise Parlot stamps "unknown".

Canonical agent identity (LiveKit sources)

LiveKit voice currently uses conversation_id === session_id (1:1) as a placeholder until multi-session conversations are modeled.

Named worker dispatch (agent_name)

This is LiveKit’s dispatch name (which jobs are eligible for which rooms). It is separate from Parlot parlotize("…") / session.agent_id, which is the canonical product identity stamped on telemetry.

Prefer an explicit name on the RTC session entrypoint:

from livekit.agents import AgentServer, JobContext

server = AgentServer()


@server.rtc_session(agent_name="healthcare")
async def entrypoint(ctx: JobContext):
    await ctx.connect()
    ...

Why (LiveKit): without a name, the worker registers as the default (unnamed) agent and is eligible for automatic assignment into any room that requests an agent. Paths such as LiveKit WarmTransferTask create a second room (often {room}-human-agent for briefing). An unnamed worker will be auto-dispatched into that room and run your entrypoint again.

Why (Parlot): each LiveKit job bootstraps roughly one parlot.session. A second auto-dispatched job therefore creates a second Parlot session for the same caller journey (main room + transfer briefing), with its own turns and recording lifecycle. That is usually unwanted in the UI and can surface noisy teardown errors (engine is closed, failed to send session event) when the briefing room shuts down.

Keep playground, SIP dispatch rules, join tokens, and lk dispatch aligned with the same name (lk dispatch create --agent-name healthcare …, SIP room_config.agents with agent_name: healthcare). Local lk agent console / lk agent dev still work; Cloud and SIP must request the named agent explicitly. See the healthcare example README for a full WarmTransferTask setup.

2. await ctx.connect() before session.start() (required)

async def entrypoint(ctx: JobContext):
    await ctx.connect()

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

Without ctx.connect() you may still see basic telemetry if you pass room=ctx.room, but you will not get room audio recording or a reliable room_sid for UI linking.

Environment variables (agent)

Full env reference: Environment Variables. Shared parlotize() options: Python SDK Reference.

Recording policy (LiveKit)

Recording is on by default for new tenants (allowlist *). Precedence: job metadata → parlotize(record=…) → Settings → Recording via bootstrap:

• UI: Parlot → Settings → Recording — globs (default *), per-agent toggles for known deployments. Empty globs turns recording off org-wide for new agents.
• Code: parlotize(record=True), parlotize(record=False), or parlotize(record=["my-agent*"])
• Dispatch: job metadata { "record": true } or { "record": false }

Generative AI content capture (message bodies and tool payloads; default on) is shared across adapters — see Concepts → Generative AI content capture. LiveKit job metadata: { "capture_genai_content": true|false }.

Session application logs

Python logging from instrumented agents is captured on by default while a Parlot session is active (not print() / stdout). Rows appear on the session Logs tab.

Precedence (same ladder as recording; fallback is on):

job metadata capture_logs → parlotize(capture_logs=…) → Settings → Logs (bootstrap) → on

• UI: Parlot → Settings → Logs — globs (default *), min level (default INFO), per-agent toggles. Empty globs turns capture off org-wide.
• Code: parlotize(capture_logs=True|False) or parlotize(capture_logs=["my-agent*"], log_level="WARNING")
• Dispatch (LiveKit): job metadata { "capture_logs": true|false }
• Messages are stored as emitted (treat like stdout for PII). Missing bootstrap / old collectors still capture.

Errors in the session waterfall

Failed LLM and tool work is surfaced in spans_agent.error_flag at ingest. LiveKit stamps OpenTelemetry exception.type / exception.message on spans such as llm_request_run when a provider call fails; tool failures use lk.function_tool.is_error. The collector maps those signals (and OTLP span status ERROR) into error_flag and error_type on each operational span row.

Turn-level has_error is derived at query time — see Concepts.

Session recording

Recording uses Room Composite Egress (OGG, audio-only) to R2. Flow:

1. Agent calls POST /v1/recordings/upload-grant → JWT-minted temporary R2 credentials (scoped to {org}/sessions/{sessionId}/) + canonical r2://…/audio.ogg URI.
2. Agent starts egress (OGG → R2) using agent LIVEKIT_* credentials.
3. OTLP exports session.recording.audio_uri, session.recording.anchor_wall_ms, session.recording.egress_id with audio_available=false until confirmation. On egress failure, session.recording.webhook_error is stamped instead.
4. Opening GET /v1/sessions/:id runs R2 HEAD reconcile → audio_available=true when the object exists.

Setup checklist

1. LiveKit Cloud → Settings → Keys → create an API key with roomRecord (needed on the agent to start egress via LIVEKIT_*).
2. Parlot → Settings → API Keys — mint a key for the same org; set it as PARLOT_API_KEY on the agent.
3. New tenants record by default (Settings → Recording allowlist *). Clear the allowlist or use parlotize(record=False) / { "record": false } in job metadata to disable; use globs or per-agent toggles to narrow which agents record.

If recording stays “processing”

What gets exported

The conversation attribute contract is framework-agnostic (see Concepts). The LiveKit adapter (parlot-instrumentation-livekit) reads LiveKit Agents OTel spans in-process, stamps Parlot attributes from parlot.core.attrs, emits handoff spans as parlot.agent.handoff, and strips all lk.* keys before OTLP export (SanitizeVendorAttrsSpanExporter).

Native LiveKit → exported GenAI / voice names

LiveKit still creates vendor span names internally (llm_request, function_tool, …). Before OTLP export, Parlot remaps them to the shared vocabulary (OTel GenAI semconv v1.41 + voice). Pre-launch: no native-name export path.

When a span carries explicit agent.role, the collector prefers that value.

Span name → agent.stage (timeline labels)

Each operational span carries agent.stage (from the native LiveKit name before rename). UI labels combine role + stage — e.g. llm + run → LLM · API call. Nested LiveKit LLM spans all export as chat with distinct stages.

In events mode, trust committed conversation items for authoritative agent utterance text on parlot.turn.

Vendor attribute → Parlot attribute (export)

Turn metrics (LiveKit source → Parlot histogram)

Pipeline timing is read from native agent_turn / tts_* spans and stamped onto parlot.turn (and metrics) before those native turn spans are dropped from export.

LiveKit-native lk.agents.turn.* and lk.agents.usage.* metrics may still land in otel_metrics_raw but are not used by the Parlot pipeline.

Session close (parlot.session.close)

Primary emission: AgentSession.on("close") via event hooks.

AgentSession events (semantic / commit layer)

When parlotize() patches AgentSession, Parlot subscribes to LiveKit events for turn boundaries and session aggregates. Operational waterfall detail stays on OTel spans.

Span-based turn emission (user_turn / agent_turn → parlot.turn) is disabled once event hooks install (turn_source=events). Native turn spans are still observed to copy latency / STT confidence / media alignment onto parlot.turn, then dropped from export. Semantic session lifecycle (bootstrap, turns, close, tokens) does not depend on the job_entrypoint span.

Export allowlist (LiveKit)

Spans exported to Parlot (after rename): Conversation Contract (parlot.session, parlot.turn, parlot.session.close, parlot.agent.handoff), GenAI (chat / chat {model}, execute_tool {name}, invoke_agent), and voice (tts, stt, eou_detection, amd).

Human escalation

Semantics and role vocabulary (user / agent / human_rep) are in Concepts → Human escalation. Below are LiveKit-specific ways to signal a live rep.

Explicit call

from parlot.instrumentation.livekit import record_human_rep

record_human_rep("support_rep_jane", label="Jane")

SIP warm transfer (auto-detect)

If you use WarmTransferTask (or any flow that opens a second agent room), set a named LiveKit agent_name on @server.rtc_session so the briefing room does not auto-dispatch another copy of your worker and mint a duplicate Parlot session.

from parlot.instrumentation.livekit import parlotize

parlotize("my-agent", auto_escalate_sip=True)

Or match participant metadata:

parlotize(
    "my-agent",
    escalation_metadata_match={
        "type": "agent_transfer",
        "is_human": "true",
    }
)

Context manager around a dial

from parlot.instrumentation.livekit import human_escalation

async def transfer_to_support_desk(session, sip_uri):
    with human_escalation(label="L2 Support Queue"):
        await session.dial(sip_uri)

Custom metadata and refs

Semantics are in Concepts → Custom metadata and external references. Import the same helpers from the LiveKit package:

from parlot.instrumentation.livekit import (
    set_session_metadata,
    set_session_attribute,
    add_platform_ref,
)

set_session_metadata(order_id="12345", crm_ticket="TKT-9")
set_session_attribute("retry_count", 2)
add_platform_ref("crm_ticket", "TKT-9")
# optional framework= for your own IDs:
add_platform_ref("order_id", "ORD-100", framework="shopify")

Call after the session has started (agent_state_changed → listening). LiveKit room / job IDs are stamped automatically as platform.ref.* during session bootstrap.

LiveKit observability (OTEL): enabled vs disabled

This section describes what Parlot stores and surfaces when LiveKit Agents pipeline tracing is active vs when it is not. It is not about whether the agent calls parlot.parlotize() — Parlot instrumentation must stay on for any ingest.

Terminology

Session bootstrap and close no longer depend on job_entrypoint. Bootstrap runs on agent_state_changed when the agent transitions initializing → listening (AgentSession lifecycle); close runs on the AgentSession close event (events reference).

Empirical comparison (same agent, two local sessions)

These sessions exercised the hotel-receptionist agent against the same local stack; only LiveKit pipeline OTEL differed:

Both sessions received a full semantic session record and a non-empty waterfall. The clearest OTEL-on-only signal in this pair was end-to-end turn latency (turn.e2e_latency_s / turn.e2e_latency_ms), which is sourced from lk.e2e_latency on LiveKit agent_turn spans. Neither session populated non-zero turn.llm_ttft_ms, turn.tts_ttfb_ms, turn.transcription_delay_ms, or turn.eou_delay_ms (metrics rows existed but summed to zero).

Coverage matrix

*When parlot.parlotize() registers the tracer provider, LiveKit may still emit pipeline spans even if LiveKit Cloud observability is toggled off elsewhere. Treat “OTEL off” as no pipeline spans reaching Parlot, not merely disabling a cloud dashboard.

What Parlot can promise without LiveKit pipeline OTEL

With parlot.parlotize() only (events + Parlot OTLP, no LiveKit pipeline spans):

• Episode record — paste session id → read the call: turns, roles, text, close outcome, coarse usage, handoffs, intent label.
• Session list / search — metadata, end state, token totals, participant count.
• Evals on transcript — session-close workers can still score user turns from stored text.
• Recording — egress to R2 when PARLOT_API_KEY and recording policy are set; audio confirms via R2 reconcile when the session is opened.

Not available (or materially degraded) without pipeline spans:

• Expanded turn waterfall (LLM/TTS/tool timing tree) and span detail panel I/O.
• Turn-level latency charts beyond what ChatMessage.metrics provides on committed messages.
• STT quality, EOU, and AMD pipeline signals.
• Accurate has_error per turn and provider-level failure attribution.
• Audio segment bars synced to turns (media_segment_* stays at 0).
• Fleet graph and per-agent operational analytics.

Recommendation

• Debugging / SRE / latency work: keep LiveKit pipeline OTEL active and parlot.parlotize() on. The waterfall, error attribution, and latency histograms depend on it.
• Transcript-only / compliance / eval workflows: parlot.parlotize() + AgentSession events are sufficient for the semantic session record; do not expect a populated debugger waterfall.
• Never disable all tracing if you still call parlot.parlotize() — Parlot replaces the provider. “Turn off OTEL” should mean disabling LiveKit’s pipeline span emission or not routing it to Parlot, not removing Parlot instrumentation.

Mental model

Two layers: LiveKit events commit conversational semantics (turns, handoffs, usage, close). LiveKit OTel spans carry the pipeline waterfall (LLM, TTS, tools, AMD, EOU). The adapter maps both to Parlot OTLP keys; the collector stays framework-agnostic.

For platform env (R2_ACCOUNT_ID, R2_CONTENT_BUCKET, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY on collector + API, DATABASE_URL), see the platform local E2E runbook. R2 key scheme: {tenant_id}/sessions/{session_id}/audio.ogg.