Trace LiveKit applications ↗

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.
• Tracks and aggregates conversation messages across turns
• Uses multiple extraction strategies to handle various LiveKit attribute formats.

The processor automatically 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 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-4.1-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. Here is an example of a trace in LangSmith: LangSmith trace with LiveKit

View the complete agent.py code.

Advanced usage#

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:

1. Verify environment variables: Ensure OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS are set correctly in your .env file.
2. Check setup order: Make sure setup_langsmith() is called before creating AgentServer.
3. Check API key: Confirm your LangSmith API key has write permissions.
4. 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:

1. Check span processor: Verify langsmith_processor.py is in your project directory and imported correctly.
2. Verify imports: Ensure LangSmithSpanProcessor is imported in your agent.py.
3. 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:

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

Import errors#

If you’re getting import errors:

1. Install dependencies: Run the complete pip install command from Step 1.
2. Check Python version: Ensure you’re using Python 3.9 or higher.
3. Verify langsmith_processor: Make sure langsmith_processor.py is downloaded and in the same directory as agent.py.
4. 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:

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

Edit this page on GitHub or file an issue.

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