LiveKit

The LiveKit integration records an AgentSession and can wrap the existing STT and TTS providers to capture their inputs, outputs, timing, metadata, and audio.

Requirements

• Python 3.10 or later
• an existing working LiveKit Agents application
• LiveKit Agents 1.x

Install the tracing integration without replacing the provider packages already used by the application:

pip install "noveum-trace[livekit]"

Initialize Noveum Trace

Initialize once when the worker starts:

import os

import noveum_trace

noveum_trace.init(
    api_key=os.environ["NOVEUM_API_KEY"],
    project=os.environ["NOVEUM_PROJECT"],
    environment=os.getenv("NOVEUM_ENVIRONMENT", "production"),
    service_version=os.environ["NOVEUM_SERVICE_VERSION"],
)

Instrument a session

Apply the wrappers to the providers the application already creates. Pass the extracted job context into both wrappers so room, participant, and job metadata are attached to their spans.

from livekit.agents import AgentSession, JobContext
from noveum_trace.integrations.livekit import (
    LiveKitSTTWrapper,
    LiveKitTTSWrapper,
    extract_job_context,
    setup_livekit_tracing,
)


async def entrypoint(ctx: JobContext):
    job_metadata = await extract_job_context(ctx)
    session_id = ctx.job.id

    traced_stt = LiveKitSTTWrapper(
        stt=stt,
        session_id=session_id,
        job_context=job_metadata,
    )
    traced_tts = LiveKitTTSWrapper(
        tts=tts,
        session_id=session_id,
        job_context=job_metadata,
    )

    session = AgentSession(
        stt=traced_stt,
        llm=llm,
        tts=traced_tts,
    )
    setup_livekit_tracing(session, record=False)
    await session.start(agent=agent, room=ctx.room)

Use the application's existing stt, llm, tts, and agent objects. The tracing patch should not change provider or agent behavior.

Choose audio capture deliberately

Use session tracing without the STT and TTS wrappers when no utterance audio may be stored. Review transcripts, model messages, tool arguments, and other session payloads separately; disabling audio does not redact text.

What is captured

Depending on the components and capture choices, one session can include:

• an agent-session trace with lifecycle and conversation events
• STT recognition or stream spans from LiveKitSTTWrapper
• TTS synthesis or stream spans from LiveKitTTSWrapper
• model and tool activity emitted by the session
• optional full-conversation recording
• job, room, participant, and session correlation data

Provider-specific values are present only when the provider emits them. Do not assume confidence, quality, cost, or usage fields exist until a representative trace confirms them.

Verify the integration

Run one complete call and confirm:

1. the session produces one connected trace
2. STT, model, tool, and TTS operations appear in execution order
3. the final agent response and terminal status are present
4. job context appears on wrapped STT and TTS operations
5. audio is present only at the surfaces you enabled
6. handled failures contain the expected error details

For automated conversations, configure NovaSynth. NovaSynth can execute and evaluate a synthetic session without production tracing; this integration adds production observability and richer application evidence.

Source

• LiveKit integration source