[David Elner (delner)]

Add LiveKit Python cascade tracing and recording

Adds end-to-end voice traces for LiveKit cascade sessions, including user speech, transcription, model responses, tools and agent speech. When audio recording is opted-in, it is linked to the traces.

Opt-in to the audio you want to capture:

export BRAINTRUST_CAPTURE_USER_AUDIO_ATTACHMENTS=true
export BRAINTRUST_CAPTURE_AGENT_AUDIO_ATTACHMENTS=true

Call setup in each worker before starting its LiveKit session:

import braintrust
from braintrust.integrations.livekit_agents import setup_livekit_agents

braintrust.init_logger(project="voice-agent")
setup_livekit_agents()

With braintrust-audio installed, recordings use Opus/Ogg by default. SDK auto-instrumentation also enables the integration.

A tool-using reply produces a trace like:

session                         ← recording attachments
├─ user_turn
│  ├─ user_speech
│  └─ stt
└─ agent_turn
   ├─ llm_response
   ├─ lookup_order
   ├─ llm_response              ← tool continuation
   ├─ tts
   └─ agent_speech              ← confirmed playback

See the runnable cascade example.

Design

flowchart LR
    L[LiveKit framework hooks] --> T[Session / turn / operation spans]
    L --> P[Consumed input + confirmed playback]
    P --> R[Common recorder + optional codecs]
    R --> A[Session audio attachments]

Loading

• Opt-in audio recording flags and respect of LiveKit PII flags avoid unwanted capture/export of data.
• On shutdown remaining recording audio/data is flushed.

[David Elner (delner)]

First pass on implementation, may require more refactoring to get the design/behavior right.