Skip to content

Testing & Deployment Guide

This guide covers local verification workflows, writing automated tests for tools, and containerized production deployment.


1. Local Testing Workflow

Follow this sequence when developing and testing changes:

1. chakra-convai check    ──▶ Validates syntax, prompts, tools, licence
2. chakra-convai prompt   ──▶ Inspects assembled LLM prompt
3. chakra-convai kb       ──▶ Tests knowledge-base retrieval
4. pytest tests/          ──▶ Runs unit tests against skills
5. chakra-convai console  ──▶ Voice conversation via microphone
6. chakra-convai dev      ──▶ Live-reloading server with LiveKit

Writing Unit Tests for Skills

Skills inherit from BaseSkill and can be tested directly with pytest using a mock state dictionary:

# tests/test_weather_skill.py
import pytest
from myapp.skills.weather.tool import WeatherSkill

@pytest.mark.asyncio
async def test_weather_skill_returns_clean_fallback(monkeypatch):
    monkeypatch.delenv("OPENWEATHER_API_KEY", raising=False)

    # Provide mock call context
    mock_context = {
        "session_id": "test_session_1",
        "language": "english",
        "caller_number": "0771234567"
    }

    skill = WeatherSkill(mock_context)
    result = await skill.get_current_weather("Kandy")
    assert "STATUS: NOT_CONFIGURED" in result or "Kandy" in result

Run tests from the root of your application repository:

pytest tests/


2. Production Docker Deployment

Deploy the agent as a container image. The worker only requires outbound network access to LiveKit, Chakra Labs, and Google; it does not listen on inbound public ports.

# syntax=docker/dockerfile:1
FROM python:3.12-slim
WORKDIR /app

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential curl && \
    rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN --mount=type=secret,id=fury,env=FURY_DEPLOY_TOKEN \
    pip install --no-cache-dir -r requirements.txt \
      --extra-index-url "https://deploy:${FURY_DEPLOY_TOKEN}@pypi.chakralabsai.com/simple/"

COPY . .
RUN chakra-convai download-files

CMD ["chakra-convai", "start"]

Building the Image

docker build --secret id=fury,env=FURY_DEPLOY_TOKEN -t my-voice-agent .

3. Production Readiness Checklist

  • Secrets Management: Supply secrets (CHAKRA_LICENSE_KEY, LIVEKIT_*, DATABASE_URL) via environment variables or cloud secret managers. Never hardcode tokens in the Docker image.
  • Agent Name Matching: Set AGENT_NAME to match your LiveKit inbound dispatch SIP rules.
  • Hardware Sizing: Each active concurrent call runs in an isolated process. As a baseline, allocate 2 vCPU and 4 GB RAM per worker instance and monitor CPU utilization during peak traffic.
  • Redundancy: Run at least two container replicas to ensure seamless rolling restarts during updates.

4. Production License Behavior

  • Startup Validation: The service verifies the license with Chakra Console on startup.
  • Periodic Refresh: The license refreshes in the background every 10 minutes.
  • High-Availability Grace Period: If Chakra Console cannot be contacted due to transient network issues, the worker enters a 6-hour grace period, allowing existing and new calls to proceed uninterrupted.
  • Dynamic Configuration: Changes made in the Console (such as updated talk-time limits or pipeline assignments) apply automatically within 10 minutes without requiring container redeployments.