Dispatching agents

As part of an agent's lifecycle, agent workers register with the LiveKit server and remain idle until they are assigned to a room to interact with end users. The process of assigning an agent to a room is called dispatching an agent.

LiveKit’s dispatch system is optimized for concurrency and low latency. It supports hundreds of thousands of new connections per second and dispatches an agent to a room in under 150ms.

Automatic agent dispatch

By default, agents are automatically dispatched when rooms are created. If a participant connects to LiveKit and the room does not already exist, it is created automatically, and an agent is assigned to it.

Automatic dispatch is the best option if the same agent needs to be assigned to new participants consistently.

Explicit agent dispatch

For greater control over when and how agents join rooms, explicit dispatch is available. This approach leverages the same worker systems, allowing you to run agent workers in the same way.

The key difference is that when registering the agent, the agent_name field in WorkerOptions needs to be set.

opts = WorkerOptions(
    ...
    agent_name="test-agent",
)

Dispatch via API

Agents running with an agent_name set can be explicitly dispatched to a room via AgentDispatchService.

import asyncio
from livekit import api

room_name = "my-room"
agent_name = "test-agent"

async def create_explicit_dispatch():
    lkapi = api.LiveKitAPI()
    dispatch = await lkapi.agent_dispatch.create_dispatch(
        api.CreateAgentDispatchRequest(
            agent_name=agent_name, room=room_name, metadata="my_job_metadata"
        )
    )
    print("created dispatch", dispatch)

    dispatches = await lkapi.agent_dispatch.list_dispatch(room_name=room_name)
    print(f"there are {len(dispatches)} dispatches in {room_name}")
    await lkapi.aclose()

asyncio.run(create_explicit_dispatch())

If my-room does not exist, it is created automatically during dispatch, and an instance of test-agent is assigned to it.

Handling job metadata

The metadata set during dispatch is included in the Job metadata passed to the agent.

async def entrypoint(ctx: JobContext):
    logger.info(f"job metadata: {ctx.job.metadata}")
    ...

Dispatch on participant connection

A participant’s token can be configured to dispatch one or more agents immediately upon connection.

To dispatch multiple agents, include multiple RoomAgentDispatch entries in RoomConfiguration.

from livekit.api import (
  AccessToken,
  RoomAgentDispatch,
  RoomConfiguration,
  VideoGrants,
)

room_name = "my-room"
agent_name = "test-agent"

def create_token_with_agent_dispatch() -> str:
    token = (
        AccessToken()
        .with_identity("my_participant")
        .with_grants(VideoGrants(room_join=True, room=room_name))
        .with_room_config(
            RoomConfiguration(
                agents=[
                    RoomAgentDispatch(agent_name="test-agent", metadata="my_metadata")
                ],
            ),
        )
        .to_jwt()
    )
    return token