Trace LiveKit applications - Docs by LangChain

LangSmith can capture traces generated by LiveKit Agents using OpenTelemetry instrumentation. This guide shows you how to automatically capture traces from your LiveKit voice AI agents and send them to LangSmith for monitoring and analysis. For our high-level guiding principles on tracing voice agents, see Voice tracing fundamentals. For a complete implementation, see the voice demo repository.

Installation

Install the required packages:

pip install langsmith livekit livekit-agents livekit-plugins-openai livekit-plugins-silero livekit-plugins-turn-detector opentelemetry-exporter-otlp python-dotenv

Quickstart tutorial

Follow this step-by-step tutorial to create a voice AI agent with LiveKit and LangSmith tracing. You’ll build a complete working example by copying and pasting code snippets.

Step 1: Set up your environment

Create a .env file in your project directory:

.env

OTEL_EXPORTER_OTLP_ENDPOINT=https://api.smith.langchain.com/otel
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=<your-langsmith-api-key>, Langsmith-Project=livekit-voice
LIVEKIT_URL=<your-livekit-url>
LIVEKIT_API_KEY=<your-livekit-api-key>
LIVEKIT_API_SECRET=<your-livekit-api-secret>
OPENAI_API_KEY=<your-openai-api-key>

Step 2: Download the span processor

LiveKit emits OpenTelemetry spans, but most of the useful data rides in LiveKit-specific attributes that LangSmith doesn’t recognize by default. A custom span processor translates those attributes so your traces render properly in LangSmith. Add the custom span processor file and save it as langsmith_processor.py in your project directory.

What does the span processor do?

The span processor enriches LiveKit Agents’ OpenTelemetry spans with LangSmith-compatible attributes so your traces display properly in LangSmith.Key functions:

Converts LiveKit span types (stt, llm, tts, agent, session, job) to LangSmith format.
Adds gen_ai.prompt.* and gen_ai.completion.* attributes for message visualization.
Surfaces LiveKit’s metrics (time-to-first-token, time-to-first-byte, end-to-end latency, and other lk.* analysis data) as run metadata.
Tracks and aggregates conversation messages across the conversation.
Renders the whole-conversation transcript and attaches the call recording to the root run.

It only reshapes spans it recognizes as LiveKit’s; any other span (for example, a nested LangChain or LangGraph run) passes through untouched. The processor activates when you import it in your code.

Step 3: Create your voice agent file

Create a new file called agent.py and add the following code. We’ll build it section by section so you can copy and paste each part.

Part 1: Import dependencies and set up tracing

import sys
import os
from pathlib import Path
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Import LiveKit components
from livekit import agents
from livekit.agents import AgentServer, AgentSession, Agent
from livekit.agents.telemetry import set_tracer_provider
from livekit.plugins import openai, silero
from livekit.plugins.turn_detector.multilingual import MultilingualModel
from opentelemetry.sdk.trace import TracerProvider

# Import span processor to enable LangSmith tracing
from langsmith_processor import LangSmithSpanProcessor

# Set up LangSmith tracing
def setup_langsmith():
    """Setup OpenTelemetry tracing to export spans to LangSmith."""
    endpoint = os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
    headers = os.getenv("OTEL_EXPORTER_OTLP_HEADERS")

    if not endpoint or not headers:
        print("⚠️  Warning: OTEL environment variables not set. Tracing disabled.")
        return

    # Create tracer provider with custom span processor
    trace_provider = TracerProvider()
    trace_provider.add_span_processor(LangSmithSpanProcessor())

    # Set as LiveKit's tracer provider
    set_tracer_provider(trace_provider)
    print("✅ LangSmith tracing enabled")

# Enable tracing before creating agents
setup_langsmith()

Part 2: Define your agent

class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="""You are a helpful voice AI assistant.
            You eagerly assist users with their questions.
            Keep responses concise and conversational.""",
        )

Part 3: Set up the agent server

server = AgentServer()

@server.rtc_session()
async def my_agent(ctx: agents.JobContext):
    # Create agent session with STT, LLM, TTS, and VAD
    session = AgentSession(
        stt="deepgram/nova-2:en",
        llm="openai/gpt-5.4-mini",
        tts=openai.TTS(model="tts-1", voice="alloy"),
        vad=silero.VAD.load(),
        turn_detection=MultilingualModel(),
    )

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

if __name__ == "__main__":
    # Run in console mode for local testing
    sys.argv = [sys.argv[0], "console"]
    agents.cli.run_app(server)

Step 4: Run your agent

Run your voice agent in console mode for local testing:

python agent.py console

Your agent will start and connect to LiveKit. Speak through your microphone, and all traces will automatically appear in LangSmith. View the complete agent.py code.

Advanced usage

Trace speech-to-speech models

The previous example uses a cascade pipeline (separate STT, LLM, and TTS services). LiveKit also supports speech-to-speech models, where a single realtime model handles audio in and out. To trace one, build the session with a realtime model instead of the STT/LLM/TTS stack. The tracing setup is identical and the span processor is unchanged:

from livekit.plugins import openai as lk_openai

session = AgentSession(llm=lk_openai.realtime.RealtimeModel(voice="marin"))

Attach the conversation audio

To listen to a conversation alongside its transcript, record the call and attach the audio file to the root run. Record what was played to the client so the recording reflects what was actually heard, including any speech cut off by an interruption. For the underlying attachment API, see Upload files with traces.

Custom metadata and tags

You can add custom metadata to your traces using span attributes:

from opentelemetry import trace

class Assistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="You are a helpful assistant.",
        )

        # Get current span and add custom attributes
        tracer = trace.get_tracer(__name__)
        span = trace.get_current_span()
        if span:
            span.set_attribute("langsmith.metadata.agent_type", "voice_assistant")
            span.set_attribute("langsmith.metadata.version", "1.0")
            span.set_attribute("langsmith.span.tags", "livekit,voice-ai,production")

Troubleshooting

Spans not appearing in LangSmith

If traces aren’t showing up in LangSmith:

Verify environment variables: Ensure OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS are set correctly in your .env file.
Check setup order: Make sure setup_langsmith() is called before creating AgentServer.
Check API key: Confirm your LangSmith API key has write permissions.
Look for confirmation: You should see ”✅ LangSmith tracing enabled” in the console when starting.

Messages not showing correctly

If conversation messages aren’t displaying properly:

Check span processor: Verify langsmith_processor.py is in your project directory and imported correctly.
Verify imports: Ensure LangSmithSpanProcessor is imported in your agent.py.
Enable debug logging: Set LANGSMITH_PROCESSOR_DEBUG=true in your environment to see detailed logs.

Connection issues

If your agent can’t connect to LiveKit:

Verify LiveKit URL: Check LIVEKIT_URL is set correctly in your .env file.
Check credentials: Ensure LIVEKIT_API_KEY and LIVEKIT_API_SECRET are correct.
Test connection: Try connecting to your LiveKit server with the LiveKit CLI first.
Console mode: For local testing, always use: python agent.py console.

Import errors

If you’re getting import errors:

Install dependencies: Run the complete pip install command from Step 1.
Check Python version: Ensure you’re using Python 3.9 or higher.
Verify langsmith_processor: Make sure langsmith_processor.py is downloaded and in the same directory as agent.py.
Check LiveKit plugins: Ensure you have the correct LiveKit plugins installed for your STT/LLM/TTS providers.

Agent not responding

If your agent connects but doesn’t respond:

Check API keys: Verify your OpenAI API key (or other provider keys) are correct.
Test services: Ensure your STT, LLM, and TTS services are accessible.
Check instructions: Make sure your Agent has proper instructions.
Review logs: Look for errors in the console output.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​Installation

​Quickstart tutorial

​Step 1: Set up your environment

​Step 2: Download the span processor

​Step 3: Create your voice agent file

​Part 1: Import dependencies and set up tracing

​Part 2: Define your agent

​Part 3: Set up the agent server

​Step 4: Run your agent

​Advanced usage

​Trace speech-to-speech models

​Attach the conversation audio

​Custom metadata and tags

​Troubleshooting

​Spans not appearing in LangSmith

​Messages not showing correctly

​Connection issues

​Import errors

​Agent not responding

Installation

Quickstart tutorial

Step 1: Set up your environment

Step 2: Download the span processor

Step 3: Create your voice agent file

Part 1: Import dependencies and set up tracing

Part 2: Define your agent

Part 3: Set up the agent server

Step 4: Run your agent

Advanced usage

Trace speech-to-speech models

Attach the conversation audio

Custom metadata and tags

Troubleshooting

Spans not appearing in LangSmith

Messages not showing correctly

Connection issues

Import errors

Agent not responding