LiveKit Agents Traces

Inference platform traces LiveKit Agents by connecting LiveKit's native OpenTelemetry tracer to the Inference Tracing provider. Your LiveKit worker keeps using AgentSession, rooms, tools, and model plugins normally; Inference platform 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

Inference Tracing 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.

Install

Configure Export

Set a stable service name so LiveKit sessions are easy to find in the Inference platform.

export INFERENCE_OTLP_ENDPOINT="https://telemetry.inference.net"
export INFERENCE_API_KEY="<your-token>"
export INFERENCE_SERVICE_NAME="livekit-agent"
export INFERENCE_SERVICE_VERSION="2026.05.06"

Initialize Tracing

Initialize tracing before starting LiveKit agent sessions or workers.

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.

import os

from dotenv import load_dotenv
from inference_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.

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, Inference platform 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.

from inference_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 the Inference platform

Open the Inference platform and filter traces by your INFERENCE_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 INFERENCE_SERVICE_NAME and filter by that value.
• Confirm INFERENCE_OTLP_ENDPOINT and INFERENCE_API_KEY are present in the process environment.
• Call tracing.shutdown() before a script exits.
• For Python OpenAI-backed LiveKit agents, use current Inference Tracing packages so OpenAI streaming context managers are preserved.