LiveKit Tracing

Enhanced observability for LiveKit agents using the Cekura Python SDK

Overview

LiveKit Tracing provides deep observability into your LiveKit agent’s performance by integrating the Cekura Python SDK directly into your agent code. This integration significantly enhances the information available in the Cekura platform for end-to-end visibility over agent execution.

What you get:

• Complete conversation transcripts with full message history
• Tool/function calls with inputs and outputs
• Detailed performance metrics (STT, TTS, LLM, End-of-Utterance)
• Session logs captured automatically from your application
• Mock tools support for testing with predictable tool responses
• Dual-channel audio recording for monitoring production calls
• LiveKit job and room metadata

Video Tutorial

Prerequisites

• A Cekura account with an API key
• A LiveKit agent project

Setup

Testing

Use this setup in your test agents while running simulation calls from the Cekura platform.

1. Install the Cekura Python SDK

   pip install cekura==1.1.0rc1
   
2. Integrate the SDK in your LiveKit agent

   Add the Cekura tracer to your LiveKit agent’s entrypoint:

   import os
   from livekit import agents
   from cekura.livekit import LiveKitTracer
   
   # Initialize Cekura tracer
   cekura = LiveKitTracer(
       api_key=os.getenv("CEKURA_API_KEY"),
       agent_id=123  # Your agent ID from Cekura dashboard
   )
   
   @server.rtc_session(agent_name="my_agent")
   async def entrypoint(ctx: agents.JobContext):
       assistant = YourAssistant()
       session = agents.AgentSession(...)
   
       # Track session with automatic tool injection and export
       await cekura.track_session(ctx, session, assistant)
   
       await session.start(room=ctx.room, agent=assistant)
   

   What this does:

   • Captures transcripts, tool calls, metrics, and session logs
   • Automatically injects mock tools configured in Cekura
   • Automatically configures chat/text mode when running text-based tests
   • Exports data to Cekura for test analysis
3. Configure LiveKit provider and enable tracing

   Navigate to your agent settings in the Cekura dashboard, select LiveKit as the provider, and enable tracing:

   

   Required configuration:

   • LiveKit API Key: Your LiveKit API key
   • LiveKit API Secret: Your LiveKit API secret
   • LiveKit URL: Your LiveKit server URL (e.g., wss://your-server.livekit.cloud)
   • Agent Name: The specific agent name to dispatch in LiveKit
   • LiveKit Config (JSON) (Optional): Additional room configuration parameters (accessible in agent code via get_simulation_data())

   Testing connection types:

   

   Configure at least one connection type for voice-based testing:

   • WebRTC: Direct LiveKit room connection using the credentials configured above
   • Telephony: Phone-based testing if your LiveKit agent is connected to a phone system (requires Contact Number)

   For text-based testing:

   • Chat: Select LiveKit to enable chat-based testing (uses the same WebRTC configuration, no additional setup required)
4. Run tests

   Run tests using your preferred connection type:

   • Run with LiveKit: For WebRTC-based testing
   • Run with Voice: For telephony-based testing
   • Run with Text: For chat-based testing

   
5. Analyze the call

   Navigate to the Runs section to view your test results with enhanced data including transcripts, tool calls, session logs, and detailed performance metrics.

Observability

Use this setup in your production agents for monitoring live calls with audio recording.

1. Install the Cekura Python SDK

   pip install cekura==1.1.0rc1
   
2. Integrate the SDK in your LiveKit agent

   Add the Cekura tracer to your LiveKit agent’s entrypoint:

   import os
   from livekit import agents
   from cekura.livekit import LiveKitTracer
   
   # Initialize Cekura tracer
   cekura = LiveKitTracer(
       api_key=os.getenv("CEKURA_API_KEY"),
       agent_id=123  # Your agent ID from Cekura dashboard
   )
   
   @server.rtc_session(agent_name="my_agent")
   async def entrypoint(ctx: agents.JobContext):
       assistant = YourAssistant()
       session = agents.AgentSession(...)
   
       # Observe session with audio recording and metrics
       await cekura.observe_session(ctx, session)
   
       await session.start(room=ctx.room, agent=assistant)
   

   What this does:

   • Captures transcripts, tool calls, metrics, and session logs
   • Records dual-channel audio (agent + user) for analysis
   • Exports data to Cekura observability endpoint
3. Configure LiveKit provider and credentials

   Navigate to your agent settings in the Cekura dashboard, select LiveKit as the provider:

   

   Required configuration for audio recording:

   • LiveKit API Key: Your LiveKit API key
   • LiveKit API Secret: Your LiveKit API secret
   • LiveKit URL: Your LiveKit server URL (e.g., wss://your-server.livekit.cloud)
   • Agent Name: The specific agent name to dispatch in LiveKit

   All LiveKit credentials are required to enable audio egress recording for production calls.

4. Monitor production calls

   Once configured, all production calls will automatically appear in the Calls section of your Cekura dashboard.

Enhanced Data in Cekura UI

With tracing enabled, you’ll see enriched information in the Cekura platform:

The run now displays:

• Room Session ID: Visible in the call provider ID field, allowing you to correlate Cekura test runs with specific LiveKit sessions
• Complete Transcript: Full conversation history from the LiveKit agent, including tool/function call requests and responses
• Provider Call Data: Detailed metadata accessible in the run details, including job information, room configuration, session logs, and raw performance metrics

Provider Call Data contains the following information:

• Job Information: Job ID, room name, participant details, and agent dispatch metadata
• Room Information: Room configuration, participant count, session duration, and connection details
• Session Logs: Captured agent session logs with timestamps, log levels, and messages for debugging
• Raw Metrics:
  • STT (Speech-to-Text): Latency, duration, and transcription timing
  • TTS (Text-to-Speech): Generation time and audio synthesis metrics
  • LLM: Token usage, response time, and inference latency
  • EOU (End-of-Utterance): Detection timing and accuracy
• Custom Metadata: Additional metadata passed to the SDK via **metadata parameters

Automatic Chat Mode Support

The SDK automatically handles chat/text mode configuration when you run scenarios using “Run with Text” — no code changes required.

When you run a text-based test, the SDK automatically patches your session to disable audio processing, enabling pure text-based interactions with your agent. This provides:

• Targeted testing of your agent’s conversational logic without audio overhead
• Cost savings by eliminating STT/TTS provider costs and reducing Cekura credit usage
• Faster simulations compared to voice-based tests

Your track_session() integration works seamlessly for both voice and text modes.

Using Mock Tools with LiveKit Tracing

The SDK supports mock tools, allowing you to test your agent with predictable tool responses. This is useful for creating reproducible test scenarios without relying on live external services.

To use mock tools:

1. Create mock tools in Cekura: Set up your mock tool configurations in the Cekura dashboard. See the Mock Tools guide for detailed instructions.

2. SDK handles the rest: Once mock tools are configured, the SDK automatically routes tool calls to Cekura’s mock endpoints during testing - no additional code changes needed.

3. Test with predictable data: Your agent will receive the mock responses you configured, making it easy to test specific scenarios and edge cases.

Best Practices

1. Use the right method for your environment: Use track_session() in your test/UAT environments for simulation testing with mock tools. Use observe_session() in your production environment for monitoring live calls with audio recording.

2. Use environment variables for credentials: Don’t hardcode API keys in your code

3. Keep the SDK updated: Run pip install --upgrade cekura periodically for the latest features

4. Review tool calls regularly: Add the predefined metric Tool Call Success to your evaluators

SDK Reference

LiveKitTracer Initialization

from cekura.livekit import LiveKitTracer

cekura = LiveKitTracer(
    api_key="your_api_key",         # Required: Your Cekura API key
    agent_id=123,                   # Required: Agent ID from dashboard
    host="https://api.cekura.ai",   # Optional: Custom API host
    enabled=True                    # Optional: Enable/disable tracer
)

track_session()

Tracks simulation/test calls with automatic mock tool injection and chat mode support. Collects transcripts, tool calls, session logs, and metrics.

await cekura.track_session(
    ctx,               # Required: LiveKit JobContext
    session,           # Required: LiveKit AgentSession
    agent,             # Optional: Agent instance for mock tool injection
    capture_logs=True, # Optional: Capture session logs (default: True)
    **metadata         # Optional: Custom metadata
)

Environment variables:

• CEKURA_TRACING_ENABLED="false": Disable tracking entirely
• CEKURA_MOCK_TOOLS_ENABLED="false": Disable only mock tool injection

observe_session()

Monitors production calls with dual-channel audio recording. Collects transcripts, tool calls, session logs, and metrics. Requires LiveKit credentials configured in Cekura.

await cekura.observe_session(
    ctx,               # Required: LiveKit JobContext
    session,           # Required: LiveKit AgentSession
    capture_logs=True, # Optional: Capture session logs (default: True)
    **metadata         # Optional: Custom metadata
)

Environment variables:

• CEKURA_OBSERVABILITY_ENABLED="false": Disable observability entirely

get_simulation_data()

Extracts simulation data populated by Cekura when running simulation calls from the platform. Returns empty dict for phone-based calls.

await ctx.connect()  # Must be called first

simulation_data = cekura.get_simulation_data(
    ctx    # Required: LiveKit JobContext
)

Returns: Dictionary with simulation metadata:

{
    "scenario_id": 123,              # Scenario being tested
    "run_id": 456,                   # Current run ID
    "test_profile_data": {           # Test profile data
        "customer_name": "John Doe",
        "account_number": "ACC-12345"
    },
    "additional_config": {           # LiveKit config from agent settings
        "sample_key": "sample_value"
    }
}

This data is ONLY available when using Option 2 (Automated LiveKit Testing) - running tests via “Run with LiveKit”. Phone-based calls (Option 1) will return an empty dictionary.

Next Steps

• Set up mock tools for testing with predictable tool responses
• Create custom metrics to evaluate based on provider call data
• Perform load testing with your LiveKit agent
• Explore predefined metrics