LiveKit — Direct Connection

If your agent runs on the LiveKit Agents framework, this is the simplest way to simulate calls. Bluejay manages room and token creation and places the Digital Human directly in the room with your agent.

This method is for inbound agents: your agent answers and the Digital Human starts the conversation. If your agent places calls, use Outbound agents instead.

How it connects

Bluejay creates a room inside your LiveKit Cloud project, dispatches your agent into it, then mints a token and joins the Digital Human to the same room. No SIP or trunks involved.

Quick start

Add your LiveKit credentials — in Settings → Integrations, add your LiveKit api_key, api_secret, and url.
Set your agent name — in Agent Settings → Connection, enter the name your agent registers with, or leave it blank to dispatch your default agent.

Create a simulation — go to the Simulations page, click Create in the top right, select your agent, and add or auto-generate Digital Human personas.
Run it — in the Simulations tab, click Run on the simulation, then click Run calls (the button shows the call count, e.g. “Run 3 calls”).
Review results — transcripts, recordings, and metric scores.

Token webhook

If you’d rather not store your LiveKit API key and secret with Bluejay, set a Token Webhook URL in Agent Settings → Connection instead. Before each simulated call, Bluejay POSTs to your endpoint and your side mints the room token.

Request

{
  "room_name": "test-room-812192",
  "participant_identity": "digital-human-812192",
  "agent_name": "your-agent-name",
  "agent_metadata": { "any": "metadata you configured" },
  "sim_conversation_id": 812192
}

If you set an Authorization value in the connection settings, Bluejay stores it encrypted and sends it verbatim as the Authorization header on this POST (e.g. Bearer <token>). No other authentication is added.

Response

Field	Type	Description
`token`	string	Required. A LiveKit token granting `room_join`, `can_publish`, and `can_subscribe` for the requested identity (plus `can_publish_data` if you use tool call tracking), with a TTL covering the whole call
`livekit_url`	string	Optional. Overrides the LiveKit server URL; falls back to your org integration’s URL
`room_name`	string	Optional. Overrides the room the digital human joins, for tokens bound to a different room

In webhook mode you own agent dispatch: either bake a RoomAgentDispatch into the token’s room configuration using the agent_name and agent_metadata we send, or dispatch your agent server-side when you handle the request.

Failure behavior

If your endpoint (or a proxy in front of it) responds 401 or 403, Bluejay does not retry. The run fails immediately with status NO_CONNECTION and error code LIVEKIT_SESSION_SETUP_FAILED, and the error message states whether the configured Authorization header was sent. The header is sent exactly as configured, so a 401 means your side rejected that exact value. Timeouts and 5xx responses are retried up to 3 times before the run fails.

Room metadata

Optionally include metadata on the room at creation: add JSON to the metadata field in Agent Connection settings.

Tool call tracking

Bluejay can capture tool calls your agent makes during a simulation. Publish a data packet to a LiveKit topic and Bluejay ingests it. In Agent Connection settings, set the LiveKit Customer Tool Topic field to the topic your code publishes to (e.g. customer.tool.calls). Then, whenever your agent invokes a tool:

import json
from livekit import rtc

async def report_tool_call(room: rtc.Room, tool_name: str, parameters: dict, output):
    payload = json.dumps({
        "name": tool_name,
        "parameters": parameters,
        "output": output,
    }).encode()
    await room.local_participant.publish_data(payload, topic="customer.tool.calls")

Only name is required; everything else is optional:

Field	Type	Description
`name`	string	Required. The tool that was invoked
`parameters`	object	Input parameters passed to the tool
`output`	any	Return value of the tool
`start_offset_ms`	integer	Milliseconds from call start (Bluejay calculates if omitted)

Bluejay buffers packets during the call and persists them when the simulation ends.

Sending traces to Bluejay

Export OpenTelemetry traces from your LiveKit agent so they’re used and displayed in simulation evaluations.

from opentelemetry.sdk import trace as trace_sdk
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.resources import SERVICE_NAME, Resource
from livekit.agents.telemetry import set_tracer_provider
import opentelemetry.trace as otel_trace

resource = Resource.create({SERVICE_NAME: "my-agent"})
tracer_provider = trace_sdk.TracerProvider(resource=resource)
tracer_provider.add_span_processor(
    SimpleSpanProcessor(
        OTLPSpanExporter(
            "https://otlp.getbluejay.ai/v1/traces",
            headers={"X-API-KEY": BLUEJAY_API_KEY},
        )
    )
)

set_tracer_provider(tracer_provider)
otel_trace.set_tracer_provider(tracer_provider)

After session.start(), capture the trace ID from the active span:

import opentelemetry.trace as otel_trace

await session.start(agent=MyAgent(), room=ctx.room)

current_span = otel_trace.get_current_span()
span_ctx = current_span.get_span_context()
if span_ctx.is_valid:
    trace_ids = [format(span_ctx.trace_id, "032x")]

Linking data to simulation results

POST trace IDs and tool calls at shutdown via ctx.add_shutdown_callback():

async def on_shutdown():
    span.end()
    tracer_provider.force_flush()

    if simulation_result_id and (trace_ids or tool_calls):
        async with httpx.AsyncClient(timeout=10) as client:
            res = await client.post(
                "https://api.getbluejay.ai/v1/update-simulation-result",
                json={
                    "simulation_result_id": simulation_result_id,
                    "trace_ids": trace_ids,
                    "tool_calls": tool_calls,
                },
                headers={"X-API-Key": BLUEJAY_API_KEY},
            )
            res.raise_for_status()

    tracer_provider.shutdown()

ctx.add_shutdown_callback(on_shutdown)

Ordering matters: span.end() → force_flush() → POST → tracer_provider.shutdown(). If you POST before ending the span, the trace may not be in Bluejay yet.

For the full traces concept, see the Traces documentation.

Getting Started

Key Concepts

Test

Monitor

Integrations

Administration

LiveKit — Direct Connection

How it connects

Quick start

Token webhook

Request

Response

Failure behavior

Room metadata

Tool call tracking

Sending traces to Bluejay

Linking data to simulation results

​How it connects

​Quick start

​Token webhook

​Request

​Response

​Failure behavior

​Room metadata

​Tool call tracking

​Sending traces to Bluejay

​Linking data to simulation results

How it connects

Quick start

Token webhook

Request

Response

Failure behavior

Room metadata

Tool call tracking

Sending traces to Bluejay

Linking data to simulation results