LiveKit Integration Overview

Noveum Trace provides seamless integration with LiveKit voice agents, enabling you to trace speech-to-text (STT), text-to-speech (TTS), and agent interactions in real-time voice applications.

What You Get

• STT Tracing: Automatic tracing of speech-to-text operations with Deepgram, AssemblyAI, and other providers
• TTS Tracing: Track text-to-speech generation with Cartesia, ElevenLabs, and other providers
• Agent Session Tracing: Monitor complete voice agent sessions and conversations
• Audio Metrics: Track latency, audio duration, and quality metrics
• Automatic Integration: Minimal code changes with wrapper pattern

Requirements

• Python 3.10+ (required by livekit-agents)
• livekit >= 1.0.19 and livekit-agents >= 1.0.0 (pulled in by the [livekit] extra)
• A Noveum API key and project

Installation

pip install "noveum-trace[livekit]"
pip install "livekit-plugins-deepgram" "livekit-plugins-cartesia" "livekit-plugins-openai"  # or your preferred providers

Quick Start

Wrap your STT/TTS providers with Noveum Trace wrappers:

import os
import noveum_trace
from noveum_trace.integrations.livekit import (
    LiveKitSTTWrapper,
    LiveKitTTSWrapper,
    setup_livekit_tracing,
    extract_job_context
)
from livekit.agents import Agent, AgentSession, JobContext
from livekit.plugins import deepgram, cartesia, openai

# Initialize Noveum Trace
noveum_trace.init(
    api_key=os.getenv("NOVEUM_API_KEY"),
    project="voice-agent"
)

# Define your agent (see basic-agent guide for advanced examples)
class VoiceAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful voice assistant."
        )

async def entrypoint(ctx: JobContext):
    session_id = ctx.job.id
    
    # Extract JobContext metadata to enrich traces
    job_metadata = await extract_job_context(ctx)
    
    # Wrap STT provider
    traced_stt = LiveKitSTTWrapper(
        stt=deepgram.STT(model="nova-2"),
        session_id=session_id
    )
    
    # Wrap TTS provider
    traced_tts = LiveKitTTSWrapper(
        tts=cartesia.TTS(model="sonic-english"),
        session_id=session_id
    )
    
    # Create session with traced providers
    session = AgentSession(
        stt=traced_stt,
        llm=openai.LLM(model="gpt-4o-mini"),
        tts=traced_tts
    )
    
    # Setup automatic session tracing
    setup_livekit_tracing(session)
    
    # Start agent
    await session.start(agent=VoiceAgent(), room=ctx.room)

Integration Patterns

1. STT/TTS Wrappers

Wrap audio providers for automatic tracing.

2. Session Tracing

Track complete conversation sessions with context.

3. Agent Integration

Monitor agent decisions and tool usage in voice workflows.

Key Features

• Non-Intrusive: Wrap existing providers without changing your code
• Audio Metrics: Track transcription accuracy, latency, and audio quality
• Context Enrichment: Use extract_job_context(ctx) to enrich spans with room, participant, and job metadata
• Session Context: Maintain conversation context across interactions
• Provider Agnostic: Works with Deepgram, Cartesia, ElevenLabs, and more

What Gets Traced

• STT Operations:
  • Original audio recordings (playable in dashboard)
  • Full audio transcriptions (exact text spoken)
  • Audio input duration and format
  • Confidence scores and accuracy
  • Processing latency
• TTS Operations:
  • Generated audio files (playable in dashboard)
  • Text-to-speech input (exact text sent)
  • Generated audio metadata (duration, format, quality)
  • Audio generation timing
  • Voice and model details
• Agent Sessions: Session lifecycle, user interactions, agent responses
• Audio Metrics: Processing time, audio duration, quality indicators
• JobContext Metadata: Use extract_job_context(ctx) to get room/participant/job info and add to spans manually

Next Steps

• Basic Voice Agent - Complete working example

Need Help?

• Documentation: Browse our comprehensive guides
• Examples: Check out LangChain, LangGraph, and CrewAI examples
• Support: Contact our team for assistance