Worker lifecycle

Overview

When you start your app with python main.py dev, it registers itself as a worker with LiveKit server. LiveKit server manages dispatching your agents to rooms with users by sending requests to available workers.

A LiveKit session is one or more participants in a room. A LiveKit session is often referred to simply as a "room." When a user connects to a room, a worker fulfills the request to dispatch an agent to the room.

An overview of the worker lifecycle is as follows:

1. Worker registration: Your agent code registers itself as a "worker" with LiveKit server, then waits on standby for requests.
2. Job request: When a user connects to a room, LiveKit server sends a request to an available worker. A worker accepts and starts a new process to handle the job. This is also known as agent dispatch.
3. Job: The job initiated by yourentrypoint function. This is the bulk of the code and logic you write. To learn more, see Job lifecycle.
4. LiveKit session close: By default, a room is automatically closed when the last non-agent participant leaves. Any remaining agents disconnect. You can also end the session manually.

The following diagram shows the worker lifecycle:

Some additional features of workers include the following:

• Workers automatically exchange availability and capacity information with the LiveKit server, enabling load balancing of incoming requests.
• Each worker can run multiple jobs simultaneously, running each in its own process for isolation. If one crashes, it won’t affect others running on the same worker.
• When you deploy updates, workers gracefully drain active LiveKit sessions before shutting down, ensuring no sessions are interrupted mid-call.

Worker options

You can change the permissions, dispatch rules, add prewarm functions, and more through WorkerOptions.