green-balloon-95599
06/26/2025, 7:21 PMtall-airline-16756
06/26/2025, 7:21 PMtall-airline-16756
06/26/2025, 7:21 PMgreen-balloon-95599
06/26/2025, 7:24 PMtall-airline-16756
06/26/2025, 7:24 PMgreen-balloon-95599
06/26/2025, 7:27 PMtall-airline-16756
06/26/2025, 7:27 PMagent_name
field in the WorkerOptions
when creating your agent. It's totally easy! For example: `opts = WorkerOptions(
...
agent_name="test-agent",
)`Or if you're using the CLI template approach: if __name__ == "__main__":
cli.run_app(
WorkerOptions(
entrypoint_fnc=entrypoint,
prewarm_fnc=prewarm,
agent_name="inbound-agent",
),
)
2. Next, start your agent in development mode - just run: python3 agent.py dev
3. Now for the fun part - use explicit dispatch to connect to your named agent via the API. Here's a friendly example: 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='{"user_id": "12345"}'
)
)
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())
Pro tip: When you set the agent_name, automatic dispatch gets disabled, which means you'll have total control over when and how your agent joins rooms. Pretty cool, right? 😎 Sources: Agent dispatch | LiveKit Docs | Accepting incoming calls | LiveKit Docsgreen-balloon-95599
06/26/2025, 7:35 PMtall-airline-16756
06/26/2025, 7:36 PMagent_name
field in the WorkerOptions
when registering your agent:
opts = WorkerOptions(
entrypoint_fnc=entrypoint,
agent_name="test-agent",
)
By doing this, your agent won't jump into rooms on its own – you're taking the driver's seat!
Dispatching an Agent via API
Once your agent is up and running with an agent_name
, you can personally guide it into rooms using the AgentDispatchService
. It's like calling your agent's personal taxi service!
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())
Don't worry – if the room doesn't exist yet, it'll be created automatically during dispatch. Super convenient, right?
Handling Job Metadata
You can also add some extra context when dispatching an agent. It's like giving your agent a little note about its mission:
async def entrypoint(ctx: JobContext):
<http://logger.info|logger.info>(f"job metadata: {ctx.job.metadata}")
# Rest of your agent code
Use Case: Telephony Integration
For telephony setups, explicit dispatch is a game-changer. It ensures no surprise room assignments, giving you total control:
if __name__ == "__main__":
agents.cli.run_app(agents.WorkerOptions(
entrypoint_fnc=entrypoint,
agent_name="my-telephony-agent"
))
Need any help working through this? I'm here to guide you! Just give me a shout if something isn't crystal clear. 😊
Sources: Dispatching agents | LiveKit Docs | Dispatching agents | LiveKit Docs | Agents telephony integration | LiveKit Docsgreen-balloon-95599
06/26/2025, 7:37 PMtall-airline-16756
06/26/2025, 7:38 PMAgentDispatchService
– super straightforward.
2. Leveraging SIP dispatch rules for inbound calls – neat trick!
3. Configuring participant tokens with RoomAgentDispatch
entries, which lets you set up dispatch right from the client side.
That last method is especially handy – it means you can plan out agent assignments when participants first connect. Sounds complicated, but it's actually pretty simple once you get the hang of it. Want me to walk you through the details? I'm happy to help! Sources: Dispatching agents | LiveKit Docsgreen-balloon-95599
06/26/2025, 7:44 PMtall-airline-16756
06/26/2025, 7:44 PMimport 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())
3. Client-Side Token Configuration Example (RoomAgentDispatch)
import { AccessToken, VideoGrant } from 'livekit-server-sdk';
import { RoomAgentDispatch, RoomConfiguration } from '@livekit/protocol';
const roomName = 'name-of-room';
const participantName = 'user-name';
const agentName = 'my-agent';
const at = new AccessToken('api-key', 'secret-key', {
identity: participantName,
});
const videoGrant: VideoGrant = {
room: roomName,
roomJoin: true,
};
at.addGrant(videoGrant);
at.roomConfig = new RoomConfiguration({
agents: [
new RoomAgentDispatch({
agentName: "test-agent",
metadata: "test-metadata"
})
]
});
const token = await at.toJwt();
console.log('access token', token);
Hey there! I've got two awesome ways for you to set up agent dispatches – one using the API and another with client-side token configuration. The cool part? Both methods let you add job metadata, so you can pass along extra context like user IDs. Sounds helpful, right? If anything's not clicking, just give me a shout, and I'll break it down further!
Sources: Dispatching agents | LiveKit Docs | Authentication | LiveKit Docs | Agent dispatch | LiveKit Docsgreen-balloon-95599
06/26/2025, 8:01 PMtall-airline-16756
06/26/2025, 8:01 PMgreen-balloon-95599
06/26/2025, 8:04 PMtall-airline-16756
06/26/2025, 8:04 PMgreen-balloon-95599
06/26/2025, 8:05 PMtall-airline-16756
06/26/2025, 8:05 PMgreen-balloon-95599
06/26/2025, 8:06 PMgreen-balloon-95599
06/26/2025, 8:13 PM