Skip to main content

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.

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 does not monkey patch AgentSession methods. The integration uses LiveKit’s public telemetry provider hooks, so LiveKit helper objects and streaming behavior are preserved.

​
Install

bun add @inference/tracing @livekit/agents

​
Configure Export

Set a stable service name so LiveKit sessions are easy to find in Catalyst. 
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. 
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();

​
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.
Python
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.
Python
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.

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