Skip to main content
Available for: TypeScript (@livekit/agents 1.10 or newer, below 2) and Python (livekit-agents 1.8 or newer, below 3, Python 3.10 or newer). Both SDKs read LiveKit’s own session events and metrics, so it works with or without LiveKit Cloud and with or without LiveKit’s OpenTelemetry export.
One call attaches Zespan to a LiveKit AgentSession. Every turn of a call shows up as a trace: what the caller said, what the agent answered, and each model, speech-to-text, text-to-speech and tool step inside the turn, with tokens, audio seconds, characters, cost and the latencies LiveKit measures. Turns of one call are grouped as one session, and each turn is tagged with the agent that handled it. Nothing is patched in your agent. The SDK subscribes to the session, never touches audio, and its handlers do no network work on the voice loop.

Installation

@livekit/agents is an optional peer dependency of @zespan/sdk, and livekit-agents is the livekit extra of zespan. Both SDKs import and run without LiveKit installed.

Quickstart

1

Initialise Zespan once

Call zespan.init() at startup, with the API key from an environment variable.
2

Attach it to the session, before it starts

Create your AgentSession, then call instrumentLiveKitSession (TypeScript) or instrument_session (Python) before session.start() so the first turn is seen. Pass the job context so the session id is lk:<job id>.
3

Flush at shutdown

Flush from LiveKit’s shutdown callback so the last turn and the call summary are sent before the worker exits.
The call returns a handle with detach() and flush() (Python also has aflush() for async code). detach() stops listening and sends the open turn and the call summary. Calling it twice on one session returns the same handle. The function never throws; if it cannot attach it logs a warning and your agent runs untouched.

Options

The TypeScript SDK also exposes the same call as zespan.livekit.instrument(session, options).

What you get

One trace per turn. A turn starts when the caller’s message lands (or when the agent speaks first, for example with say()), and every turn of one call shares the call’s session_id. When the call closes Zespan sends one more trace, the call summary, with the totals.
Realtime models (OpenAI Realtime, Gemini Live) give realtime spans instead of stt, chat and tts. Text-only sessions and agent handoffs are supported, and an interrupted turn is marked, not failed.

What each turn records

Durations are in milliseconds. A value LiveKit did not report is absent, never 0. The child spans carry the unit each one is priced in: Streaming speech-to-text reports per audio window, not per utterance, so Zespan attaches each report to the turn that was open when it arrived and marks the turn lk_stt_attribution = "window". Per-turn STT attribution is approximate; the call totals are exact. The call summary carries lk_turns, lk_interruptions, lk_false_interruptions, lk_close_reason, the usage totals LiveKit reported, and content-free facts the voice detectors read: tool call counts per tool name, the longest run of calls to one tool, transcript confidence, and the number of dead-air turns. It is never priced.

Who the call belongs to

Transcripts and PII

Voice transcripts are user content, and callers read names, card numbers and phone numbers aloud. The integration uses the same pipeline as every other Zespan integration:
  • The caller’s transcript becomes prompt_text, the agent’s reply completion_text, and the agent’s instructions system_prompt (when they are a plain string), only when storePrompts is on (the default). Each goes through the SDK’s redaction (key redaction, PII detection with your preset, secret patterns) before it leaves your process, then is cut to the text limit.
  • captureTranscripts: false (capture_transcripts=False) stops transcripts while leaving other prompt capture on.
  • Interim transcripts are never sent; only final ones.
  • Tool arguments and results are stored only with storeToolIO.
  • Participant identity, room name and SIP numbers are never read into an event unless you opt in with userIdFrom: "participant_identity".
On the native path, fields LiveKit marks as personal data (lk.pii.*) are never read. On the OpenTelemetry path, the lk.pii.* transcripts (the caller’s text and the agent’s reply) and tool arguments and results are stored as content when your project’s content capture is on, and dropped when it is off. What is never stored on either path is the raw lk.pii.* attribute itself, and the identity fields (participant identity, room name, SIP numbers).
See PII redaction for the presets and for what redaction does not cover.

Pricing

The model call is priced like any other model call. Speech-to-text and text-to-speech are priced by what the provider bills:
  • Speech-to-text: audio seconds, or tokens for token-billed models.
  • Text-to-speech: characters, or tokens for token-billed models.
  • The SDK never sets a cost. Zespan prices on the server from an official price table (OpenAI, Deepgram, AssemblyAI and ElevenLabs model families), so a price change applies without an SDK release. A custom price your organization sets under Model pricing in settings applies as well.
A model that is not in the price table and has no custom price is unpriced. Its span cost reads unpriced in the trace, never $0. A realtime model (a model id containing realtime) is always unpriced unless you set a custom price: its audio tokens are never priced at a text-model rate. Set a custom price under Model pricing in settings to price it.
Where unpriced spans are counted today: A cost ceiling guardrail never blocks on unknown spend by itself. If the spend already counted is over the ceiling, it blocks. Otherwise the check is allowed and marked as errored, with the evidence “spend unknown: N unpriced spans”, whatever the rule’s onError setting is.

Do not send LiveKit’s OpenTelemetry data to Zespan as well

Use the native integration or LiveKit’s OTel export to Zespan, not both. If you point LiveKit’s tracer provider at Zespan’s /v1/otel endpoint and also call instrumentLiveKitSession, every turn is counted twice and cost and token totals double. Zespan does not remove the duplicates. The SDK warns once at attach time if OTEL_EXPORTER_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT points at a Zespan host. Exporting to LiveKit Cloud as well is fine; that never reaches Zespan.
Other overlaps are handled for you:
  • While a session is instrumented, the SDK drops the livekit-agents OpenTelemetry scope from Zespan’s own OTel exporter (TypeScript even with captureExternalSpans on).
  • If your LiveKit LLM plugin uses the openai package, Zespan’s provider auto-patching skips the request the plugin makes, so a model step is recorded once. A model call you make yourself inside a tool is still recorded.

Guardrails

Guardrails are opt-in. They run your project’s guardrails and policies inside the voice pipeline and can stop a reply before the caller hears it. Two calls turn them on: guardrails on the instrumentation, and guardLiveKitAgent / guard_agent on each agent.
guardrails: true turns on all three stages. An object turns on every stage it does not name, unless it names one explicitly: { output: true } is the output stage only.
Only agents you pass to guardLiveKitAgent / guard_agent are guarded. When guardrails is on and an agent that was never guarded becomes active, for example after a handoff, the SDK warns once per session (agent <id> is not guarded) and does not guard it for you, because changing an agent in the middle of a turn would race LiveKit. Call guardLiveKitAgent on every agent you hand off to.

The stages

  • A redact answer on the input stage replaces the caller’s text with the redacted text before the model sees it. On the output stage the redacted sentence is spoken instead of the original.
  • Budgets are real time on the call. The input check adds to LiveKit’s end-of-turn delay. The first output sentence’s check adds to time to first audio. Later sentences are checked while the previous one is spoken, so they add nothing unless a check is slower than speech. Every check sends its budget to the server as a deadline, and the server applies each rule’s own on-error setting to anything it could not run in time.
  • Text is split into sentences at ., !, ? or …, or after 240 characters.

What the caller hears

A turn blocked at input says only blockedLine. A turn blocked at output has already spoken the sentences that were allowed, because a spoken sentence cannot be unsaid; the caller hears those sentences and then blockedLine. The trace records how many sentences were spoken first. The assistant message LiveKit stores holds exactly what was said, and the Call tab shows it as “What the caller heard”. The safe line is your text, it is spoken through your text-to-speech like any reply, and Zespan never sends it to a model.

Fail open or closed

When a check gets no answer inside its budget (time-out, network error, a server error), failClosed decides: closed treats it as a block with the reason guardrail_unavailable, open lets the turn through. If you do not set it, Zespan uses your project’s setting, and otherwise closed. In that case the SDK warns once per session, because a Zespan outage then makes every guarded turn say the blocked line. Either way the decision is recorded as unavailable and the guardrail span has an error status.

Local bundle

With a policyBundle / policy_bundle (see Policy as code), an allowed or blocked decision on input and output text costs no network call. Anything the bundle cannot decide is passed to Zespan within the same budget.
Tool checks always go to Zespan, because the bundle has no tool fields. A bundle also hands every check to Zespan when your policies hold tool-argument content rules (they always list a remote type). A project with those rules pays the server round trip on every turn.

What is not guarded

These paths are not checked. Plan for them.
  • Typed input you send yourself. Text a caller types into the room is guarded. Text you pass in your own code through generateReply({ userInput }) (Python generate_reply(user_input=...)) is not.
  • session.say() text. It does not pass through the model node, so it is not output-checked.
  • Realtime models. The model’s audio does not pass through the text node, so input and output checks do not apply to realtime sessions. The SDK warns once. Tool checks still apply.
  • Agents you did not guard, as above.
  • A reply started early. LiveKit can start generating a reply while your turn hook is still running (preemptive generation). A blocked turn never speaks that reply, but the model provider may already have received the caller’s text. If your provider must never see text a guardrail blocks, turn preemptive generation off in your LiveKit turn handling.

What is recorded

Every guard decision is a guardrail span under the turn, with the stage (input, output or tool), the action (allowed, blocked, redacted, warned), the source (server or local) and the outcome (answered or unavailable). The span never holds the checked text or a reason. The turn root summarises them: lk_guardrail_blocked, lk_guardrail_redacted, lk_guardrail_unavailable, lk_guard_input_ms, lk_guard_first_sentence_ms, lk_guard_spoken_before_block. They show on the trace page and in the Call tab.

Guarded tools

The tool stage checks a function tool before its code runs. It uses the same checks as other Zespan integrations: tool-safety packs (commands, SQL, URLs and file paths) and rules on tool arguments. guardLiveKitAgent / guard_agent guards the agent’s tools, and the session’s own tools when the tools stage is on. To guard tools you build elsewhere, wrap them:
The guarded tool keeps the same name, description and schema, so LiveKit and your model see no difference.
Tool-argument rules run on tool checks only when they are switched on for your Zespan deployment. Without it only the tool-safety packs and the other tool rules apply.
Tool arguments are not redacted. If a rule’s action is redact, a tool check records a warning and the tool runs with the original arguments. Zespan returns no changed arguments for tool rules, so it never claims a redaction it did not make. To stop a call, use a rule that blocks.
Limits: guard_tools returns a toolset or a provider tool unchanged (use guard_agent for those; it guards the function tools inside a toolset). A tool you add to a running session by a path the SDK cannot see is guarded at the next sync of the agent’s tools, not mid-turn.

Evaluations

Voice turns carry what an evaluator needs to read: the caller’s text and the agent’s reply on the turn, and the end-to-end latency, end-of-turn delay and interruption numbers on the turn and the call summary.
  • Model-judged evaluators score the turn’s text. The caller’s text and the agent’s reply are on the livekit.turn root, and LiveKit’s own model steps carry tokens but no text. So a judge scores the root. If a provider wrapper in your app recorded the model call (the root then carries lk_llm_recorded_by_wrapper), the judge scores that wrapper’s call instead and the root gets only the voice evaluators below. The turn is judged once when the SDK links the wrapper’s model call to it; if it cannot link them (for example a model call with no duration reported), both may be judged.
  • Voice evaluators. Four code-only templates in the Voice category (see Voice evaluators): response time (default 1500 ms), end-of-turn delay (800 ms), dead air (a turn with no spoken reply fails; otherwise 3000 ms; not applicable to a turn the agent started, one a guardrail blocked, or one the caller interrupted) and interruption rate (30% of a call’s turns, scored once per call on the call summary). They score live turns only. A caller who simply keeps talking before any agent audio does not leave the earlier turn marked as unanswered: that turn’s reply status is unknown, so it is not dead air. The Latency SLA and Cost budget evaluators skip voice turns.
  • A number the SDK did not report is “Not reported”, never a pass and never 0. A check that needs lk_e2e_latency_ms and finds none records Not checked · <field> was not reported and no score.

Detectors

A voice detector pack reads the numbers above. It is off by default and every check in it is in shadow: findings are recorded for you to read, and they never reach Issues or fix verification until Zespan releases them. None of them reads what was said.
The existing detector packs (for example the AI-product checks) read a voice turn’s text only when the server mode FUNCTIONAL_VOICE_TURNS is on. It is off by default and Zespan turns it on.

If you use LiveKit’s OpenTelemetry export instead

If you already export LiveKit’s own spans to Zespan, Zespan maps its lk.* attributes to the same span kinds: turns, model steps, tools and text-to-speech. Use it instead of the native integration (see the warning above). What this path does not have:
  • No speech-to-text spans. LiveKit emits no STT span, so STT cost and latency never arrive.
  • No guardrails. Blocking needs the SDK hooks.
  • No SDK capture controls. captureTranscripts, the SDK’s redaction and the capture markers do not run on it. Content passes only through the server’s own content-capture and PII handling.
  • Audio seconds and characters are read from a JSON attribute rather than typed fields.
  • Tracing and the waterfall only. Turns, model steps and tools appear in the trace list and the turn waterfall. The voice evaluators, the voice detectors and fix verification read only turns from the native integration, so OTel-only LiveKit data does not get them.
lk.pii.participant_identity, lk.pii.room_name and lk.pii.sip.phoneNumber are never used as the user id or tags, and are never stored. The lk.pii.* transcripts and tool arguments follow your content capture setting (see Transcripts and PII).

Troubleshooting

Next steps