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:
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
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_NAMEto 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.