LiveKit

​

Overview

​

Dispatch Modes

• Automatic dispatch (the default): If your worker calls WorkerOptions without an agent_name, LiveKit auto-joins it to every new room created in your project. Most simple, single-agent setups use this mode, and no extra Coval configuration is needed.
• Explicit dispatch: If your worker’s code passes an agent_name to WorkerOptions (LiveKit’s Python/Node agents SDK), it opts out of auto-join. It will only join a room when that room’s access token embeds the same name via room_config.agents[].agent_name.

• If it passes an agent_name argument, your agent uses explicit dispatch—set Coval’s Agent Name field to match.
• If it doesn’t, your agent uses automatic dispatch and will auto-join Coval’s simulation rooms with no further configuration.

​

Configuration Requirements

​

Generate Token Endpoint

• Field: generate_token_endpoint
• Type: String (required)
• Purpose: Endpoint for generating LiveKit access tokens
• Format: Valid HTTPS URL
• Example: https://your-api.com/livekit/token

{
  "room_name": "uuid-generated-by-coval",
  "participant_name": "simulated_user"
}

{
  "room_name": "uuid-generated-by-coval",
  "participant_name": "simulated_user",
  "room_config": {
    "agents": [
      { "agent_name": "voice-assistant" }
    ]
  }
}

from livekit.api import AccessToken, VideoGrants, RoomConfiguration, RoomAgentDispatch

def generate_token(request_body):
    room_config = request_body.get("room_config")
    token = (
        AccessToken()
        .with_identity(request_body["participant_name"])
        .with_grants(VideoGrants(room_join=True, room=request_body["room_name"]))
    )
    if room_config:
        token = token.with_room_config(RoomConfiguration(**room_config))
    return token.to_jwt()

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "serverUrl": "wss://your-livekit-server.com",
  "room_name": "uuid-generated-by-coval"
}

​

LiveKit URL

• Field: livekit_url
• Type: String (required)
• Purpose: LiveKit server WebSocket URL
• Format: Valid WebSocket URL (wss://)
• Example: wss://your-livekit-server.com

​

Generate Token Headers

• Field: generate_token_headers
• Type: String (optional)
• Purpose: HTTP headers for token generation requests
• Format: Valid JSON string
• Example: {"X-Coval-Simulation-Id": "{{simulation_id}}"}

​

Sandbox ID (Development Token Server ID)

• Field: sandbox_id
• Type: String (optional, testing only)
• Purpose: Identifier for LiveKit Cloud’s hosted, dev-only token-minting API—what LiveKit’s own UI now labels the Development Token Server, formerly branded Sandbox
• When to use: If your generate_token_endpoint points at LiveKit’s hosted Sandbox/Development Token Server API rather than a backend you run yourself
• When to skip: If you’re already running your own token-minting backend (LiveKit’s recommended production setup), skip this field entirely

​

LiveKit Agent Name

• Field: livekit_agent_name
• Type: String (optional)
• Purpose: Name identifier for the LiveKit agent
• Format: String identifier
• Example: "voice-assistant", "video-agent"

​

Custom Payload Fields

• Field: token_request_payload
• Type: String (optional)
• Purpose: Additional fields to include in the token request
• Format: Valid JSON string
• Example: {"agent_variant": "sales", "language": "en"}

​

Setup Instructions

1. Set up a token generation endpoint that accepts POST requests
2. Configure your endpoint to return tokens with the correct room permissions
3. Enter your LiveKit server WebSocket URL
4. (Optional) Add authentication headers if your endpoint requires them
5. Test the connection by launching a simulation

​

Sending Traces

​

Technical Details

​

Token Generation Flow

1. Coval generates a unique room name (UUID) for each simulation
2. Coval sends a POST request to your token endpoint with the room name
3. Your endpoint generates a LiveKit JWT token with room access permissions
4. Your endpoint should also dispatch your agent to join the same room
5. Coval joins the room using the returned token
6. Coval waits for your agent to join (on_first_participant_joined event)
7. Conversation simulation begins

​

Accepted Response Field Names

​

Troubleshooting

​

Common Issues

• Check endpoint accessibility and authentication
• Verify your endpoint returns valid JSON with a token field
• Ensure HTTPS is properly configured

• Verify LiveKit server URL starts with wss://
• Check that serverUrl is included in your token response
• Confirm your LiveKit server is running and accessible

• You’re using explicit dispatch (your worker registered with an agent_name) but Coval’s Agent Name field is unset or doesn’t match. Set livekit_agent_name to the exact name your worker passed to WorkerOptions.
• If Agent Name is set and matches, confirm your token endpoint actually embeds the incoming room_config into the minted token (e.g. via RoomConfiguration/RoomAgentDispatch)—see Generate Token Endpoint. Receiving room_config in the request isn’t enough; your endpoint must put it into the token itself, or dispatch will silently fail even though token generation succeeds.
• Confirm the token response’s room name matches the room your worker actually expects to join.
• Check your worker’s logs for a dispatch request—if it never receives one, double-check the Agent Name value for typos.

• Ensure your agent dispatch system receives the room_name from token requests
• Verify your agent is running and connected to LiveKit
• Check that the token grants access to the correct room

• Coval waits for your agent to join before starting
• If your agent doesn’t join, the simulation will timeout
• Check your agent logs for connection errors

• Verify your response includes a recognized token field name
• Check that the token value is a non-empty string
• Ensure response Content-Type is application/json

​

Running Components Locally

ngrok http 8888
# Use the generated https:// URL as your token endpoint