> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiceblox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Worker

> Run the Voiceblox agent as a standalone Python worker process using the LiveKit Agents Python SDK.

# Python Worker

The Python worker runs the Voiceblox agent using the [LiveKit Agents Python SDK](https://github.com/livekit/agents) (v1.4+).

## Prerequisites

* Python 3.12+
* [uv](https://docs.astral.sh/uv/) (Python package manager)

## Setup

```bash theme={null}
cd agent
uv sync
```

Download required ML models (run once after setup):

```bash theme={null}
pnpm agent:download-files
```

## Running

### Starting the agent server

```bash theme={null}
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:

```bash theme={null}
# 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`.

```env theme={null}
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](/deployment/docker) for running the Python worker alongside the web app in a container.