```
### 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](https://github.com/langchain-ai/voice-demo/blob/main/src/voice_demo/livekit/processor.py) and save it as `langsmith_processor.py` in your project directory.
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
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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:
```bash theme={null}
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](https://github.com/langchain-ai/voice-demo/blob/main/src/voice_demo/livekit/agent.py).
## 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:
```python theme={null}
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](/langsmith/upload-files-with-traces).
### Custom metadata and tags
You can add custom metadata to your traces using span attributes:
```python theme={null}
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.
***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/trace-with-livekit.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).