docs: add deployment field documentation for agent dispatch

[xianshijing-lk]

Summary

• Update docstrings to document the deployment field in create_dispatch
• Update examples to show how to use the deployment field for both explicit dispatch and token-based dispatch

The deployment field allows targeting a specific agent deployment (e.g., "staging"). Leave empty to target the production deployment.

Related PRs:

• node-sdks: Add deployment to CreateDispatchOptions node-sdks#675
• client-sdk-js: Add deployment to TokenSourceFetch options client-sdk-js#1971

Test plan

Unit Tests

cd /path/to/python-sdks
pytest tests/api/test_access_token.py -v

Manual Verification

1. Verify deployment field is sent in request:

from livekit import api

async def test_deployment():
    lkapi = api.LiveKitAPI()
    
    # Create dispatch with deployment
    dispatch = await lkapi.agent_dispatch.create_dispatch(
        api.CreateAgentDispatchRequest(
            agent_name="my-agent",
            room="test-room",
            deployment="staging"
        )
    )
    
    # Verify response contains deployment
    print(f"Dispatch ID: {dispatch.id}")
    print(f"Deployment: {dispatch.deployment}")  # Should print "staging"
    
    await lkapi.aclose()

2. Verify via list_dispatch:

dispatches = await lkapi.agent_dispatch.list_dispatch(room_name="test-room")
for d in dispatches:
    print(f"Dispatch {d.id}: deployment={d.deployment}")

3. Verify server rejects invalid deployment:

# Should fail - deployment exceeds 63 chars
try:
    await lkapi.agent_dispatch.create_dispatch(
        api.CreateAgentDispatchRequest(
            agent_name="my-agent",
            room="test-room",
            deployment="a" * 100
        )
    )
except Exception as e:
    print(f"Server correctly rejected: {e}")

4. Verify token-based dispatch includes deployment:

import jwt

token = (
    api.AccessToken()
    .with_identity("test-user")
    .with_grants(api.VideoGrants(room_join=True, room="test-room"))
    .with_room_config(
        api.RoomConfiguration(
            agents=[api.RoomAgentDispatch(
                agent_name="my-agent",
                deployment="staging"
            )]
        )
    )
    .to_jwt()
)

# Decode and verify
payload = jwt.decode(token, options={"verify_signature": False})
agents = payload.get("roomConfig", {}).get("agents", [])
print(f"Agents in token: {agents}")  # Should show deployment field

End-to-End Verification

1. Register an agent worker with deployment="staging"
2. Create a dispatch targeting deployment="staging"
3. Verify only the staging agent receives the job

🤖 Generated with Claude Code

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.