Connecting to LiveKit - Tuner Documentation

This guide covers both the Python SDK (tuner-livekit-sdk) and the Node.js SDK (@usetuner.ai/livekit-sdk). Use the language switcher below to view the guide for your stack.

Video tutorial

Prerequisites

An active Tuner account
A Tuner agent with provider LiveKit
A Tuner API key, your workspace ID and the agent’s Agent Remote ID. See API keys.
A LiveKit Agents project, either:
- Python running LiveKit Agents v1.4 or later, or
- Node.js 18+ running @livekit/agents v1.4 or later with @livekit/rtc-node v0.13 or later.

Overview

The Tuner LiveKit SDK captures session data from your LiveKit agent and sends it to Tuner when the call ends. You don’t make any API calls yourself. It ships as a Python package and a Node.js package that share the same wire format.

Install the SDK

Add the package to your project.

Set your credentials

Configure your Tuner API key, workspace ID, and Agent Remote ID.

Add the plugin

Add two lines to your entrypoint.

Enable simulation

Required only if you use Call Simulation. See Enable simulation.

Python
Node.js

Step 1: Install the SDK

pip install tuner-livekit-sdk

Requirements: Python ≥ 3.10, livekit-agents >= 1.4, aiohttp >= 3.9. The package also installs tuner-langchain >= 0.1.1 as a dependency.To forward OpenTelemetry traces as well, install the traces extra instead. See OpenTelemetry traces.

pip install 'tuner-livekit-sdk[traces]'

Step 2: Set your credentials

You can configure credentials via environment variables or pass them directly in code.

Environment variables
Inline in code

export TUNER_API_KEY="tr_api_..."
export TUNER_WORKSPACE_ID="123"
export TUNER_AGENT_ID="fa4da74c-..."

Variable	Required	Description
`TUNER_API_KEY`	✅	Bearer token (starts with `tr_api_`)
`TUNER_WORKSPACE_ID`	✅	Your Tuner workspace ID
`TUNER_AGENT_ID`	✅	Agent Remote ID from Agent Settings > Agent Connection. This is a UUID, not your agent’s display name.
`TUNER_BASE_URL`	No	API base URL (default: `https://api.usetuner.ai`)

TunerPlugin(
    session, ctx,
    api_key="tr_api_...",
    workspace_id=123,
    agent_id="fa4da74c-...",
)

Use the Agent Remote ID from Agent Settings > Agent Connection, not your agent’s display name. It is a UUID (for example fa4da74c-...). Copy your value from the Tuner dashboard.

Step 3: Add the plugin

Import TunerPlugin and add it right after creating your AgentSession, before calling session.start():

from tuner import TunerPlugin

async def entrypoint(ctx: JobContext):
    session = AgentSession(...)
    TunerPlugin(session, ctx)          # wires itself automatically
    await session.start(...)

The plugin listens to session events and submits call data to Tuner when the session ends.

Step 1: Install the SDK

npm install @usetuner.ai/livekit-sdk

Requirements: Node 18+, @livekit/agents >= 1.4.0, @livekit/rtc-node >= 0.13.0

Step 2: Set your credentials

You can configure credentials via environment variables or pass them directly in code.

Environment variables
Inline in code

export TUNER_API_KEY="tr_api_..."
export TUNER_WORKSPACE_ID="123"
export TUNER_AGENT_ID="fa4da74c-..."

Variable	Required	Description
`TUNER_API_KEY`	✅	Bearer token (starts with `tr_api_`)
`TUNER_WORKSPACE_ID`	✅	Your Tuner workspace ID
`TUNER_AGENT_ID`	✅	Agent Remote ID from Agent Settings > Agent Connection. This is a UUID, not your agent’s display name.
`TUNER_BASE_URL`	No	API base URL (default: `https://api.usetuner.ai`)

new TunerPlugin(session, ctx, {
  apiKey: 'tr_api_...',
  workspaceId: 123,
  agentId: 'fa4da74c-...',
});

Use the Agent Remote ID from Agent Settings > Agent Connection, not your agent’s display name. It is a UUID (for example fa4da74c-...). Copy your value from the Tuner dashboard.

Step 3: Add the plugin

Import TunerPlugin and add it right after creating your AgentSession, before calling session.start():

import { TunerPlugin } from '@usetuner.ai/livekit-sdk';
import { voice, type JobContext } from '@livekit/agents';

export default async function entry(ctx: JobContext) {
  const session = new voice.AgentSession({ /* ... */ });
  new TunerPlugin(session, ctx);             // wires itself automatically
  await session.start({ agent, room: ctx.room });
}

The plugin listens to session events and submits call data to Tuner when the session ends.

Enable simulation

Required for Call Simulation. Skip it otherwise.

Inbound

Tuner calls your agent over SIP.

SDK	Version
Python, `tuner-livekit-sdk`	0.1.11 or later
Node.js, `@usetuner.ai/livekit-sdk`	0.5.6 or later

Add your agent’s SIP URI in Agent Settings > Simulation Setup. Get it from your SIP provider, then see Set up inbound simulation.
Run your agent. There is nothing to add in code.

If a carrier such as Twilio or Telnyx sits between Tuner and LiveKit, also follow Carrier in front of LiveKit.

How Tuner links the call

Tuner puts two IDs on each simulated call: the SIP Call-ID and an X-Correlation-Id header. The plugin reads both from the SIP participant and sends them with the call report. Tuner links the call on either one. When Tuner calls LiveKit directly, the Call-ID links it. Behind a carrier, the Call-ID changes and the header links it.See How simulated calls are linked.

Older Python SDK versions

`tuner-livekit-sdk`	Sends	Direct to LiveKit	Behind a carrier
0.1.11 or later	Call-ID and header	Links	Links
0.1.5 to 0.1.10	Call-ID	Links	Doesn’t link
Before 0.1.5	Nothing for simulation	Doesn’t link	Doesn’t link

To upgrade, install 0.1.11 or later. No code changes are needed.

Outbound

Your agent calls a Simulated Caller at a SIP URI that Tuner sends to your trigger endpoint.

Configure the trigger endpoint in Agent Settings > Simulation Setup. See Set up outbound simulation.
Pass the SIP URI your agent dialed as recipient, exactly as Tuner sent it.

Python
Node.js

Requires tuner-livekit-sdk 0.1.7 or later.

TunerPlugin(
    session, ctx,
    recipient=dialed_sip_uri,   # the SIP URI Tuner sent, unchanged
)

new TunerPlugin(session, ctx, {
  recipient: dialedSipUri,   // the SIP URI Tuner sent, unchanged
});

If the plugin starts before your agent knows the SIP URI, report it later with attach_sip. This needs tuner-livekit-sdk 0.1.12 or @usetuner.ai/livekit-sdk 0.5.6.

Python
Node.js

plugin.attach_sip(recipient=dialed_sip_uri)

plugin.attachSip(null, { recipient: dialedSipUri });

Carrier in front of LiveKit

Use this if a carrier such as Twilio or Telnyx sits between Tuner and LiveKit. Skip it if Tuner calls LiveKit directly.

Prerequisite: your LiveKit inbound trunk must pass SIP headers to the agent. Set the trunk’s include_headers option to SIP_X_HEADERS or SIP_ALL_HEADERS. The default, SIP_NO_HEADERS, drops them. As an alternative, map the header explicitly with headers_to_attributes, using {"X-Correlation-Id": "sip.h.x-correlation-id"}.To check, run lk sip inbound list --json. The setting appears only in the JSON output.

Requires tuner-livekit-sdk 0.1.12 or later (Python) or @usetuner.ai/livekit-sdk 0.5.6 or later (Node.js). Set up the carrier so Tuner’s call reaches your webhook:

Twilio: Tuner dials a Twilio SIP Domain with a Credential List. Set the domain’s Voice URL to your webhook. Use the domain for inbound only, because a domain has one Voice URL. Twilio passes Tuner’s header to the webhook as SipHeader_X-Correlation-Id.
Telnyx: Tuner dials the SIP subdomain of a Call Control application, sip:<user>@<subdomain>.sip.telnyx.com. Set the subdomain to receive calls from anyone, and set the application’s webhook to your server. Transfer the call on the incoming call.initiated event. Telnyx puts Tuner’s header in the event’s custom_headers.

See SIP providers for the SIP URI and credentials. Add two calls where your webhook already sends the call to LiveKit: extract_sip reads Tuner’s data from the carrier’s webhook, and forward_to_sip builds the leg into LiveKit with Tuner’s header on it. Your server keeps its routing, signature checks and call control.

Twilio
Telnyx

Python
Node.js

from tuner.telephony import extract_sip, forward_to_sip

# in your existing Twilio voice webhook
params = dict(await request.form())
info = extract_sip(params, provider="twilio")

# sip_uri: the LiveKit SIP address you already dial
fwd = forward_to_sip(info, sip_uri="sip:agent@xxxx.sip.livekit.cloud")

# fwd.sip_uri: that address with Tuner's header attached, unchanged when there is none
response = VoiceResponse()
response.dial(answer_on_bridge=True).sip(fwd.sip_uri, username=..., password=...)

import { extractSip, forwardToSip } from '@usetuner.ai/livekit-sdk/telephony';

// in your existing Twilio voice webhook
const info = extractSip(params, { provider: 'twilio' });

// sipUri: the LiveKit SIP address you already dial
const fwd = forwardToSip(info, { sipUri: 'sip:agent@xxxx.sip.livekit.cloud' });

// fwd.sipUri: that address with Tuner's header attached, unchanged when there is none
response.dial({ answerOnBridge: true }).sip({ username, password }, fwd.sipUri);

Python
Node.js

from tuner.telephony import extract_sip, forward_to_sip

# event: the webhook JSON. sip_uri: the LiveKit SIP address you already dial
fwd = forward_to_sip(
    extract_sip(event, provider="telnyx"),
    sip_uri="sip:agent@xxxx.sip.livekit.cloud",
)

# fwd.transfer: {"to": ..., "custom_headers": [...]}, without headers when there is none
await telnyx_post(f"/calls/{call_control_id}/actions/transfer", {
    **fwd.transfer,
    "sip_auth_username": ..., "sip_auth_password": ...,
})

import { extractSip, forwardToSip } from '@usetuner.ai/livekit-sdk/telephony';

// event: the webhook JSON. sipUri: the LiveKit SIP address you already dial
const fwd = forwardToSip(extractSip(event, { provider: 'telnyx' }), {
  sipUri: 'sip:agent@xxxx.sip.livekit.cloud',
});

// fwd.transfer: { to, custom_headers }, without headers when there is none
await telnyxPost(`/calls/${encodeURIComponent(callControlId)}/actions/transfer`, {
  ...fwd.transfer,
  sip_auth_username: '...',
  sip_auth_password: '...',
});

You can call forward_to_sip on every call. Without Tuner’s header, it returns your address unchanged. A malformed header is dropped with a warning on the tuner.telephony logger, and the call still connects. The SDK doesn’t check the carrier’s webhook signature, so keep your own check.

Why a carrier needs this

The carrier opens a new SIP leg into LiveKit with its own Call-ID, and doesn’t copy Tuner’s X-Correlation-Id header onto that leg. forward_to_sip forwards the header, and the trunk setting lets it reach your agent. The plugin then sends it to Tuner, which links the call. For the general rule, see How simulated calls are linked.The SDK knows where each carrier puts Tuner’s data (Twilio’s SipHeader_ fields, Telnyx’s custom_headers), so the code is the same for every carrier. Only the provider name changes.

How the header travels

If the call doesn't link

The call still connects and your agent still talks. In the run it shows Unreported. The header can be lost in two places:

Your webhook	LiveKit trunk	Result
Uses `forward_to_sip`	`SIP_X_HEADERS` or `SIP_ALL_HEADERS`	Links
Uses `forward_to_sip`	`SIP_NO_HEADERS` (the default)	Doesn’t link. The trunk drops the header.
Dials a plain SIP address	`SIP_X_HEADERS` or `SIP_ALL_HEADERS`	Doesn’t link. The carrier drops the header.
Dials a plain SIP address	`SIP_NO_HEADERS` (the default)	Doesn’t link. The carrier drops the header.

The header also can’t link the call if another worker with the same agent name takes the job and reports to a different Tuner agent. Give each agent’s worker its own name.

Support another carrier

Write a provider with a name, an extract method that reads the webhook payload into a SipInfo, and a forward_to_sip method that returns a Forward. Register it once. Then pass its name as provider.

Python
Node.js

from tuner.telephony import Forward, SipInfo, register_provider

class AcmeProvider:
    name = "acme"

    def extract(self, payload) -> SipInfo:
        return SipInfo(sip_headers={"X-Correlation-Id": payload.get("x_correlation_id", "")})

    def forward_to_sip(self, info: SipInfo, sip_uri: str) -> Forward:
        return Forward(sip_uri=sip_uri, correlation_id=info.correlation_id or None)

register_provider(AcmeProvider())

import { Forward, SipInfo, registerProvider } from '@usetuner.ai/livekit-sdk/telephony';

registerProvider({
  name: 'acme',
  extract: (payload: any) =>
    new SipInfo({ sipHeaders: { 'X-Correlation-Id': payload?.x_correlation_id ?? '' } }),
  forwardToSip: (info, sipUri) => new Forward(sipUri, info.correlationId || null),
});

Check simulation works

Start a simulation run. See Run a simulation. When the call ends, check its result in the run. If it shows Unreported, Tuner never received a matching call from your agent.

Open Call Logs and look for the call. If it’s missing, check that the plugin is sending calls (see Troubleshooting).
If it’s there, check your tuner-livekit-sdk version against the Inbound table. Behind a carrier, also check the carrier webhook and the trunk’s include_headers setting. See Fix an Unreported run.

Python
Node.js

Per-turn timing

Each user and agent turn in the transcript carries these metadata fields. The values come from LiveKit’s own per-turn metrics; the SDK converts them to milliseconds and does not recompute them.

Field	Description
`stt_node_ttfb`	Time to obtain the transcript after the user stopped speaking
`eou_delay`	Time between the end of user speech and the decision to end their turn. Requires `tuner-livekit-sdk >= 0.1.9`.
`llm_node_ttft`	Time for the LLM node to return its first token
`tts_node_ttfb`	Time for the TTS node to return its first audio chunk
`e2e_latency`	Time from the end of user speech to the agent beginning its response
`interrupted`	Whether the turn was interrupted before it completed
`transcript_confidence`	STT confidence score for user turns

Disconnection reasons

Tuner captures why each call ended. User disconnects and errors are tracked automatically. To record agent-initiated hangups, pass reason="agent_hangup" when ending the call programmatically:

get_job_context().shutdown(reason="agent_hangup")

Without this, agent hangups are indistinguishable from dropped calls in your analytics.

Full tool call example

@function_tool
async def end_call(self, context: RunContext):
    """End the call once the user has been helped."""
    await context.session.shutdown(drain=True)
    get_job_context().shutdown(reason="agent_hangup")

drain=True lets any in-flight audio finish before the session closes. Omit it for an immediate cutoff.

LangChain and LangGraph observability

If you use LangGraph or LangChain for your logic layer, the plugin can capture node transitions, tool calls, and timing alongside session data. See LangChain / LangGraph.

Configuration options

Call type

The plugin auto-detects the call type (phone_call for SIP participants, web_call otherwise). Override it explicitly when needed:

TunerPlugin(session, ctx, call_type="phone_call")
TunerPlugin(session, ctx, call_type="web_call")

Recording URL

Tuner requires a recording_url for every call. Provide a resolver function that returns the URL. If you don’t provide one, the plugin submits "pending" as a placeholder.The URL must be a public https:// link. Tuner stores a placeholder or any other value as sent, but treats the call as having no recording: it has no playback in call details and can’t be added to a Dataset.

# Static / pre-known URL
async def my_resolver(room_name: str, job_id: str) -> str:
    return f"https://cdn.example.com/recordings/{job_id}.ogg"

TunerPlugin(session, ctx, recording_url_resolver=my_resolver)

# LiveKit Egress to S3
async def egress_resolver(room_name: str, job_id: str) -> str:
    url = await my_egress_db.get_recording_url(room_name)
    return url or "pending"

TunerPlugin(session, ctx, recording_url_resolver=egress_resolver)

Cost calculation

Provide a callable that receives a UsageSummary and returns the call cost in USD cents. Implement the method that matches your pricing plan; the snippet below is illustrative.

def calculate_cost(usage) -> float:
    # rates below are USD per unit; convert to cents before returning
    llm_cost  = usage.llm_prompt_tokens     * 0.000_003
    llm_cost += usage.llm_completion_tokens * 0.000_015
    tts_cost  = usage.tts_characters_count  * 0.000_030
    stt_cost  = usage.stt_audio_duration    * 0.000_006
    return (llm_cost + tts_cost + stt_cost) * 100  # USD -> cents

TunerPlugin(session, ctx, cost_calculator=calculate_cost)

Extra metadata

Attach arbitrary key-value data to every call record:

TunerPlugin(
    session, ctx,
    extra_metadata={
        "env": "production",
        "region": "us-east-1",
        "deployment": "v2.3.1",
    },
)

Retry and timeout

TunerPlugin(
    session, ctx,
    timeout_seconds=15.0,   # per-request timeout (default: 30.0)
    max_retries=5,          # retries on 5xx / 429 / network errors (default: 3)
)

Agent version tracking

Track which version of your agent handled each call, for example after you update a prompt, swap a model, or change your pipeline:

AGENT_VERSION=42 python agent.py start

The plugin reads AGENT_VERSION automatically. Bump the number on every deployment.Override in code (takes priority over the env var):

TunerPlugin(session, ctx, agent_version=42)

Trace forwarding

With the traces extra installed, the plugin forwards LiveKit’s OpenTelemetry spans to Tuner. forward_traces defaults to True. To turn it off:

TunerPlugin(session, ctx, forward_traces=False)

See OpenTelemetry traces.

Disable the plugin

Useful for local development or test environments:

import os

TunerPlugin(
    session, ctx,
    enabled=os.getenv("ENV") == "production",
)

Full example

import os
from livekit.agents import JobContext, AgentSession
from tuner import TunerPlugin

def calculate_cost(usage) -> float:
    usd = (
        usage.llm_prompt_tokens     * 0.000_003
        + usage.llm_completion_tokens * 0.000_015
        + usage.tts_characters_count  * 0.000_030
    )
    return usd * 100  # Tuner expects USD cents

async def get_recording_url(room_name: str, job_id: str) -> str:
    return await my_storage.get_url(job_id) or "pending"

async def entrypoint(ctx: JobContext):
    session = AgentSession(...)

    TunerPlugin(
        session,
        ctx,
        api_key=os.environ["TUNER_API_KEY"],
        workspace_id=int(os.environ["TUNER_WORKSPACE_ID"]),
        agent_id=os.environ["TUNER_AGENT_ID"],
        call_type="phone_call",
        recording_url_resolver=get_recording_url,
        cost_calculator=calculate_cost,
        extra_metadata={"env": "prod", "region": "us-east-1"},
        timeout_seconds=20.0,
        max_retries=3,
        enabled=True,
    )

    await session.start(...)

The SIP Call-ID is captured automatically, so the example doesn’t pass sip_call_id.

Disconnection reasons

Tuner captures why each call ended. User disconnects and errors are tracked automatically.

@livekit/agents (Node) currently invokes shutdown callbacks with no arguments, so the JS SDK submits a hardcoded 'shutdown' reason instead of the actual disconnect reason. Once LiveKit’s Node SDK forwards the reason, the JS plugin will pass it through automatically.

Configuration options

Call type

The plugin auto-detects the call type (phone_call for SIP participants, web_call otherwise). Override it explicitly when needed:

new TunerPlugin(session, ctx, { callType: 'phone_call' });
new TunerPlugin(session, ctx, { callType: 'web_call' });

Recording URL

Tuner requires a recording URL for every call. Provide a resolver function that returns the URL. If you don’t provide one, the plugin submits "pending" as a placeholder.The URL must be a public https:// link. Tuner stores a placeholder or any other value as sent, but treats the call as having no recording: it has no playback in call details and can’t be added to a Dataset.

async function getRecordingUrl(roomName: string, jobId: string): Promise<string> {
  return (await myStorage.getUrl(jobId)) ?? 'pending';
}

new TunerPlugin(session, ctx, { recordingUrlResolver: getRecordingUrl });

Cost calculation

Provide a callable that receives a UsageSummary and returns the call cost in USD cents. Implement the method that matches your pricing plan; the snippet below is illustrative.

import type { metrics } from '@livekit/agents';

function calculateCost(usage: metrics.UsageSummary): number {
  const usd =
    usage.llmPromptTokens * 0.000_003 +
    usage.llmCompletionTokens * 0.000_015 +
    usage.ttsCharactersCount * 0.000_030;
  return usd * 100; // Tuner expects USD cents
}

new TunerPlugin(session, ctx, { costCalculator: calculateCost });

Extra metadata

Attach arbitrary key-value data to every call record:

new TunerPlugin(session, ctx, {
  extraMetadata: {
    env: 'production',
    region: 'us-east-1',
    deployment: 'v2.3.1',
  },
});

Retry and timeout

new TunerPlugin(session, ctx, {
  timeoutSeconds: 15,   // per-request timeout (default: 30)
  maxRetries: 5,        // retries on 5xx / 429 / network errors (default: 3)
});

Agent version tracking

Track which version of your agent handled each call, for example after you update a prompt, swap a model, or change your pipeline:

AGENT_VERSION=42 node agent.js start

The plugin reads AGENT_VERSION automatically. Bump the number on every deployment.Override in code (takes priority over the env var):

new TunerPlugin(session, ctx, { agentVersion: 42 });

Disable the plugin

Useful for local development or test environments:

new TunerPlugin(session, ctx, {
  enabled: process.env.NODE_ENV === 'production',
});

Full example

import { TunerPlugin } from '@usetuner.ai/livekit-sdk';
import { voice, type JobContext, type metrics } from '@livekit/agents';

function calculateCost(usage: metrics.UsageSummary): number {
  const usd =
    usage.llmPromptTokens * 0.000_003 +
    usage.llmCompletionTokens * 0.000_015 +
    usage.ttsCharactersCount * 0.000_030;
  return usd * 100; // Tuner expects USD cents
}

async function getRecordingUrl(roomName: string, jobId: string): Promise<string> {
  return (await myStorage.getUrl(jobId)) ?? 'pending';
}

export default async function entry(ctx: JobContext) {
  const session = new voice.AgentSession({ /* ... */ });

  new TunerPlugin(session, ctx, {
    apiKey: process.env.TUNER_API_KEY,
    workspaceId: Number.parseInt(process.env.TUNER_WORKSPACE_ID!, 10),
    agentId: process.env.TUNER_AGENT_ID,
    callType: 'phone_call',
    recordingUrlResolver: getRecordingUrl,
    costCalculator: calculateCost,
    extraMetadata: { env: 'prod', region: 'us-east-1' },
    agentVersion: 42,
    timeoutSeconds: 20,
    maxRetries: 3,
    enabled: process.env.NODE_ENV === 'production',
  });

  await session.start({ agent, room: ctx.room });
}

OpenTelemetry traces

LiveKit Agents emits OpenTelemetry spans for every session. The Python SDK forwards them to Tuner, and they appear as a span tree on the call’s Traces tab. See Traces for how to read one. The Node.js SDK does not forward traces.

Requires tuner-livekit-sdk 0.1.10 or later.

Install the traces extra

pip install 'tuner-livekit-sdk[traces]'

The extra adds the OpenTelemetry SDK and the OTLP HTTP exporter. Without it, trace forwarding is skipped with a debug log, and the rest of the plugin works as usual.

Keep forward_traces on

forward_traces defaults to True, so TunerPlugin(session, ctx) is enough. The plugin sends spans to Tuner with the API key and base URL you already configured, and tags every span with the call’s ID. You don’t need to create a TracerProvider, choose an exporter, or set any OTEL_* environment variable.If you already configured a TracerProvider to export traces elsewhere, the plugin adds Tuner as an extra destination on it. Your existing backend keeps receiving the same spans.To stop forwarding traces, pass forward_traces=False.

Check that it worked

Open the call in Tuner. A Traces tab appears on the call details page once spans have been received and matched. Matching completes when the call itself is ingested, so the tab can take a moment to appear after a session ends.

Span reference

The span names come from LiveKit Agents, so they are the same ones you would see in any other OpenTelemetry backend.

Span	What it covers
`agent_session`	The whole session. This is the root span.
`start_agent_activity`, `on_enter`	Session startup and the agent’s entry hook.
`agent_turn`	One agent response.
`llm_node`	The model stage of that turn.
`llm_request`, `llm_request_run`	The model request itself, nested inside the node span.
`tts_node`	The synthesis stage of that turn.
`tts_stream_adapter`, `tts_request_run`	The streaming adapter and the synthesis request underneath it.
`user_turn`	One customer turn.
`user_speaking`	The window where the customer was actually speaking.

See LiveKit’s telemetry documentation for the full set, and Traces for how to read the tree in Tuner.

Traces troubleshooting

The Traces tab never appears

The traces extra isn’t installed. The plugin skips forwarding and logs a debug message. Install tuner-livekit-sdk[traces].
The SDK is older than 0.1.10. Upgrade tuner-livekit-sdk.
forward_traces=False is set. Remove it or set it to True.
The API key is wrong or revoked. Tuner rejects the spans with 401 or 403.

Webhooks

Tuner can notify your systems when it has something to report on a call. See Webhooks.

Before you finish

A test call appears in Call Logs.
Your API key, workspace ID and Agent Remote ID come from API keys.
If you use Call Simulation: Enable simulation is done for your agent’s call direction, and one simulated call shows a result other than Unreported.

Troubleshooting

Calls don't appear in Tuner

Verify that TUNER_AGENT_ID is the Agent Remote ID from Agent Settings > Agent Connection (not your agent’s display name).
Confirm TUNER_WORKSPACE_ID is correct.
Check your application logs for any error messages from the plugin.

Unauthorized (401)

Ensure TUNER_API_KEY starts with tr_api_ and is valid.
Confirm the API key belongs to the correct workspace.

Simulated calls show as Unreported

Inbound: check that the caller joins the room as a SIP participant with a sip.callIDFull attribute, and check your tuner-livekit-sdk version against the Inbound table.
Inbound, with a carrier in front of LiveKit: check that your webhook calls forward_to_sip (see Carrier in front of LiveKit) and that the inbound trunk’s include_headers is SIP_X_HEADERS or SIP_ALL_HEADERS.
Outbound: confirm you pass recipient with the SIP URI exactly as Tuner sent it.
See Fix an Unreported run.

A call has no recording

You haven’t provided a recording URL resolver (recording_url_resolver in Python, recordingUrlResolver in Node.js), so the plugin sent "pending". Add one that returns the actual recording URL for each call.
The resolver returned a link that isn’t a public https:// URL, such as http:// or localhost. Tuner treats those as no recording.
If using LiveKit Egress, ensure the recording has finished processing before the resolver is called.

Next steps

Configure your agent

Set up call outcomes, user intents, and evals.

Custom integration

Learn about the underlying API if you need more control.

Classify calls

Define how Tuner categorizes your calls.

Alerts

Get notified when issues are detected.

​Video tutorial

​Prerequisites

​Overview

​Step 1: Install the SDK

​Step 2: Set your credentials

​Step 3: Add the plugin

​Step 1: Install the SDK

​Step 2: Set your credentials

​Step 3: Add the plugin

​Enable simulation

​Inbound

​Outbound

​Carrier in front of LiveKit

​Check simulation works

​Per-turn timing

​Disconnection reasons

​LangChain and LangGraph observability

​Configuration options

​Full example

​Disconnection reasons

​Configuration options

​Full example

​OpenTelemetry traces

​Span reference

​Traces troubleshooting

​Webhooks

​Before you finish

​Troubleshooting

​Next steps

Configure your agent

Custom integration

Classify calls

Alerts

Video tutorial

Prerequisites

Overview

Step 1: Install the SDK

Step 2: Set your credentials

Step 3: Add the plugin

Step 1: Install the SDK

Step 2: Set your credentials

Step 3: Add the plugin

Enable simulation

Inbound

Outbound

Carrier in front of LiveKit

Check simulation works

Per-turn timing

Disconnection reasons

LangChain and LangGraph observability

Configuration options

Full example

Disconnection reasons

Configuration options

Full example

OpenTelemetry traces

Span reference

Traces troubleshooting

Webhooks

Before you finish

Troubleshooting

Next steps