SDK quickstart

Uses tuner-core plus one observer per role in your pipeline. Not on Python? See Direct API.

This guide shows the Tuner lines you add to a voice agent you already have. The examples assume Deepgram for STT, LangGraph for the LLM layer, and Cartesia for TTS. Swap or skip any role you don’t use. Your audio loops, agent logic, and synthesis code stay as they are. With the observers attached, Tuner receives user and agent turns with timing, per-turn STT/LLM/TTS and end-to-end latency, tool calls and results in the same timeline, word-accurate interruption capture, and usage plus cost, without code of your own.

Prerequisites

An active Tuner account
A Tuner agent with provider Custom API
A Tuner API key, your workspace ID and the agent’s Agent Remote ID. See API keys.
Python 3.10 to 3.13 and a custom voice stack you control

The mental model

Create one TunerSession per call

tuner-core coordinates the call. The session holds your call’s identity (call_id, workspace, and agent mapping) and coordinates the observers.

Attach one observer per role

STT, LLM, and TTS each have their own package. Attach only the roles your stack has; each is independent.

flush() at call end

The session assembles what the observers captured into a single timeline and sends it to Tuner via the Create Call API. One network call, at the end.

Step 1: Install

pip install tuner-core "tuner-stt-observer[deepgram]" "tuner-tts-observer[cartesia]" tuner-langchain

tuner-core provides TunerSession and TunerConfig. Provider SDKs sit behind extras so you only pull in what you use. Other combinations are in Mix and match below.

Step 2: Set your credentials

TunerConfig.from_env() reads these from the environment. Keyword arguments you pass to it take priority.

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
`TUNER_BASE_URL`	No	API base URL (default: `https://api.usetuner.ai`)
`TUNER_DEBUG`	No	Set to `true` to log the full payload on flush
`AGENT_VERSION`	No	Integer agent version attached to every call. No `TUNER_` prefix. The `agent_version` argument overrides it.

Step 3: Create a session per call

Create one TunerSession at the start of each call. The model names are recorded as call metadata. Keep call_id stable across retries so ingestion stays idempotent.

from tuner_core import TunerConfig, TunerSession

session = TunerSession(
    config=TunerConfig.from_env(
        asr_model="nova-2",
        llm_model="gpt-4o-mini",
        tts_model="sonic-2",
    ),
    call_id=call_id,  # your unique, retry-stable identifier for this call
)

Extra metadata

Attach arbitrary key-value data to every call, such as environment, region, deployment version, or tenant:

config = TunerConfig.from_env(
    asr_model="nova-2",
    llm_model="gpt-4o-mini",
    tts_model="sonic-2",
    extra_metadata={"env": "production", "region": "us-east-1"},
)

Metadata can also be used as an eval input, which is how you evaluate agents whose instructions change per call. See Evaluate agents with per-call instructions. The keys ai_models and usage_token are reserved and ignored in extra_metadata.

Cost calculation

Pass a cost_calculator callable. At flush, it receives a CallUsage and returns the call cost in USD cents. The rates below are illustrative.

from tuner_core import CallUsage, TunerConfig

def calculate_cost(usage: CallUsage) -> float:
    usd = (
        usage.llm_prompt_tokens       * 0.000_003
        + usage.llm_completion_tokens * 0.000_015
        + usage.tts_characters        * 0.000_030
        + usage.stt_audio_seconds     * 0.000_006
    )
    return usd * 100  # USD -> cents

config = TunerConfig.from_env(cost_calculator=calculate_cost)

CallUsage fields: llm_prompt_tokens, llm_completion_tokens, llm_total_tokens, tts_characters, stt_audio_seconds. If the callable raises, the call is sent without a cost.

Disconnection reason

Set session.disconnection_reason before flush() to record why the call ended. Use a DisconnectReason value or your own string:

from tuner_core import DisconnectReason

session.disconnection_reason = DisconnectReason.AGENT_HANGUP

Constant	Value
`DisconnectReason.USER_HANGUP`	`"user_hangup"`
`DisconnectReason.AGENT_HANGUP`	`"agent_hangup"`
`DisconnectReason.ERROR`	`"error"`
`DisconnectReason.TIMEOUT`	`"timeout"`
`DisconnectReason.UNKNOWN`	`"unknown"`

Step 4: Attach observers

STT: Deepgram

from tuner_stt_observer import DeepgramAdapter

stt = DeepgramAdapter(connection=dg_connection)   # your existing Deepgram connection
stt.on_utterance = handle_user_utterance          # your callback: complete user turn text
session.attach(stt)

Send audio to Deepgram as you normally would. The adapter only listens on the connection’s events. Your LiveOptions must set utterance_end_ms and vad_events=True, or you’ll see calls with no user turns. Speechmatics, custom providers, and what each adapter captures: Speech-to-Text.

LLM: LangGraph

from tuner_langchain import wrap_graph

graph = session.attach(wrap_graph(your_graph))

# then invoke as usual:
result = await graph.ainvoke({"messages": history})

Node transitions, per-node LLM latency, and tool calls land in the timeline. Plain chains and privacy controls: LangChain / LangGraph.

TTS: Cartesia

from tuner_tts_observer import CartesiaAdapter

tts = session.attach(CartesiaAdapter())

# around your existing Cartesia WebSocket receive loop:
async with tts.track_ws(agent_text) as tracked:
    async for chunk in tracked(ctx.receive()):    # ctx: your Cartesia context
        ...                                        # your playback / send code

Word-accurate interruption capture, the SSE pattern for HTTP-only stacks, and what your app owns for barge-in: Text-to-Speech.

Step 5: Flush at call end

flush() is the only network call the libraries make. Put it in a finally block so the call reaches Tuner even when the connection drops or your loop raises:

try:
    ...  # your call loop
finally:
    await session.flush()

Open Call Logs in Tuner to see the processed result.

Enable simulation

Required for Call Simulation. Skip it otherwise.

Inbound

Tuner calls your agent over SIP.

SDK	Version
Python, `tuner-core`	0.1.3 or later

If your calls come through a carrier, the carrier sends each call to a webhook, then opens a WebSocket for the audio. Tuner’s SIP data reaches the webhook but not the WebSocket. Forward it from the webhook, then attach it to the session.

Add your SIP URI in Tuner

Add your agent’s SIP URI in Agent Settings > Simulation Setup. Get it from your SIP provider, then see Set up inbound simulation.

Forward the SIP data from your webhook

Read the SIP data from the carrier’s request and put it on the WebSocket.

Twilio
Telnyx

from tuner_core.telephony import extract_sip, forward_to_websocket

# Twilio voice webhook: the Voice URL of the SIP Domain that Tuner dials
info = extract_sip(await request.form(), provider="twilio")
fwd = forward_to_websocket(info, ws_url=WS_URL)
return Response(fwd.twiml, media_type="application/xml")

from tuner_core.telephony import extract_sip, forward_to_websocket

# Telnyx call.initiated webhook
fwd = forward_to_websocket(extract_sip(webhook_json, provider="telnyx"), ws_url=WS_URL)

# answer rejects custom_parameters, so answer first, then start the stream
await telnyx(f"calls/{call_control_id}/actions/answer", {})
await telnyx(f"calls/{call_control_id}/actions/streaming_start", fwd.stream)

Tuner dials the SIP subdomain of a Call Control application. Set the application’s webhook to this handler.

Attach the SIP data to the session

In your WebSocket handler, read the SIP data from the first message and attach it to the session. Do this before you call flush().

session.attach_sip(extract_sip(start_message, provider="twilio"))  # or "telnyx"

Twilio forwards SipCallId and X-Correlation-Id. Telnyx’s call.initiated event has no SIP Call-ID, so X-Correlation-Id links a Telnyx call. Tuner links the call on either one. You can call attach_sip more than once. Headers merge, and the first non-empty value wins. It never changes the shared config.

Your own SIP trunk or another carrier

If you already have the values, pass them directly:

session.attach_sip(
    sip_call_id=sip_call_id,                          # SIP Call-ID of the inbound call
    sip_headers={"X-Correlation-Id": correlation_id}, # the header Tuner put on the call
)

To read a carrier’s payload with extract_sip, register a class with a name and extract(payload) -> SipInfo. Add forward_to_websocket(info, ws_url) -> Forward to support forwarding.

from tuner_core.telephony import SipInfo, register_provider

class AcmeProvider:
    name = "acme"

    def extract(self, payload) -> SipInfo:
        return SipInfo(sip_call_id=payload["sip_call_id"], sip_headers=payload["headers"])

register_provider(AcmeProvider())

Set the values in the config instead

TunerConfig also takes sip_call_id, sip_headers and recipient. They are per call, so use a separate config for each call. They have no environment variables.

session = TunerSession(
    config=TunerConfig.from_env(
        sip_call_id=sip_call_id,
        sip_headers={"X-Correlation-Id": correlation_id},
    ),
    call_id=call_id,
)

Older SDK versions

tuner-core 0.1.1 to 0.1.2 accepts sip_call_id on TunerConfig, which links calls on the SIP Call-ID. sip_headers, recipient, attach_sip and tuner_core.telephony need 0.1.3 or later.

sip_call_id doesn’t replace call_id. Tuner uses call_id to detect duplicates.

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.
Report the SIP URI your agent dialed as recipient, exactly as Tuner sent it. It needs tuner-core 0.1.3 or later.

If your bot gets audio from a Twilio or Telnyx media stream, put the SIP URI on the stream when you place the call. Then the bot reads it from the start message.

Twilio
Telnyx

from tuner_core.telephony import SipInfo, extract_sip, forward_to_websocket

fwd = forward_to_websocket(SipInfo(recipient=dialed_sip_uri), ws_url=WS_URL, provider="twilio")
twilio_client.calls.create(to=dialed_sip_uri, from_=..., twiml=fwd.twiml)

# in the bot, on the WebSocket "start" message
session.attach_sip(extract_sip(start, provider="twilio"))

from tuner_core.telephony import SipInfo, extract_sip, forward_to_websocket

fwd = forward_to_websocket(SipInfo(recipient=dialed_sip_uri), ws_url=WS_URL, provider="telnyx")
# on call.answered for the call you placed
await telnyx_post(f"/v2/calls/{call_control_id}/actions/streaming_start", fwd.stream)

# in the bot, on the WebSocket "start" message
session.attach_sip(extract_sip(start, provider="telnyx"))

If your bot already has the SIP URI, pass it directly:

session.attach_sip(recipient=dialed_sip_uri)   # the SIP URI Tuner sent, unchanged

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. See Fix an Unreported run.

Mix and match

Your stack	Install
Deepgram + LangGraph + Cartesia	`tuner-core "tuner-stt-observer[deepgram]" "tuner-tts-observer[cartesia]" tuner-langchain`
Speechmatics + Cartesia	`tuner-core "tuner-stt-observer[speechmatics]" "tuner-tts-observer[cartesia]"`
STT observability only	`tuner-core "tuner-stt-observer[deepgram]"`
LLM tracing only	`tuner-core tuner-langchain`
LiveKit or Pipecat	Use the LiveKit / Pipecat SDKs instead

Missing an adapter for one of your providers? Extend the base adapter for that role. See Custom providers on the Speech-to-Text and Text-to-Speech pages.

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 TUNER_AGENT_ID is the Agent Remote ID from Agent Settings > Agent Connection.
Set TUNER_DEBUG=true to log the full payload on flush.
Confirm TUNER_WORKSPACE_ID is correct.
Confirm session.flush() ran. Put it in a finally block so exceptions don’t skip it.

Unauthorized (401)

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

Role-specific problems (missing user turns, interrupted turns recording in full, latency fields absent) are on the Speech-to-Text and Text-to-Speech pages.

Next steps

Speech-to-Text

Deepgram and Speechmatics adapters, options, custom providers.

Text-to-Speech

Cartesia over WebSocket or SSE, word-level interruption capture.

LangChain / LangGraph

Node transitions, tool calls, and LLM latency in your timeline.

Review your first call

What Tuner does with the data once it lands.

Getting Started

Integrations

Evaluation

Observability

Simulation

Datasets

MCP

Guides

Resources

Prerequisites

The mental model

Step 1: Install

Step 2: Set your credentials

Step 3: Create a session per call

Extra metadata

Cost calculation

Disconnection reason

Step 4: Attach observers

STT: Deepgram

LLM: LangGraph

TTS: Cartesia

Step 5: Flush at call end

Enable simulation

Inbound

Outbound

Check simulation works

Mix and match

Before you finish

Troubleshooting

Next steps

Speech-to-Text

Text-to-Speech

LangChain / LangGraph

Review your first call

​Prerequisites

​The mental model

​Step 1: Install

​Step 2: Set your credentials

​Step 3: Create a session per call

​Extra metadata

​Cost calculation

​Disconnection reason

​Step 4: Attach observers

​STT: Deepgram

​LLM: LangGraph

​TTS: Cartesia

​Step 5: Flush at call end

​Enable simulation

​Inbound

​Outbound

​Check simulation works

​Mix and match

​Before you finish

​Troubleshooting

​Next steps

Speech-to-Text

Text-to-Speech

LangChain / LangGraph

Review your first call

Prerequisites

The mental model

Step 1: Install

Step 2: Set your credentials

Step 3: Create a session per call

Extra metadata

Cost calculation

Disconnection reason

Step 4: Attach observers

STT: Deepgram

LLM: LangGraph

TTS: Cartesia

Step 5: Flush at call end

Enable simulation

Inbound

Outbound

Check simulation works

Mix and match

Before you finish

Troubleshooting

Next steps