Skip to main content

​
Overview

LiveKit is a real-time voice and video infrastructure platform. Preclinical connects via WebRTC to test your LiveKit agents.

​
Configuration

To add a LiveKit integration, you’ll need:
FieldDescription
Server URLYour LiveKit server URL (wss://…)
API KeyLiveKit API key
API SecretLiveKit API secret
Agent NameName of the agent to dispatch

​
Optional Settings

FieldDescriptionDefault
Room nameCustom room name (auto-generated if not provided)Auto
Auto cleanupClean up room after testYes
TimeoutMaximum test duration2 minutes

​
Setup Steps

1

Get LiveKit Credentials

  1. Go to LiveKit Cloud
  2. Navigate to your project Settings
  3. Copy your Server URL, API Key, and API Secret
2

Deploy Your Agent

Ensure your LiveKit agent is deployed and registered with a dispatch name.
# Example agent registration
@agent.on("agent_started")
async def on_started():
    await agent.register("healthcare-agent")
3

Add Integration

In Preclinical, create a new agent with your LiveKit credentials and agent name.

​
How It Works

  1. Preclinical creates a LiveKit room for the test
  2. Your agent is dispatched to the room
  3. The pen tester joins and conducts the conversation via WebRTC
  4. Transcript is captured and the room is cleaned up

​
Features

Agent Dispatch

Automatic agent dispatch with retry and health checks

Room Cleanup

Automatic room cleanup after test completion

Concurrency Control

Configurable concurrent connection limits

Comprehensive Metrics

Connection time, agent join time, room duration

​
Metrics Captured

MetricDescription
Connection timeTime to establish WebRTC connection
Agent join timeTime for agent to join room
Turn countNumber of conversation turns
Room durationTotal room lifetime

​
Error Handling

​
Common Errors

ErrorCauseResolution
Connection timeoutNetwork issuesVerify LiveKit URL is correct
Agent not dispatchedAgent offlineCheck agent is deployed and registered
Room not foundInvalid roomLet Preclinical auto-generate rooms
Auth failedInvalid credentialsVerify API key and secret

​
Room Cleanup

After each test, Preclinical automatically:
  1. Lists all participants in the room
  2. Removes each participant
  3. Deletes the room
Set auto cleanup to “No” in config if you want to inspect rooms after tests.

​
Troubleshooting

  • Verify agent is deployed and running
  • Check agent is registered with correct name
  • Ensure agent can connect to LiveKit server
  • Check agent logs for errors
  • Verify LiveKit URL format (must be wss://)
  • Check API key/secret are correct
  • Ensure LiveKit project is active
  • Reduce concurrency limit
  • Check agent processing time

​
Next Steps

Run a Test

Execute your first test run

Pipecat Integration

Similar WebRTC setup for Pipecat