cekura 1.2.0rc1

Testing and Observability SDK for AI Agents

Cekura Python SDK

Testing and Observability for AI Voice Agents. Launch in minutes not weeks by ensuring your agents deliver a seamless experience in every conversational scenario.

Installation

pip install cekura

LiveKit Integration

Setup

1. Create a new agent in the Cekura dashboard
2. Select LiveKit as the provider in agent settings
3. Enable tracing for your agent
4. Copy your API key and Agent ID

Quick Start

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
)

@server.rtc_session(agent_name="my_agent")
async def entrypoint(ctx: agents.JobContext):
    # Create your assistant and session
    assistant = YourAssistant()
    session = agents.AgentSession(...)

    # Track session with Cekura for simulation calls (includes mock tool injection)
    await cekura.track_session(ctx, session, assistant)

    # Send call with audio to Cekura for observability
    await cekura.observe_session(ctx, session)

    # Start your session
    await session.start(room=ctx.room, agent=assistant)

Next Steps

After integrating the SDK, you can:

• Run tests from the Cekura platform
• Monitor real-time conversations
• Analyze performance metrics
• Review conversation transcripts, tool calls, and session logs

Features

• One-Line Integration: Simple one line API for seamless integration for both simulation calls and observability
• Automatic Metrics Collection: Captures STT, LLM, TTS, and End-of-Utterance metrics
• Session Logs Capture: Automatically captures and exports all application logs (INFO level and above) with session context
• Automated Chat Mode Support: Automatically detects and configures text-only mode when running chat-based tests from Cekura, disabling audio components
• Dual-Channel Audio Recording: Records production calls with dual audio channel for analysis
• Conversation Tracking: Records complete chat history with tool calls
• Mock Tool Injection: Automatically replaces tools with mock versions configured in Cekura dashboard for simulation calls
• Session Reports: Generates comprehensive session reports from LiveKit

Automated Chat Mode Support

When running chat-based simulation tests from the Cekura platform, the SDK automatically detects chat mode and patches the session to disable audio components, ensuring optimal text-only performance.

What happens automatically:

• Disables STT (Speech-to-Text)
• Disables TTS (Text-to-Speech)
• Disables VAD (Voice Activity Detection)
• Disables turn detection
• Injects text-only room_options (audio_input=False, audio_output=False)

No code changes needed - the SDK detects chat mode from Cekura and handles everything automatically.

Mock Tools

The SDK automatically injects mock tools when running tests from the Cekura platform. Mock tools return predefined responses configured in the dashboard.

Setup:

1. Create mock tools in the Cekura dashboard under your agent settings
2. Define input/output pairs for each tool
3. When tests run, the SDK automatically replaces matching tools with mocks

Configuration

Parameters

• api_key (str, required): Your Cekura API key
• agent_id (int, required): Unique identifier for your agent from Cekura dashboard
• host (str, optional): API host URL (default: https://api.cekura.ai)
• enabled (bool, optional): Enable/disable tracer. Defaults to True if not set

Environment Variables

• CEKURA_TRACING_ENABLED (default: "true"): Enable/disable track_session() for simulation calls
• CEKURA_OBSERVABILITY_ENABLED (default: "true"): Enable/disable observe_session() for production call recording
• CEKURA_MOCK_TOOLS_ENABLED (default: "true"): Enable/disable mock tool injection

Data Collected

The SDK automatically collects:

• Session start/end timestamps
• Complete conversation transcripts
• Tool/function calls and outputs
• Session logs (INFO level and above)
• Dual-channel audio recording for production calls
• Performance metrics:
  • Speech-to-Text (STT) latency and duration
  • LLM token usage and timing
  • Text-to-Speech (TTS) generation time
  • End-of-Utterance detection timing
• Room and job information
• Custom metadata

Requirements

• Python 3.9+
• aiohttp>=3.9.0

License

MIT License - see LICENSE file for details.

Links

• Homepage
• Documentation
• Dashboard

Support

For support, email [e-mail]