> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LiveKit Agents

> Trace, guard and measure LiveKit voice agents with instrumentLiveKitSession and instrument_session: one trace per turn, speech-to-text and text-to-speech spans, audio pricing, guardrails that block before the caller hears anything, and voice detectors.

> [!NOTE]
>
> 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](https://docs.zespan.com/dashboard/sessions.md), 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

```bash TypeScript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
npm install @zespan/sdk @livekit/agents
```

```bash Python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
pip install "zespan[livekit]"
```

`@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.

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
import { zespan, instrumentLiveKitSession } from "@zespan/sdk";
import { defineAgent, voice } from "@livekit/agents";

zespan.init({ apiKey: process.env.ZESPAN_API_KEY! });

export default defineAgent({
  entry: async (ctx) => {
    const session = new voice.AgentSession({
      stt: "deepgram/nova-3",
      llm: "openai/gpt-4.1-mini",
      tts: "cartesia/sonic-2",
    });

    const zs = instrumentLiveKitSession(session, {
      jobContext: ctx,
      agentName: "support-voice",
      tags: { line: "billing" },
    });

    await session.start({
      agent: new voice.Agent({ instructions: "You are a helpful support agent." }),
      room: ctx.room,
    });

    ctx.addShutdownCallback(async () => {
      await zs.flush();
    });
  },
});
```

```python Python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
import os

import zespan
from zespan.integrations import instrument_session
from livekit.agents import Agent, AgentSession, JobContext

zespan.init(api_key=os.environ["ZESPAN_API_KEY"])

async def entrypoint(ctx: JobContext):
    session = AgentSession(
        stt="deepgram/nova-3",
        llm="openai/gpt-4.1-mini",
        tts="cartesia/sonic-2",
    )

    zs = instrument_session(
        session,
        job_context=ctx,
        agent_name="support-voice",
        tags={"line": "billing"},
    )

    await session.start(
        agent=Agent(instructions="You are a helpful support agent."),
        room=ctx.room,
    )

    ctx.add_shutdown_callback(zs.aflush)
```

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

| TypeScript | Python | What it does |
| - | - | - |
| `jobContext` | `job_context` | The entrypoint's `ctx`. The session id becomes `lk:<job id>`. Without it Zespan reads the job id from LiveKit if it can, and otherwise generates an id. |
| `agentName` | `agent_name` | Fixes the agent name for the whole session. Default: the active LiveKit agent's id, following handoffs. |
| `sessionId` | `session_id` | Your own session id instead of `lk:<job id>`. |
| `userId` | `user_id` | A user id you choose. Unset by default. |
| `userIdFrom: "participant_identity"` | `user_id_from="participant_identity"` | Opt in to using LiveKit's participant identity as the user id. |
| `tags` | `tags` | Tags merged on top of the defaults (`lk_agent_framework`, `lk_mode`). |
| `captureTranscripts` | `capture_transcripts` | Turn transcripts off while keeping other prompt capture. Default: follows `storePrompts`. |
| `turnSettleMs` | `turn_settle_ms` | How long Zespan waits for late text-to-speech metrics before it sends a turn. Default 1500 ms. |
| `guardrails` | `guardrails` | Turn on [guardrails](#guardrails). |

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.

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
livekit.turn            the turn: caller said, agent answered
├─ stt                  speech-to-text for this turn
├─ chat                 one per model step (a tool loop gives several)
├─ tool.<name>          one per tool call
├─ handoff              when the agent handed over inside the turn
├─ tts                  one per text-to-speech request
└─ guardrail            one per guard decision, when guardrails are on
```

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.

| Field | Meaning |
| - | - |
| `latency_ms` | From the caller stopping to the agent's message settling |
| `ttft_ms` | Time to the model's first token |
| `lk_e2e_latency_ms` | Caller stopped speaking to agent audio started |
| `lk_end_of_turn_delay_ms` | How long LiveKit waited to decide the caller had finished |
| `lk_transcription_delay_ms` | Speech-to-text delay (the STT latency LiveKit measures; streaming STT has no request duration) |
| `lk_on_user_turn_completed_delay_ms` | Time spent in your turn-completed hook (includes the input guard) |
| `lk_tts_ttfb_ms` | Text-to-speech time to first byte |
| `lk_playback_latency_ms` | Playback latency |
| `lk_interrupted` | The caller interrupted the agent |
| `lk_answered` | `true` when the agent produced speech for the turn, `false` when the turn ended with none, absent when unknown |
| `lk_turn_origin` | `user`, or `agent` for agent-initiated speech |
| `conversation_turn` | Turn number in the call, starting at 1 |

The child spans carry the unit each one is priced in:

| Span | Fields |
| - | - |
| `chat` | `provider`, `model`, input, output, cached and reasoning tokens, `latency_ms`, `ttft_ms`, `status` (`cancelled` for an interrupted step) |
| `stt` | `audio_duration_seconds`; token counts only for token-billed models; `latency_ms` left empty for streaming STT |
| `tts` | `characters_count`, `audio_duration_seconds`, time to first byte as `ttft_ms`, `latency_ms`; token counts only for token-billed models |
| `tool.<name>` | Name, call id, `status`, `error_code` when the tool returned an error, `latency_ms`; arguments and results only with `storeToolIO` |

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](#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

| Field | Default |
| - | - |
| `agent_name`, `agent_id` | The active agent, following handoffs. `agent_role` is `coordinator` for the first agent and `specialist` after a handoff |
| `session_id` | `lk:` plus the LiveKit job id, which is per dispatch and carries no personal data |
| `user_id` | **Unset.** LiveKit treats participant identity, room name and SIP phone numbers as personal data, so none of them is read unless you opt in |

## 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"`.

> [!NOTE]
>
> 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](https://docs.zespan.com/sdk/pii-redaction.md) 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.

> [!WARNING]
>
> 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:

| Counts unpriced spans ("N spans unpriced") | Does not yet |
| - | - |
| Trace and session totals | The trace list cost column |
| Cost attribution | The overview cost tiles |
| The spend page | Totals read from Zespan's pre-aggregated views, which still add an unpriced span as \$0 |
| Cost alerts (partially: the alert message carries the count, but an alert does not fire on unknown spend alone) | |

A [cost ceiling guardrail](https://docs.zespan.com/dashboard/guardrails.md) 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

> [!WARNING]
>
> 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](https://docs.zespan.com/dashboard/guardrails.md) 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.

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
import { instrumentLiveKitSession, guardLiveKitAgent } from "@zespan/sdk";

const zs = instrumentLiveKitSession(session, {
  jobContext: ctx,
  guardrails: {
    blockedLine: "Sorry, I can't help with that.",
    failClosed: true,
    budgets: { inputMs: 300, outputSentenceMs: 250, toolMs: 300 },
  },
});

const agent = new voice.Agent({ instructions: "You are a helpful support agent." });
guardLiveKitAgent(agent, zs);

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

```python Python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
from zespan.integrations import instrument_session, guard_agent

zs = instrument_session(
    session,
    job_context=ctx,
    guardrails={
        "blocked_line": "Sorry, I can't help with that.",
        "fail_closed": True,
        "budgets": {"input_ms": 300, "output_sentence_ms": 250, "tool_ms": 300},
    },
)

agent = Agent(instructions="You are a helpful support agent.")
guard_agent(agent, zs)

await session.start(agent=agent, room=ctx.room)
```

`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.

| Option (TypeScript / Python) | What it does |
| - | - |
| `input`, `output`, `tools` | Switch a stage on or off |
| `failClosed` / `fail_closed` | What a check that gets no answer in time means (see below) |
| `blockedLine` / `blocked_line` | What the caller hears when a turn is blocked. Default `Sorry, I can't help with that.` An empty string means say nothing |
| `budgets` | Time limit per stage in milliseconds: `inputMs`, `outputSentenceMs`, `toolMs` (Python: `input_ms`, `output_sentence_ms`, `tool_ms`) |
| `policyBundle` / `policy_bundle` | A [local policy bundle](#local-bundle) that decides without a network call |

> [!WARNING]
>
> 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

| Stage | Where it runs | Default budget | What a block does |
| - | - | - | - |
| **Input** | On each finished caller turn, in `on_user_turn_completed`, and on typed text sent into the room | 300 ms | The model is never called. The agent says `blockedLine` and the turn ends |
| **Output** | On the reply text, sentence by sentence, before text-to-speech | 250 ms per sentence | The reply stops. The agent says `blockedLine` once and no more model text is spoken |
| **Tool** | Before a function tool's own code runs | 300 ms | The tool does not run (see [Guarded tools](#guarded-tools)) |

* 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](https://docs.zespan.com/dashboard/sessions.md#call-tab-voice-sessions) 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](https://docs.zespan.com/policies/as-code.md)), 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.

> [!NOTE]
>
> 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

> [!WARNING]
>
> 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](https://docs.zespan.com/dashboard/traces.md#voice-turn-latency-waterfall) and in the [Call tab](https://docs.zespan.com/dashboard/sessions.md#call-tab-voice-sessions).

## 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](https://docs.zespan.com/dashboard/guardrails.md#tool-safety-packs) (commands, SQL, URLs and file paths) and [rules on tool arguments](https://docs.zespan.com/dashboard/guardrails.md#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:

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
import { guardLiveKitTools } from "@zespan/sdk";

const tools = guardLiveKitTools(
  {
    lookupOrder: llm.tool({ description: "Look up an order", parameters, execute }),
  },
  zs,
);
const agent = new voice.Agent({ instructions: "...", tools });
```

```python Python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
from zespan.integrations import guard_tools

tools = guard_tools([lookup_order, refund_order], zs)
agent = Agent(instructions="...", tools=tools)
```

The guarded tool keeps the same name, description and schema, so LiveKit and your model see no difference.

| Result | What happens |
| - | - |
| Allowed | The tool runs |
| Warned | The tool runs and the decision is recorded. Tool-safety packs warn rather than block |
| Blocked, or unavailable under fail-closed | The tool does not run. LiveKit's `ToolError("This action was blocked by a policy.")` goes back to the model as the tool's output, so the agent can tell the caller. The tool span records `zs_guard_blocked` |

> [!NOTE]
>
> 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.

> [!WARNING]
>
> **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](https://docs.zespan.com/dashboard/evaluations.md#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](https://docs.zespan.com/dashboard/detector-packs.md) 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](https://docs.zespan.com/dashboard/issues.md) or fix verification until Zespan releases them. None of them reads what was said.

| Check | Fires when | Says "can't tell" when |
| - | - | - |
| Dead air (`VO1.dead_air`) | A turn's end-to-end latency is over 3 seconds, or the caller spoke and the agent never replied (not for an interrupted turn or one a guardrail blocked) | The turn did not store its latency or whether the agent replied |
| Repeated barge-in (`VO2.repeated_barge_in`) | At least 3 turns of a call, and at least 30% of them, ended interrupted | The call summary has no turn counts |
| Tool loop in a call (`VO3.tool_loop_in_call`) | One tool is called 5 or more times in a row inside one turn, or one tool returns an error 3 or more times in the call | The call summary has no tool counts |
| Speech-to-text confidence drop (`VO4.stt_confidence_drop`) | At least 3 final transcripts under 0.6 confidence, and at least 25% of those that reported one | The speech-to-text stage reported no confidence |

> [!NOTE]
>
> 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](#transcripts-and-pii)).

## Troubleshooting

| Symptom | Fix |
| - | - |
| No traces | Check `ZESPAN_LIVEKIT` is not `off`. When it is `off` (read when you call the function), the call is a no-op |
| The first turn is missing | Call `instrumentLiveKitSession` / `instrument_session` **before** `session.start()` |
| Last turn or call summary missing | Flush at shutdown: `await zs.flush()` or `zs.aflush` in LiveKit's shutdown callback |
| `ImportError` or no attach on Python | The integration needs Python 3.10 or newer and `pip install "zespan[livekit]"` (`livekit-agents` 1.8 or newer) |
| Cost and tokens look doubled | LiveKit's OTel export also points at Zespan. Remove one of the two |
| A cost reads "unpriced" | The model is not in Zespan's price table. Set a custom price under **Model pricing** in settings |
| `agent <id> is not guarded` warning | Call `guardLiveKitAgent` / `guard_agent` on that agent |
| A latency field is empty | LiveKit did not report it for that turn. Zespan leaves it empty rather than write 0 |

## Next steps

* [Guardrails](https://docs.zespan.com/dashboard/guardrails.md): the rules and policies the voice stages run
* [Sessions](https://docs.zespan.com/dashboard/sessions.md#call-tab-voice-sessions): the Call tab of a voice session
* [Traces](https://docs.zespan.com/dashboard/traces.md#voice-turn-latency-waterfall): the turn latency waterfall
* [Detector packs](https://docs.zespan.com/dashboard/detector-packs.md): the voice pack
* [PII redaction](https://docs.zespan.com/sdk/pii-redaction.md): what is redacted from transcripts
* [Send traces from any OTel-instrumented app](https://docs.zespan.com/sdk/otel-integration.md#send-traces-from-any-otel-instrumented-app-no-zespan-sdk): the OpenTelemetry path
* [Integrations overview](https://docs.zespan.com/sdk/integrations/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.