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 if you’ll use Call Simulation. Skip it otherwise. Tuner links each simulated call to its run through a value you send back: sip_call_id for inbound agents and recipient for outbound agents (how simulated calls are linked). Do the steps for your agent’s call direction.

Inbound

Tuner calls your agent over SIP.

Add your agent’s SIP URI in Agent Settings > Simulation Setup. Get it from your SIP provider, then see Set up inbound simulation.
Pass the SIP Call-ID of the call Tuner placed as sip_call_id. Read it from the inbound call in your SIP stack; it may arrive under a different name.

session = TunerSession(
    config=TunerConfig.from_env(
        sip_call_id=sip_call_id,  # SIP Call-ID of the inbound call
    ),
    call_id=call_id,
)

When you send sip_call_id, Tuner uses it in place of call_id to detect duplicates.

Outbound

Your agent calls a Simulated Caller at a SIP URI that Tuner sends to your trigger endpoint. Tuner links the call through recipient, and tuner-core can’t send recipient yet.

Configure the trigger endpoint in Agent Settings > Simulation Setup. See Set up outbound simulation.
Send outbound calls with the Create Call API instead of session.flush(), with the dialed SIP URI in recipient. See Direct API: Enable simulation.

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