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

# LiveKit Agents Traces

> Trace LiveKit Agents sessions, model calls, and function tools through LiveKit's native OpenTelemetry spans.

Catalyst traces LiveKit Agents by connecting LiveKit's native OpenTelemetry
tracer to the Catalyst provider. Your LiveKit worker keeps using `AgentSession`,
rooms, tools, and model plugins normally; Catalyst enriches the spans LiveKit
already emits with OpenInference attributes before export.

Use this guide for applications built with `@livekit/agents` in TypeScript or
`livekit-agents` in Python.

## What Is Captured

* `agent_session` spans as OpenInference AGENT spans
* `llm_node`, `llm_request`, and `llm_request_run` spans as LLM spans
* LiveKit function tools as TOOL spans, including tool name, call ID,
  arguments, output, and errors when available
* LiveKit `lk.*` and `gen_ai.*` attributes, mapped into model, provider, token,
  input, and output attributes when LiveKit provides them
* Other LiveKit telemetry spans as CHAIN spans so the full session timeline
  remains visible

Catalyst sets `agent.name` on LiveKit `agent_session` spans from
`lk.agent_name` or `lk.agent_label` when LiveKit provides it. Use stable
LiveKit agent class names or labels, and add a manual `agent_span` around your
own worker/session boundary when your product needs a canonical `agent.id` for
dashboard grouping.

<Info>
  Catalyst does not monkey patch `AgentSession` methods. The integration uses
  LiveKit's public telemetry provider hooks, so LiveKit helper objects and
  streaming behavior are preserved.
</Info>

## Install

<CodeGroup>
  <Metadata text="integrations/traces/livekit-agents-install-typescript" />

  ```bash TypeScript theme={"system"}
  bun add @inference/tracing @livekit/agents
  ```

  <Metadata text="integrations/traces/livekit-agents-install-python" />

  ```bash Python theme={"system"}
  pip install 'inference-catalyst-tracing[livekit-agents]'
  ```
</CodeGroup>

## Configure Export

Set a stable service name so LiveKit sessions are easy to find in Catalyst.

<Metadata text="integrations/traces/livekit-agents-env" />

```bash theme={"system"}
export CATALYST_OTLP_ENDPOINT="https://telemetry.inference.net"
export CATALYST_OTLP_TOKEN="<your-token>"
export CATALYST_SERVICE_NAME="livekit-agent"
export CATALYST_SERVICE_VERSION="2026.05.06"
```

## Initialize Tracing

Initialize tracing before starting LiveKit agent sessions or workers.

<CodeGroup>
  <Metadata text="integrations/traces/livekit-agents-setup-typescript" />

  ```typescript TypeScript theme={"system"}
  import { setup } from "@inference/tracing";
  import * as LiveKitAgents from "@livekit/agents";

  const tracing = await setup({
    serviceName: "livekit-agent",
    modules: { livekitAgents: LiveKitAgents },
  });

  // Start your LiveKit worker or AgentSession normally.
  // LiveKit telemetry now exports through Catalyst.

  await tracing.shutdown();
  ```

  <Metadata text="integrations/traces/livekit-agents-setup-python" />

  ```python Python theme={"system"}
  from inference_catalyst_tracing import setup

  tracing = setup(service_name="livekit-agent")

  # Start your LiveKit worker or AgentSession normally.
  # LiveKit telemetry now exports through Catalyst.

  tracing.shutdown()
  ```
</CodeGroup>

## Text-Only Agent Example

This Python example starts a LiveKit text-only `AgentSession`. It works for smoke
tests and CI because it does not require audio input or output, but it still runs
the real LiveKit session path.

<Metadata text="integrations/traces/livekit-agents-python-text-session" />

```python Python theme={"system"}
import os

from dotenv import load_dotenv
from inference_catalyst_tracing import setup
from livekit import agents
from livekit.agents import Agent, AgentSession, room_io
from livekit.plugins import openai

load_dotenv()


async def entrypoint(ctx: agents.JobContext):
    await ctx.connect()

    tracing = setup(service_name="livekit-support-agent")
    session = AgentSession(llm=openai.LLM(model=os.getenv("OPENAI_MODEL", "gpt-4o-mini")))

    await session.start(
        agent=Agent(
            instructions="You are a concise support agent. Use tools when needed."
        ),
        room=ctx.room,
        room_options=room_io.RoomOptions(
            text_input=True,
            text_output=True,
            audio_input=False,
            audio_output=False,
        ),
        record=False,
    )

    await session.generate_reply(
        user_input="Reply with one sentence confirming you are online.",
        input_modality="text",
    ).wait_for_playout()

    await session.aclose()
    tracing.shutdown()


if __name__ == "__main__":
    agents.cli.run_app(agents.WorkerOptions(entrypoint_fnc=entrypoint))
```

## Function Tools

LiveKit tool spans are captured automatically when the LiveKit runtime emits
`function_tool` telemetry. The span includes the tool name, tool call ID, JSON
arguments, and output when available.

<Metadata text="integrations/traces/livekit-agents-python-tool" />

```python Python theme={"system"}
from livekit.agents import Agent, function_tool


class FrontDeskAgent(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="Help users find appointment information.",
        )

    @function_tool
    async def lookup_appointment(self, user_id: str) -> str:
        return f"{user_id} has an appointment at 10:30 AM."
```

When `lookup_appointment` runs inside an `AgentSession`, Catalyst shows a TOOL
span under the LiveKit session trace.

## Stable Agent Identity

If your application owns a stable agent ID outside LiveKit's runtime telemetry,
wrap the session work with `agent_span()` and start the LiveKit session inside
that context.

<Metadata text="integrations/traces/livekit-agents-agent-identity-python" />

```python Python theme={"system"}
from inference_catalyst_tracing import agent_span

async def start_traced_session(ctx, session) -> None:
    with agent_span(
        tracing.tracer,
        agent_id="front-desk-agent",
        agent_name="Front Desk Agent",
        span_name="front-desk-agent.run",
        session_id="conversation-front-desk-1",
        agent_role="front-desk",
        system="livekit",
    ) as span:
        span.set_input({"room": ctx.room.name})
        await session.start(agent=FrontDeskAgent(), room=ctx.room)
        span.set_output({"status": "session-started"})
```

## Verify In Catalyst

Open Catalyst and filter traces by your `CATALYST_SERVICE_NAME`, for example
`livekit-agent` or `livekit-support-agent`.

A successful LiveKit trace should include:

* An `agent_session` AGENT span for the session
* One or more LLM spans for LiveKit model nodes or requests
* TOOL spans for any function tools the agent called
* Your stable `agent.id` on the outer AGENT span when you add the identity
  wrapper above

For short-lived scripts, always call `tracing.shutdown()` before process exit so
batched spans are flushed.

## Troubleshooting

If you do not see LiveKit spans:

* Initialize tracing before starting the worker or `AgentSession`.
* Set a stable `CATALYST_SERVICE_NAME` and filter by that value.
* Confirm `CATALYST_OTLP_ENDPOINT` and `CATALYST_OTLP_TOKEN` are present in the
  process environment.
* Call `tracing.shutdown()` before a script exits.
* For Python OpenAI-backed LiveKit agents, use current Catalyst tracing packages
  so OpenAI streaming context managers are preserved.