Cekura JavaScript/TypeScript 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

npm install @cekura/sdk

Integrations

LiveKit

• One-line integration for simulation and observability
• Automatic metrics collection (STT, LLM, TTS, EOU)
• Session logs capture
• Mock tool injection for testing
• Dual-channel audio recording

→ LiveKit Integration Guide

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 { defineAgent, voice } from '@livekit/agents';
import type { JobContext } from '@livekit/agents';
import { LiveKitTracer } from '@cekura/sdk';

const cekura = new LiveKitTracer({
  apiKey: process.env.CEKURA_API_KEY || '',
  agentId: parseInt(process.env.CEKURA_AGENT_ID || '0', 10),
});

export default defineAgent({
  entry: async (ctx: JobContext) => {
    const agent = new YourAssistant();
    const session = new voice.AgentSession({ /* stt, llm, tts, vad */ });

    // Track session with Cekura for simulation calls (includes mock tool injection)
    await cekura.trackSession(ctx, session, agent);

    // Send call with audio to Cekura for observability
    await cekura.observeSession(ctx, session);

    await session.start({ room: ctx.room, agent });
  },
});

See examples/appointment-agent/ for a complete working agent.

Features

• One-Line Integration: Simple API for both simulation calls and observability
• Automatic Metrics Collection: Captures STT, LLM, TTS, and End-of-Utterance metrics
• Session Logs Capture: Automatically captures 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
• 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.

What happens automatically:

• Disables STT (Speech-to-Text)
• Disables TTS (Text-to-Speech)
• Disables VAD (Voice Activity Detection)
• Disables turn detection
• Injects text-only input/output options (audioEnabled: 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

• apiKey (string, required): Your Cekura API key
• agentId (number, required): Unique identifier for your agent from Cekura dashboard
• host (string, optional): API host URL (default: https://api.cekura.ai)
• enabled (boolean, optional): Enable/disable tracer. Defaults to true if not set

Environment Variables

• CEKURA_TRACING_ENABLED (default: "true"): Enable/disable trackSession() for simulation calls
• CEKURA_OBSERVABILITY_ENABLED (default: "true"): Enable/disable observeSession() 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

• Node.js >= 20
• @livekit/agents >= 1.2.7
• livekit-server-sdk >= 2.0.0 (peer dependency, required for audio recording)

License

MIT License - see LICENSE file for details.

Links

• Homepage
• Documentation
• Dashboard

Support

For support, email [email protected]