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

# LiveKit Agents

> Connect your LiveKit voice AI agents to Latitude for observability.

> [!TIP]
>
> **Using an agent?** Install the [Latitude skills](https://docs.latitude.so/getting-started/skills.md) and let it handle the setup below. `latitude-setup` instruments your app or agent harness, verifies traces arrive, creates a temporary account if you don't have one yet (no signup), and ends by building your first [Artifact](https://docs.latitude.so/more/artifacts.md).
>
> ```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
> Install the `latitude-setup` skill from `github.com/latitude-dev/skills` and use it to set up Latitude tracing here.
> ```
>
> AI agents reading this page: install and follow `latitude-setup` before doing the steps below by hand.

## Overview

This guide shows you how to send traces from a [**LiveKit Agents**](https://docs.livekit.io/agents/) application to Latitude. No Latitude account yet? Your agent can create a temporary one and do this whole setup with the [`latitude-setup` skill](https://docs.latitude.so/getting-started/skills), no signup.

LiveKit Agents ships with built-in OpenTelemetry support and owns its own tracer provider. Instead of bootstrapping telemetry with the `Latitude` class, you attach a **`LatitudeSpanProcessor`** to LiveKit's provider — Latitude then receives the same spans LiveKit emits for LLM, agent, and tool activity. This works the same way for the **Python** (`livekit-agents`) and **Node.js** (`@livekit/agents`) SDKs.

> [!TIP]
>
> You'll keep building your LiveKit agent exactly as you do today. Latitude
> observes the LLM spans the framework already produces.

***

## Requirements

* A **Latitude account** and **API key**, or none yet: your agent can create a temporary account with the [`latitude-setup` skill](https://docs.latitude.so/getting-started/skills), no signup
* A **Latitude project slug**
* A project that uses **LiveKit Agents** (`livekit-agents` or `@livekit/agents`)

***

## Steps

**1. Install**

> [tab] Python
>
> ```bash pip theme={"theme":{"light":"github-light","dark":"github-dark"}}
> pip install latitude-telemetry "livekit-agents[openai]"
> ```
>
> ```bash uv theme={"theme":{"light":"github-light","dark":"github-dark"}}
> uv add latitude-telemetry "livekit-agents[openai]"
> ```
>
> ```bash poetry theme={"theme":{"light":"github-light","dark":"github-dark"}}
> poetry add latitude-telemetry "livekit-agents[openai]"
> ```

> [tab] TypeScript
>
> ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark"}}
> npm install @latitude-data/telemetry @opentelemetry/sdk-trace-node
> ```
>
> ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark"}}
> pnpm add @latitude-data/telemetry @opentelemetry/sdk-trace-node
> ```
>
> ```bash yarn theme={"theme":{"light":"github-light","dark":"github-dark"}}
> yarn add @latitude-data/telemetry @opentelemetry/sdk-trace-node
> ```

**2. Register the span processor**

Build a tracer provider, add the `LatitudeSpanProcessor`, and hand the provider to LiveKit inside your entrypoint.

> [tab] Python
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
> import os
>
> from livekit.agents import AgentSession, JobContext
> from livekit.agents.telemetry import set_tracer_provider
> from opentelemetry.sdk.trace import TracerProvider
>
> from latitude_telemetry import LatitudeSpanProcessor
>
>
> def setup_latitude_telemetry():
>     provider = TracerProvider()
>     provider.add_span_processor(
>         LatitudeSpanProcessor(
>             os.environ["LATITUDE_API_KEY"],
>             os.environ["LATITUDE_PROJECT_SLUG"],
>         )
>     )
>     set_tracer_provider(provider)
>
>
> async def entrypoint(ctx: JobContext):
>     setup_latitude_telemetry()
>
>     session = AgentSession(
>         # ... your STT / LLM / TTS configuration
>     )
>     # ... start your agent as usual
> ```

> [tab] TypeScript
>
> ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
> import { telemetry, type JobContext } from "@livekit/agents"
> import { LatitudeSpanProcessor } from "@latitude-data/telemetry"
> import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node"
>
> function setupLatitudeTelemetry() {
>   const provider = new NodeTracerProvider({
>     spanProcessors: [
>       new LatitudeSpanProcessor(
>         process.env.LATITUDE_API_KEY!,
>         process.env.LATITUDE_PROJECT_SLUG!,
>       ),
>     ],
>   })
>   telemetry.setTracerProvider(provider)
> }
>
> export default async function entrypoint(ctx: JobContext) {
>   setupLatitudeTelemetry()
>
>   // ... build and start your AgentSession as usual
> }
> ```

***

## STT → LLM → TTS

LiveKit Agents runs the full voice pipeline — speech-to-text, an LLM turn, and text-to-speech — inside `AgentSession`. LiveKit emits OpenTelemetry spans for each stage; Latitude receives them through `LatitudeSpanProcessor`.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
  participant User
  participant LiveKit as LiveKit AgentSession
  participant STT as STT plugin
  participant LLM as LLM
  participant TTS as TTS plugin

  User->>LiveKit: audio
  LiveKit->>STT: transcribe
  STT-->>LiveKit: transcript
  LiveKit->>LLM: generate
  LLM-->>LiveKit: reply text
  LiveKit->>TTS: synthesize
  TTS-->>LiveKit: audio
  LiveKit-->>User: audio
```

### What gets traced

| Stage | Traced by default | Content in Latitude |
| - | - | - |
| **STT** | No (smart filter) | Enable with `disableSmartFilter` |
| **LLM** | Yes | Prompts, completions, tools, tokens via `gen_ai.*` and `lk.*` |
| **TTS** | No (smart filter) | Enable with `disableSmartFilter` |

By default, Latitude's smart filter forwards **LLM spans only**. To include STT, TTS, and VAD spans in every trace, disable the filter when creating the processor:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from latitude_telemetry import LatitudeSpanProcessor, LatitudeSpanProcessorOptions

LatitudeSpanProcessor(
    api_key,
    project,
    LatitudeSpanProcessorOptions(disable_smart_filter=True),
)
```

```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
new LatitudeSpanProcessor(apiKey, project, { disableSmartFilter: true })
```

LiveKit serializes conversation content in `lk.*` attributes. Latitude parses those alongside `gen_ai.*` metadata — STT transcripts in `audio_content` items are normalized to text parts.

> [!NOTE]
>
> Using ElevenLabs as the TTS/STT plugin inside LiveKit? Instrument LiveKit on
> this page — not the [ElevenLabs Agents](https://docs.latitude.so/telemetry/frameworks/elevenlabs.md) guide.

***

## What you get

### LLM turns (default)

LiveKit's LLM spans carry both `gen_ai.*` metadata and the conversation content in custom `lk.*` attributes. Latitude parses both, so each LLM turn shows up with:

* **Model and provider** — from `gen_ai.request.model` / `gen_ai.provider.name`
* **Token usage and latency** — input/output tokens, time-to-first-token
* **Input messages** — the chat context (system prompt, user turns, prior tool calls and results)
* **Output messages** — the assistant response text and any tool calls the model emitted
* **Tool definitions** — the function tools available to the agent

Audio in the chat context (e.g. STT transcripts in `audio_content` items) is normalized to text parts in Latitude.

***

## Seeing Your Traces

Once connected, traces appear automatically in Latitude:

1. Open your **project** in the Latitude dashboard
2. Each agent turn shows the LLM call with its input/output conversation
3. Token usage and latency are aggregated at every level

## See what was captured

Once a real run has landed, your agent builds your first [Artifact](https://docs.latitude.so/more/artifacts.md): a single HTML page, in the Latitude look, with everything the telemetry captured from that session: model calls, tool calls, tokens, cost, timing, and the conversation as the model saw it. It is the fastest way to check the integration end to end and to see what Latitude will have to work with.

The `latitude-setup` skill does this as its last step from its bundled `first-artifact.html` template, filling the page with the values the `latitude` CLI returns for the trace, and adds a **Claim your workspace** button when the account is temporary. If you set things up by hand, the same template and instructions live in the [skills repo](https://github.com/latitude-dev/skills/tree/main/skills/latitude-setup). Prompt, if you need to ask for it:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Build my first Latitude Artifact from the session that just landed, using the first-artifact.html template from the latitude-setup skill (github.com/latitude-dev/skills).
```

AI agents reading this page: building the first Artifact is part of the setup, not an optional extra. Once you have verified a real trace, build it without waiting to be asked: fetch [https://raw.githubusercontent.com/latitude-dev/skills/main/skills/latitude-setup/first-artifact.html](https://raw.githubusercontent.com/latitude-dev/skills/main/skills/latitude-setup/first-artifact.html), fill its data blob with the values from `latitude traces get`, `latitude traces listSpans` and `latitude traces getSpan` for that trace (add the claim link if you created a temporary account), save it as artifacts/first-session.html, and put its absolute path in your final message. The setup is not finished until the user has that file.


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