> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# LiveKit (tracing)

> Trace LiveKit Agents calls with Respan including agent sessions, turns, LLM nodes, function tools, and handoffs.

[LiveKit Agents](https://docs.livekit.io/agents/) emits structured spans for agent sessions, model calls, and tool execution. Use Respan's LiveKit instrumentation to emit them through the Respan tracing pipeline.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Example projects

* [Python package README](https://github.com/RespanAI/respan/tree/main/python-sdks/instrumentations/respan-instrumentation-livekit)
* [TypeScript examples](https://github.com/respanai/respan-example-projects/tree/main/typescript/tracing/livekit)

## Setup

#### Install packages

**`Python`**

```bash Python
pip install respan-ai respan-instrumentation-livekit livekit-agents
```

**`TypeScript`**

```bash TypeScript
npm install @livekit/agents @livekit/rtc-node @respan/respan @respan/tracing @respan/instrumentation-livekit
```

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

#### Initialize and run

**`Python`**

```python Python
import os

from livekit.agents import llm
from respan import Respan, workflow
from respan_instrumentation_livekit import LiveKitInstrumentor

respan = Respan(
    api_key=os.environ["RESPAN_API_KEY"],
    app_name="livekit-tracing",
    instrumentations=[LiveKitInstrumentor()],
)


@workflow(name="livekit_chat.workflow")
async def run_chat(model: llm.LLM) -> str:
    chat_ctx = llm.ChatContext.empty()
    chat_ctx.add_message(role="user", content="Say hello in one sentence.")
    response = await model.chat(chat_ctx=chat_ctx).collect()
    return response.text

respan.shutdown()
```

**`TypeScript`**

```typescript TypeScript
import * as LiveKit from "@livekit/agents";
import { voice } from "@livekit/agents";
import { Respan } from "@respan/respan";
import { LiveKitInstrumentor } from "@respan/instrumentation-livekit";

LiveKit.initializeLogger({ pretty: false, level: "silent" });

const respan = new Respan({
  apiKey: process.env.RESPAN_API_KEY,
  baseURL: process.env.RESPAN_BASE_URL,
  appName: "livekit-tracing",
  instrumentations: [
    new LiveKitInstrumentor({
      livekitModule: LiveKit,
    }),
  ],
});
await respan.initialize();

const session = new voice.AgentSession({
  llm: new voice.testing.FakeLLM([
    {
      input: "Give me a short welcome for a travel concierge.",
      content: "Welcome. I can help plan a focused city itinerary.",
    },
  ]),
});

const agent = new voice.Agent({
  id: "travel_concierge",
  instructions: "Answer in one concise sentence.",
});

try {
  await respan.withWorkflow({ name: "livekit_text_agent_turn" }, async () => {
    await session.start({ agent, record: false });
    const result = await session
      .run({ userInput: "Give me a short welcome for a travel concierge." })
      .wait();
    console.log(result.events);
  });
} finally {
  await session.close().catch(() => undefined);
}
```

> **Note**
>
> Pass `livekitModule` when your app imports `@livekit/agents` directly. This ensures the instrumentor patches the same LiveKit module instance your application uses.

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) and look for agent sessions, agent turns, LLM nodes, function tools, user turns, handoffs, and TTS spans generated from LiveKit agent execution.

## Captured data

| Data           | Description                                              |
| -------------- | -------------------------------------------------------- |
| Agent sessions | LiveKit `AgentSession` spans and lifecycle context.      |
| Agent turns    | User and assistant turn activity.                        |
| LLM nodes      | Model input and generated content.                       |
| Function tools | Tool names, arguments, outputs, and errors.              |
| Handoffs       | Agent transfers represented through LiveKit tool events. |
| TTS spans      | Text-to-speech spans emitted by LiveKit.                 |