The worker in services/agent-python runs every call. It is built on the LiveKit Agents Python SDK, pinned to one exact version together with every livekit-plugins-* package (see services/agent-python/pyproject.toml). Bump them together, by hand, after reading the release notes; Renovate is configured to leave them alone. In the normal local setup the worker runs in Docker (docker compose -f docker-compose.dev.yml up). Run it natively when you are changing the Python code.

​
Prerequisites

  • Python 3.12+
  • uv
  • The media server and Redis from docker-compose.dev.yml

​
Setup

Download the turn-detection and noise models once:

​
Running

Stop the Docker worker first so only one worker registers with the local media server:
The agent-python:* scripts read the project root .env.local. Point it at .env once:
Then:

​
Connecting to the Playground

When a user starts a Playground conversation, the app creates a room, puts the agent configuration in its metadata and dispatches the job to this worker. Published agents and share links dispatch with a numeric deployment id instead; the worker reads that snapshot from data/agent-configs, so the native worker needs the same data directory the app writes to.

​
Environment variables

The worker needs the media server credentials plus provider keys for whichever model, voice and hearing providers the agents use. The provider tables in Environment variables are the authoritative list of what the worker can run; the Persona’s provider pickers in the builder show the same set.

​
Tests and checks

​
Project structure

​
Deploying with Docker

See Docker Compose for how the worker container is built and started.