Dispatch Agents

Dynamically assign your AI agents to meetings using the VideoSDK dispatch API. This API supports dispatching for both self-hosted agents created with the Agents SDK and agents managed through the VideoSDK dashboard (Agent Runtime).

How It Works

1. Your app calls the dispatch API
2. VideoSDK backend finds an available server
3. Server spawns a job/process to join the meeting
4. Agent starts and begins processing in the meeting

API Usage

Endpoint

POST https://api.videosdk.live/v2/agent/dispatch

Request Body Parameters

Parameter	Type	Required	Description
meetingId	string	Yes	The ID of the meeting to which the agent should be dispatched.
agentId	string	Yes	The ID of the agent to dispatch.
metadata	object	No	Optional metadata to pass to the agent, such as variables.
versionId	string	No	The specific version of a dashboard-managed agent to dispatch. If omitted, the latest deployed version is used. Not for self-hosted agents.

Example Request

curl -X POST "https://api.videosdk.live/v2/agent/dispatch" \
  -H "Authorization: YOUR_VIDEOSDK_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "meetingId": "xxxx-xxxx-xxxx",
    "agentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "metadata": {
        "variables":[
            {
                "name":"fname",
                "value":"ankit"
            }
        ]
    },
    "versionId":"abcd-abcd-abcd-abcd"
  }'

Responses

On Success

A successful request will return a confirmation that the dispatch has been initiated.

{
    "message": "Agent dispatch requested successfully.",
    "data": {
        "success": true,
        "status": "assigned",
        "roomId": "xxxx-xxxx-xxxx",
        "agentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
}

On Error

If the dispatch fails, you will receive one of the following error messages:

No Workers Available

This error occurs when no servers and agents are configured to handle the request.

{
    "message": "No workers available"
}

No Workers Registered

This error is specific to self-hosted (Agents SDK) agents. It means that while the agentId is valid, no server has been configured for the specific agentId.

{
    "message": "No workers have registered with agentId 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'"
}

Agent Not Deployed

This error is specific to dashboard-managed agents. It indicates that the agent exists but has no deployed versions available for dispatch or the specific version user wants to dispatch is not deployed .

{
    "message": "No agent is deployed with agentId 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'"
}

Dispatching Your Agent

The prerequisites for dispatching an agent depend on how it was created.

For Self-Hosted Agents (Agents SDK)

If you created your agent using the Python Agents SDK, you are responsible for hosting it. Your server must be:

1. Registered: The server must be configured with register=True.
2. Connected: The server must be running and connected to the VideoSDK backend.
3. Available: The server must have the capacity to handle new jobs.

The versionId parameter is not applicable in this scenario.

Server Configuration Example

from videosdk.agents import Options

options = Options(
    agent_id="MyAgent",        # Must match agentId in API call
    register=True,             # Required for dispatch
    max_processes=10,
    load_threshold=0.75,
)

For Dashboard-Managed Agents (Agent Runtime)

If you created your agent using the dashboard interface, VideoSDK manages the hosting for you. The only prerequisite is that your agent must be deployed.

• You can deploy your agent via the dashboard.
• You can use the optional versionId parameter in your dispatch request to specify which deployed version of the agent to use.
• If versionId is not provided, the latest deployed version will be dispatched by default.

Code Examples

Python

import requests

def dispatch_agent(auth_token, meeting_id, agent_id, metadata=None, version_id=None):
    url = "https://api.videosdk.live/v2/agent/dispatch"
    headers = {
        "Authorization": auth_token,
        "Content-Type": "application/json"
    }
    payload = {
        "meetingId": meeting_id,
        "agentId": agent_id,
    }
    if metadata:
        payload["metadata"] = metadata
    if version_id:
        payload["versionId"] = version_id

    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# Usage
result = dispatch_agent("your-token", "room-123", "MyAgent")

JavaScript

async function dispatchAgent(authToken, meetingId, agentId, metadata, versionId) {
  const url = "https://api.videosdk.live/v2/agent/dispatch";
  const headers = {
    Authorization: authToken,
    "Content-Type": "application/json",
  };
  
  const body = {
    meetingId,
    agentId,
  };

  if (metadata) {
    body.metadata = metadata;
  }
  if (versionId) {
    body.versionId = versionId;
  }

  const response = await fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
  });

  return response.json();
}

// Usage
dispatchAgent("your-token", "room-123", "MyAgent");