From 8032d30eb1562de6cc7e6d2d57623a85afcb5e64 Mon Sep 17 00:00:00 2001 From: shijing xian Date: Wed, 17 Jun 2026 10:07:13 +0800 Subject: [PATCH 1/2] docs: add deployment field documentation for agent dispatch Update docstrings and examples to document the deployment field for agent dispatch. The deployment field allows targeting a specific agent deployment (e.g., "staging"). Leave empty to target the production deployment. Co-Authored-By: Claude Opus 4.5 --- examples/agent_dispatch.py | 33 ++++++++++++++++--- .../livekit/api/agent_dispatch_service.py | 4 ++- 2 files changed, 31 insertions(+), 6 deletions(-) diff --git a/examples/agent_dispatch.py b/examples/agent_dispatch.py index c53c4ae2..2bc24c20 100644 --- a/examples/agent_dispatch.py +++ b/examples/agent_dispatch.py @@ -5,17 +5,21 @@ agent_name = "test-agent" """ -This example demonstrates how to have an agent join a room -without using the automatic dispatch. In order to use this -feature, you must have an agent running with `agent_name` set -when defining your WorkerOptions. A dispatch requests the +This example demonstrates how to have an agent join a room +without using the automatic dispatch. In order to use this +feature, you must have an agent running with `agent_name` set +when defining your WorkerOptions. A dispatch requests the agent to enter a specific room with optional metadata. + +You can also specify a `deployment` to target a specific agent deployment. +Leave empty to target the production deployment. """ async def create_explicit_dispatch(): lkapi = api.LiveKitAPI() + # Create a dispatch targeting the production deployment (default) dispatch = await lkapi.agent_dispatch.create_dispatch( api.CreateAgentDispatchRequest( agent_name=agent_name, room=room_name, metadata="my_metadata" @@ -23,6 +27,16 @@ async def create_explicit_dispatch(): ) print("created dispatch", dispatch) + # Create a dispatch targeting a specific deployment (e.g., "staging") + # dispatch = await lkapi.agent_dispatch.create_dispatch( + # api.CreateAgentDispatchRequest( + # agent_name=agent_name, + # room=room_name, + # metadata="my_metadata", + # deployment="staging", + # ) + # ) + dispatches = await lkapi.agent_dispatch.list_dispatch(room_name=room_name) print(f"there are {len(dispatches)} dispatches in {room_name}") await lkapi.aclose() @@ -33,6 +47,9 @@ async def create_explicit_dispatch(): to new rooms. If you want that agent to be dispatched to a new room as soon as the participant connects, you can set the RoomConfiguration with the agent definition in the access token. + +You can also specify a `deployment` in the RoomAgentDispatch to target a specific +agent deployment. Leave empty to target the production deployment. """ @@ -43,7 +60,13 @@ async def create_token_with_agent_dispatch() -> str: .with_grants(api.VideoGrants(room_join=True, room=room_name)) .with_room_config( api.RoomConfiguration( - agents=[api.RoomAgentDispatch(agent_name="test-agent", metadata="my_metadata")], + agents=[ + api.RoomAgentDispatch( + agent_name="test-agent", + metadata="my_metadata", + # deployment="staging", # Optional: target a specific deployment + ) + ], ), ) .to_jwt() diff --git a/livekit-api/livekit/api/agent_dispatch_service.py b/livekit-api/livekit/api/agent_dispatch_service.py index 0c8f1d7a..375cc527 100644 --- a/livekit-api/livekit/api/agent_dispatch_service.py +++ b/livekit-api/livekit/api/agent_dispatch_service.py @@ -35,7 +35,9 @@ async def create_dispatch(self, req: CreateAgentDispatchRequest) -> AgentDispatc To use explicit dispatch, your agent must be registered with an `agentName`. Args: - req (CreateAgentDispatchRequest): Request containing dispatch creation parameters + req (CreateAgentDispatchRequest): Request containing dispatch creation parameters. + The request can include an optional `deployment` field to target a specific + deployment. Leave empty to target the production deployment. Returns: AgentDispatch: The created agent dispatch object From 0b56ea1b5adf4535a0f330b674a846533916744b Mon Sep 17 00:00:00 2001 From: shijing xian Date: Wed, 17 Jun 2026 13:23:50 +0800 Subject: [PATCH 2/2] Simplify deployment example in agent_dispatch.py Show deployment as a commented optional parameter within the active example rather than a separate commented-out block. Co-Authored-By: Claude Opus 4.5 --- examples/agent_dispatch.py | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/examples/agent_dispatch.py b/examples/agent_dispatch.py index 2bc24c20..cbbadf49 100644 --- a/examples/agent_dispatch.py +++ b/examples/agent_dispatch.py @@ -19,24 +19,16 @@ async def create_explicit_dispatch(): lkapi = api.LiveKitAPI() - # Create a dispatch targeting the production deployment (default) dispatch = await lkapi.agent_dispatch.create_dispatch( api.CreateAgentDispatchRequest( - agent_name=agent_name, room=room_name, metadata="my_metadata" + agent_name=agent_name, + room=room_name, + metadata="my_metadata", + # deployment="staging", # Optional: target a specific deployment ) ) print("created dispatch", dispatch) - # Create a dispatch targeting a specific deployment (e.g., "staging") - # dispatch = await lkapi.agent_dispatch.create_dispatch( - # api.CreateAgentDispatchRequest( - # agent_name=agent_name, - # room=room_name, - # metadata="my_metadata", - # deployment="staging", - # ) - # ) - dispatches = await lkapi.agent_dispatch.list_dispatch(room_name=room_name) print(f"there are {len(dispatches)} dispatches in {room_name}") await lkapi.aclose()