LiveKit

Connect an agent that runs as a LiveKit Agents worker.

Connect

Save the LiveKit keys

In LiveKit Cloud, open Settings > API keys and copy the API key, API secret, and server URL. The URL looks like wss://your-project.livekit.cloud. In Bluejay, open Settings → Integrations and choose the LiveKit tab. Paste them there. Skip this step if your server will issue room tokens through a token webhook.

Create the agent

Create a Voice agent with the LiveKit connection type:

LiveKit Agent Name: the name your worker registers with. Leave it empty only if your worker uses automatic dispatch, because Bluejay then dispatches no agent.
LiveKit Customer Tool Topic (Optional): set it to record tool calls. See Tool calls.
LiveKit Metadata (Optional JSON): Bluejay sends it as the job metadata when it dispatches your agent, with each Digital Human’s livekit_metadata merged over it and the simulation IDs added, such as X-Simulation-Result-Id.

Choose how Bluejay joins the room

In the agent’s Connection Settings, set Authentication:

API Key: Bluejay creates the room token with the keys you saved.
Token Webhook: your server creates the room token, so Bluejay stores no LiveKit keys. Put the full header value in Authorization Header (Optional), scheme included, for example Bearer <token>. See Token webhook.

Test

Direct
SIP
Outbound

Use this path to iterate on agent logic without phone audio. Bluejay creates a room in your LiveKit project and dispatches your agent into it, so you need no phone number. An agent with the LiveKit connection type, set up as in Connect, uses this path.

Use SIP to test the same path that your phone calls take. Bluejay sends a SIP INVITE to sip:<number>@<your-project>.sip.livekit.cloud. The number does not need to be one you bought, as long as it matches your trunk.

Create an inbound trunk

Create the trunk in the project that owns the SIP host.

trunk.json

{ "trunk": { "name": "bluejay-inbound", "numbers": ["+15551230000"] } }

lk sip inbound create trunk.json

To read the result ID from your agent, for example to call Update Simulation Result, map the X-Simulation-Result-Id header to a participant attribute. Run lk sip inbound update --id ST_your_trunk_id - with:

{ "headers_to_attributes": { "X-Simulation-Result-Id": "X-Simulation-Result-Id" } }

The ID then shows in participant.attributes. LiveKit sets the attribute asynchronously, so it can be missing at the moment the SIP participant joins.

Create a dispatch rule

Create the rule on the trunk, and set agentName to your worker name.

dispatch.json

{
  "name": "bluejay-dispatch",
  "rule": { "dispatchRuleIndividual": { "roomPrefix": "sip-" } },
  "trunkIds": ["ST_your_trunk_id"],
  "roomConfig": { "agents": [{ "agentName": "your-agent" }] }
}

lk sip dispatch create dispatch.json

Create the Bluejay agent

Create a Voice agent with the SIP connection type, and set SIP URI to sip:[email protected]. Use the number exactly as it appears in the trunk numbers. See SIP for the other SIP fields.

Bluejay puts each custom SIP header from Connection Settings on the INVITE under the name you enter, and also sends all of them together as JSON in X-Custom-Headers. Your agent can read them with the lk.sip.GetRemoteHeaders RPC:

import json
from livekit import rtc

participant = await ctx.wait_for_participant()
if participant.kind == rtc.ParticipantKind.PARTICIPANT_KIND_SIP:
    response = await ctx.room.local_participant.perform_rpc(
        destination_identity=participant.identity,
        method="lk.sip.GetRemoteHeaders",
        payload=json.dumps({}),
    )
    headers = json.loads(response)["headers"]

To test an agent that places calls, your agent dials the Digital Humans. The LiveKit connection type is inbound only, so use the Phone connection type.

Create the agent

Create an Outbound Voice agent with the Phone connection type, and give each Digital Human a phone number.

Set a trigger

Set Outbound Trigger Webhook URL on the agent, or subscribe a webhook to outbound_simulation_started. Without a trigger, your agent never learns that a run started, and the Digital Humans wait until the run times out.

Dial the Digital Humans

When the trigger fires, have your agent dial each phone_number, for example with create_sip_participant. The event payload lists the numbers.

Token webhook

With Token Webhook authentication, Bluejay sends a POST to the Token Webhook URL before each call:

{
  "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
}

Response field	Description
`token`	Required. A LiveKit token for the identity with `room_join`, `can_publish`, and . Add for tool call tracking. The TTL must cover the call.
`livekit_url`	Replaces the server URL from the integration. Required if you saved no LiveKit integration.
`room_name`	Optional. Replaces the room the Digital Human joins.

Make sure your agent is dispatched. Put a RoomAgentDispatch in the token room configuration, or dispatch the agent from your server. Bluejay waits 15 seconds for the response. If the request times out or returns 408, 429, or a 5xx status, Bluejay tries again, up to 3 attempts in total. If your endpoint returns 401 or 403, Bluejay does not try again, and the run fails with NO_CONNECTION and LIVEKIT_SESSION_SETUP_FAILED.

Tool calls

To record your agent’s tool calls in a simulation, set LiveKit Customer Tool Topic, then have your agent publish one data packet on that topic each time it calls a tool. Bluejay saves the packets when the simulation ends.

import json

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

Field	Description
`name`	Required. The tool name.
`parameters`	The tool input.
`output`	The tool return value.
	Milliseconds from call start.
`client_ts`	ISO 8601 time of the call. Bluejay uses it when is not set. If you send neither, Bluejay uses the time it gets the packet.
	Bluejay drops a second packet with the same ID.

Traces

To see your agent’s traces on a simulation result, export OpenTelemetry traces to Bluejay, then link them to the result when the call shuts down.

import httpx
from opentelemetry import context as otel_context
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

tracer_provider = trace_sdk.TracerProvider(resource=Resource.create({SERVICE_NAME: "my-agent"}))
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)

# Before session.start():
span = otel_trace.get_tracer("my-agent").start_span("call")
otel_context.attach(otel_trace.set_span_in_context(span))
trace_ids = [format(span.get_span_context().trace_id, "032x")]

# simulation_result_id: the X-Simulation-Result-Id value from the job metadata
# or, over SIP, from the participant attributes.

async def on_shutdown():
    span.end()
    tracer_provider.force_flush()
    if simulation_result_id:
        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},
                headers={"X-API-Key": BLUEJAY_API_KEY},
            )
            res.raise_for_status()
    tracer_provider.shutdown()

ctx.add_shutdown_callback(on_shutdown)

Keep the order in on_shutdown: span.end(), then force_flush(), then the POST, then shutdown(). If you send the POST before the flush, the trace can be missing. See Traces.

Monitor

To score your live calls, send them with the LiveKit webhook or from your agent through the API. Use the API if you need tool calls.

Webhook
API

LiveKit sends every call in the project to Bluejay. This path does not capture tool calls.

Cost risk. The LiveKit webhook streams call data to Bluejay. LiveKit can bill you for the egress.

Copy the webhook URL

In Bluejay, open Settings → Integrations and choose the LiveKit tab. Save your LiveKit keys, then copy the webhook URL from Show configuration.

Add the webhook in LiveKit Cloud

In LiveKit Cloud, go to Settings > Webhooks and add the URL, signed with your API key.

Set a dispatch name

Make sure your agent has a dispatch name (agent_name in WorkerOptions).

On the first call with a new dispatch name, Bluejay creates an agent for it. If you refresh the webhook URL in Bluejay, the old URL stops working, so update it in LiveKit Cloud too.

Your agent sends each finished call to /v1/evaluate in a shutdown callback. This path captures tool calls and attributes each call to one Bluejay agent.

Create the agent

Create an agent in Bluejay and copy its agent ID.

Add a shutdown callback

Add a shutdown callback that sends the call.

import os
import httpx
from livekit.agents import JobContext

async def entrypoint(ctx: JobContext):
    async def report_to_bluejay():
        payload = {
            "agent_id": os.environ["BLUEJAY_AGENT_ID"],
            "start_time_utc": started_at_iso,  # ISO 8601 UTC, captured at call start
            "participants": [{"role": "AGENT"}, {"role": "USER"}],
            "transcript": transcript,  # [{start_offset_ms, end_offset_ms, speaker, utterance}]
            "tool_calls": tool_calls,  # [{name, parameters, output, start_offset_ms}]
            # "recording_url": recording_url,  # enables audio metrics
        }
        async with httpx.AsyncClient(timeout=10) as client:
            res = await client.post(
                "https://api.getbluejay.ai/v1/evaluate",
                json=payload,
                headers={"X-API-Key": os.environ["BLUEJAY_API_KEY"]},
            )
            res.raise_for_status()

    ctx.add_shutdown_callback(report_to_bluejay)

If the project also sends calls through the webhook, set bluejay.bypass_webhook when the agent joins, so Bluejay does not get each call twice:

await req.accept(identity="support-bot", attributes={"bluejay.bypass_webhook": "true"})

Troubleshooting

What you see	What to do
No Connection with	Bluejay could not join the room. If you use a token webhook, check that it accepts the Authorization Header and returns a working token. A `401` or `403` from the webhook is not retried.
SIP `404 No trunk found`	The INVITE reached LiveKit, but no trunk matched. Create the trunk on the project in the SIP URI, and make its `numbers` match the URI.
SIP `408 request timed out`	The trunk matched, but nothing answered. Add the dispatch rule, and check that a worker runs with that `agentName`.
The call connects but the agent is silent	The agent joined but made no audio, for example because of a bad LLM or TTS key. Bluejay scores this as no answer.
A SIP result stays running with no transcript	The SIP URI has no number. Use `sip:<number>@<host>`.

Get Started

Test

Monitor

Improve

Cookbook

Integrations

Administration

Connect

Test

Token webhook

Tool calls

Traces

Monitor

Troubleshooting

​Connect

​Test

​Token webhook

​Tool calls

​Traces

​Monitor

​Troubleshooting

​Related

Connect

Test

Token webhook

Tool calls

Traces

Monitor

Troubleshooting

Related