Skip to main content

​
Python Worker

The Python worker is a full port of the TypeScript agent using the LiveKit Agents Python SDK (v1.4+). It offers a broader provider and plugin ecosystem and is recommended when you need providers not yet available in the TypeScript agent.

​
Prerequisites

  • Python 3.12+
  • uv (Python package manager)

​
Setup

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

​
Running

​
Development (auto-reload on file changes)

pnpm agent-python:dev

​
Production

pnpm agent-python:start

​
Connecting to the playground

Set AGENT_RUNTIME=python in .env.local, then start both the app and the worker: 
# Terminal 1 — Next.js app
pnpm dev

# Terminal 2 — Python agent worker
pnpm agent-python:dev
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-python/
├── 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)

​
Python vs TypeScript worker

TypeScript workerPython worker
LanguageTypeScriptPython
Provider coverageGoodBroader
ML model integrationVia JS packagesVia Python plugins
AGENT_RUNTIME valuetypescriptpython
Start commandpnpm agent-typescript:devpnpm agent-python:dev
Both workers have full feature parity: same AgentConfig format, same step progression logic, same voiceblox.agent.events data channel protocol.

​
Deploying with Docker

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