Skip to main content

​
Python Worker

The Python worker runs the Voiceblox agent using the LiveKit Agents Python SDK (v1.4+).

​
Prerequisites

  • Python 3.12+
  • uv (Python package manager)

​
Setup

cd agent
uv sync
Download required ML models (run once after setup): 
pnpm agent:download-files

​
Running

​
Starting the agent server

pnpm agent:server
The agent server spawns workers on demand via /ensure-worker. It auto-reloads on file changes in development.

​
Connecting to the playground

Start both the app and the agent server: 
# Terminal 1 — Next.js app
pnpm dev

# Terminal 2 — Python agent server
pnpm agent:server
Ensure AGENT_SERVER_URL=http://localhost:8080 is set in .env.local. When you click Test in the builder, the app creates a LiveKit room with the AgentConfig in metadata and dispatches the job to this worker.

​
Required environment variables

The worker loads environment variables from the project root .env.local. 
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxxxx
LIVEKIT_API_SECRET=your-secret
Plus provider keys for whichever LLM, TTS, and STT your flow uses. Keys not set fall back to the LiveKit inference gateway.

​
Supported providers

​
LLM

OpenAI, Gemini, Groq, Together, Azure, Cerebras, xAI, Fireworks, Perplexity, DeepSeek, Moonshot, Telnyx, Ollama, OVHcloud

​
TTS

ElevenLabs, Deepgram, OpenAI, Cartesia, Rime, Neuphonic, Resemble

​
STT

Deepgram, OpenAI, Groq, OVHcloud

​
Tools

  • MCP servers — native MCPServerHTTP support with bearer/API key auth
  • Exa web search — configurable search type and result count

​
Project structure

agent/
├── src/
│   ├── main.py          # Worker entry point
│   ├── agent.py         # VoicebloxAgent + build helpers
│   ├── models.py        # AgentConfig dataclasses
│   └── step_watcher.py  # Conversation step state machine
└── pyproject.toml       # Dependencies (managed by uv)

​
Deploying with Docker

See Docker Compose for running the Python worker alongside the web app in a container.