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

Tuner Active Account
Configured Agent with provider “Custom API” in Tuner
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 automatically captures session data from your LiveKit agent and sends it to Tuner when the call ends — no manual API calls required. It ships in two flavours that share the same wire format and feature set: a Python package and a Node.js package.

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

Drop two lines into your entrypoint and you’re done.

Estimated time: 2 minutes from start to finish

Python
Node.js

Step 1: Install the SDK

pip install tuner-livekit-sdk

Requirements: Python ≥ 3.10, livekit-agents >= 1.4, aiohttp >= 3.9

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 (UUID — not your agent’s display name)
`TUNER_BASE_URL`	—	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(...)

That’s it. The plugin listens to session events and submits call data to Tuner when the session ends.

SIP correlation for simulation

To run Call Simulation against this agent, pass the inbound call’s SIP Call-ID as sip_correlation_id. For why Tuner needs it and how the value can change name in transit, see Simulation SIP setup.

This applies to inbound simulation, where Tuner dials your agent. For outbound simulation, pass the dialed SIP URI as recipient instead — see Outbound Simulation.

LiveKit exposes the value on the SIP participant as the sip.callIDFull attribute.

Requires tuner-livekit-sdk >= 0.1.5.

Helper: extract the SIP correlation ID

Add this helper to your entrypoint module. It scans the room’s remote participants for the SIP participant and returns its sip.callIDFull attribute.

from livekit import rtc
from livekit.agents import JobContext


def _extract_sip_correlation_id(ctx: JobContext) -> str | None:
    for participant in ctx.room.remote_participants.values():
        if participant.kind != rtc.ParticipantKind.PARTICIPANT_KIND_SIP:
            continue
        attributes = dict(getattr(participant, "attributes", {}) or {})
        sip_call_id_full = attributes.get("sip.callIDFull")
        if isinstance(sip_call_id_full, str) and sip_call_id_full:
            return sip_call_id_full
    return None

For web calls (no SIP participant), this returns None and TunerPlugin falls back to its normal behaviour.

Wire it into your entrypoint

The SIP participant only becomes visible after the agent joins the room. Call ctx.connect() first, then read the correlation ID, then pass it to TunerPlugin:

async def entrypoint(ctx: JobContext):
    await ctx.connect()                                     # 1. connect first
    sip_correlation_id = _extract_sip_correlation_id(ctx)   # 2. then read

    session = AgentSession(...)

    TunerPlugin(
        session, ctx,
        sip_correlation_id=sip_correlation_id,              # 3. pass it in
        # ... your other TunerPlugin options
    )

    await session.start(...)

If ctx.connect() runs after you try to read participants, ctx.room.remote_participants will be empty and sip_correlation_id will be None. Simulated calls will still complete, but they won’t be linked to their Tuner simulation rows.

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

Using 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")

Recipient

The phone number or SIP URI of the callee. Optional — pass it when you want to record who the call was directed to:

TunerPlugin(session, ctx, recipient="+15551234567")
TunerPlugin(session, ctx, recipient="sip:+15551234567@provider.com")

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.

# 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 → 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 — useful when you update a prompt, swap a model, or change your pipeline:

AGENT_VERSION=42 python agent.py start

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

TunerPlugin(session, ctx, agent_version=42)

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 import rtc
from livekit.agents import JobContext, AgentSession
from tuner import TunerPlugin


def _extract_sip_correlation_id(ctx: JobContext) -> str | None:
    for participant in ctx.room.remote_participants.values():
        if participant.kind != rtc.ParticipantKind.PARTICIPANT_KIND_SIP:
            continue
        attributes = dict(getattr(participant, "attributes", {}) or {})
        sip_call_id_full = attributes.get("sip.callIDFull")
        if isinstance(sip_call_id_full, str) and sip_call_id_full:
            return sip_call_id_full
    return None


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):
    await ctx.connect()
    sip_correlation_id = _extract_sip_correlation_id(ctx)

    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,
        sip_correlation_id=sip_correlation_id,
        extra_metadata={"env": "prod", "region": "us-east-1"},
        timeout_seconds=20.0,
        max_retries=3,
        enabled=True,
    )

    await session.start(...)

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.

Recording URL shows as 'pending'

You haven’t provided a recording_url_resolver. Add one that returns the actual recording URL for each call.
If using LiveKit Egress, ensure the recording has finished processing before the resolver is called.

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 (UUID — not your agent’s display name)
`TUNER_BASE_URL`	—	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 });
}

That’s it. The plugin listens to session events and submits call data to Tuner when the session ends.

SIP correlation for simulation

To run Call Simulation against this agent, pass the inbound call’s SIP Call-ID as sipCorrelationId. For why Tuner needs it and how the value can change name in transit, see Simulation SIP setup.

This applies to inbound simulation, where Tuner dials your agent. For outbound simulation, pass the dialed SIP URI as recipient instead — see Outbound Simulation.

LiveKit exposes the value on the SIP participant as the sip.callIDFull attribute.

Helper: extract the SIP correlation ID

Add this helper to your entrypoint module. It scans the room’s remote participants for the SIP participant and returns its sip.callIDFull attribute.

import { ParticipantKind } from '@livekit/rtc-node';
import type { JobContext } from '@livekit/agents';

function extractSipCorrelationId(ctx: JobContext): string | undefined {
  for (const participant of ctx.room.remoteParticipants.values()) {
    if (participant.kind !== ParticipantKind.SIP) continue;
    const sipCallIdFull = participant.attributes?.['sip.callIDFull'];
    if (typeof sipCallIdFull === 'string' && sipCallIdFull) return sipCallIdFull;
  }
  return undefined;
}

For web calls (no SIP participant), this returns undefined and TunerPlugin falls back to its normal behaviour.

Wire it into your entrypoint

The SIP participant only becomes visible after the agent joins the room. Call ctx.connect() first, then read the correlation ID, then pass it to TunerPlugin:

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

  await ctx.connect();                                       // 1. connect first
  const sipCorrelationId = extractSipCorrelationId(ctx);     // 2. then read

  new TunerPlugin(session, ctx, {
    sipCorrelationId,                                        // 3. pass it in
    // ...other options
  });

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

If ctx.connect() runs after you try to read participants, ctx.room.remoteParticipants will be empty and sipCorrelationId will be undefined. Simulated calls will still complete, but they won’t be linked to their Tuner simulation rows.

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.

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 — useful when you update a prompt, swap a model, or change your pipeline:

AGENT_VERSION=42 node agent.js start

Tuner reads it 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) {
  await ctx.connect();
  const sipCorrelationId = extractSipCorrelationId(ctx);

  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,
    sipCorrelationId,
    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 });
}

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.

Recording URL shows as 'pending'

You haven’t provided a recordingUrlResolver. Add one that returns the actual recording URL for each call.
If using LiveKit Egress, ensure the recording has finished processing before the resolver is called.

OpenTelemetry traces

LiveKit Agents already emits OpenTelemetry spans for every session. Point its exporter at Tuner and those spans appear as a span tree on the matching call, under a Traces tab. See OpenTelemetry Traces for how to read one.

This is optional and separate from the SDK integration above. Trace export is configured through LiveKit’s own telemetry module, in Python.

Point your exporter at Tuner

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://api.usetuner.ai/api/v1/traces"
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer tr_api_..."

Use the same TUNER_API_KEY you set in Step 2. It identifies your workspace, so nothing else needs configuring.

Use the signal-specific variable, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, and give the full URL. The generic OTEL_EXPORTER_OTLP_ENDPOINT breaks this setup in two ways: the exporter appends /v1/traces to it, which does not resolve to Tuner’s path, and it is shared with metrics and logs, so repointing it would send those to Tuner as well.

If you already send traces to your own observability backend, leave that variable alone and fan out with an OpenTelemetry Collector instead of switching endpoints.

Use the HTTP exporter

Tuner accepts OTLP over HTTP with protobuf encoding, which is the default for the HTTP exporter. gRPC is not supported.

# Correct
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Not supported by Tuner
# from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

Tag the trace with your call id

Tuner matches a trace to a call on a tuner.call_id span attribute. Its value has to be the same call id the plugin submits for this session, character for character.metadata is applied to every span in the session, so setting it once on the tracer provider is enough.

from livekit.agents.telemetry import set_tracer_provider
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor


async def entrypoint(ctx: JobContext) -> None:
    provider = TracerProvider()
    provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))

    set_tracer_provider(provider, metadata={"tuner.call_id": your_call_id})

    session = AgentSession(...)
    TunerPlugin(session, ctx)
    await session.start(...)

You only need the attribute on one span in the trace. Tuner applies it to the whole trace, including spans that arrived before the tagged one.

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. Correlation 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 OpenTelemetry Traces for how to read the tree in Tuner.

Traces troubleshooting

The Traces tab never appears

In order of likelihood:

tuner.call_id does not match the call id submitted for the session. They have to be identical strings. This is the most common cause by a wide margin.
The attribute is missing entirely. Nothing in the trace carries it, so there is nothing for Tuner to match on.
The gRPC exporter is still in use. Requests are rejected with 415. Check your agent logs for exporter errors.
The API key is wrong or revoked. Requests are rejected with 401 or 403.

Traces also stopped reaching my own backend

You probably repointed OTEL_EXPORTER_OTLP_ENDPOINT rather than the traces-specific variable. Restore it and use an OpenTelemetry Collector to send spans to both destinations.

service.name reads unknown_service

Your tracer provider was created without a service name resource. Traces still arrive and still correlate, but they are harder to tell apart when several agents report into the same workspace.

Webhooks

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

What’s Next?

Configuring Your Agent

Set up call outcomes, user intents, and evals.

Custom Integration

Learn about the underlying API if you need more control.

Classifying Calls

Define how Tuner categorizes your calls.

Real-Time 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

​SIP correlation for simulation

​Helper: extract the SIP correlation ID

​Wire it into your entrypoint

​Disconnection Reasons

​LangChain and LangGraph observability

​Configuration Options

​Full Example

​Troubleshooting

​Step 1: Install the SDK

​Step 2: Set Your Credentials

​Step 3: Add the Plugin

​SIP correlation for simulation

​Helper: extract the SIP correlation ID

​Wire it into your entrypoint

​Disconnection Reasons

​Configuration Options

​Full Example

​Troubleshooting

​OpenTelemetry traces

​Span reference

​Traces troubleshooting

​Webhooks

​What’s Next?

Configuring Your Agent

Custom Integration

Classifying Calls

Real-Time Alerts

Video Tutorial

Prerequisites

Overview

Step 1: Install the SDK

Step 2: Set Your Credentials

Step 3: Add the Plugin

SIP correlation for simulation

Helper: extract the SIP correlation ID

Wire it into your entrypoint

Disconnection Reasons

LangChain and LangGraph observability

Configuration Options

Full Example

Troubleshooting

Step 1: Install the SDK

Step 2: Set Your Credentials

Step 3: Add the Plugin

SIP correlation for simulation

Helper: extract the SIP correlation ID

Wire it into your entrypoint

Disconnection Reasons

Configuration Options

Full Example

Troubleshooting

OpenTelemetry traces

Span reference

Traces troubleshooting

Webhooks

What’s Next?