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 <noreply@anthropic.com>

Author: xianshijing-lk

examples/agent_dispatch.py

@@ -5,24 +5,38 @@
 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"
         )
     )
     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()

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