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 exactly as they are. Attach the observers and you get, without writing any of it: 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.

Prerequisites

Tuner Active Account
Configured Agent with provider “Custom API” in Tuner
Python ≥ 3.10 and a custom voice stack you control

The mental model

Create one TunerSession per call

tuner-core is the backbone. The session holds your call’s identity — call_id, workspace, and agent mapping — and coordinates everything else.

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:

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

Step 3: Create a session per call

One TunerSession at the start of each call. The model names are used for cost calculation. 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
)

TunerConfig.from_env() also takes extra_metadata={...} to attach arbitrary key-value data to the call record, and sip_call_id=... to link a simulated call back to its simulation run — see Simulation SIP setup.

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 exactly 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 Tuner → Calls to see the processed result.

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.

Troubleshooting

Calls don't appear in Tuner

Verify TUNER_AGENT_ID is the Agent Remote ID from Agent Settings → Agent Connection.
Confirm TUNER_WORKSPACE_ID is correct.
Confirm session.flush() actually 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.

What’s next?

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

MCP

Guides

Resources

Prerequisites

The mental model

Step 1: Install

Step 2: Set your credentials

Step 3: Create a session per call

Step 4: Attach observers

STT — Deepgram

LLM — LangGraph

TTS — Cartesia

Step 5: Flush at call end

Mix and match

Troubleshooting

What’s next?

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

​Step 4: Attach observers

​STT — Deepgram

​LLM — LangGraph

​TTS — Cartesia

​Step 5: Flush at call end

​Mix and match

​Troubleshooting

​What’s next?

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

Step 4: Attach observers

STT — Deepgram

LLM — LangGraph

TTS — Cartesia

Step 5: Flush at call end

Mix and match

Troubleshooting

What’s next?