LiveKit Agents

Choose a setup method

Start with one method for a call path. Combining SDK tracking with framework OpenTelemetry on the same call can create duplicate interactions.

Recommended: VoxEye SDK

Install

pip install voxeye

VoxEye requires livekit-agents >= 1.0.

Connect your agent

Create the Observability object once at module level, then call attach() inside your entrypoint.

from voxeye import Observability
from livekit.agents import AgentSession, JobContext

obs = Observability(api_key="sk_...", endpoint="https://api.voxmith.com")  # module level

async def entrypoint(ctx: JobContext):
    session = AgentSession(stt=..., llm=..., tts=...)
    obs.attach(session, ctx)                              # sync, fail-open
    await session.start(agent=MyAgent(), room=ctx.room)   # your existing line

That is the whole integration. attach() is wrapped to fail open, so it never raises into your entrypoint.

What attach() does

1. Resets any previous TracerProvider, because LiveKit worker subprocesses are pooled and reused between jobs.
2. Uses the LiveKit job ID as the call_id.
3. Resolves agent_id from your agent_id= override, then ctx.job.agent_name, and falls back to "unknown". Voxmith reconciles the real name from the agent_session span.
4. Reads session.stt, .llm, .tts, and .vad and records each component's provider and model on every span.
5. Installs a gzip OTLP exporter with bearer authentication and an async flush on shutdown.
6. Sends a lifecycle ping so a call shows up immediately and crashes are detected.

Notes

• Call attach() once per entrypoint. Calling it twice replaces the tracer provider mid-call.
• endpoint defaults to http://localhost:8000. Pass your Voxmith endpoint in production.
• Do not combine VoxEye with the manual OpenTelemetry setup below on the same call path. VoxEye already exports the native LiveKit spans, and running both can create duplicate interactions.

Alternative: Voxmith skill

Install the skill once in your coding-agent environment:

npx skills add Voxmith/skills --skill voxmith

Run the framework-specific prompt below from the application root. Review the resulting diff before deploying it.

Use the voxmith skill to add Voxmith analytics to this LiveKit Agents application.
Org ID: your-org-id
Use LiveKit's native OpenTelemetry traces and verify one fresh agent session.

Manual setup: OpenTelemetry

LiveKit Agents already instruments agent sessions, turns, model requests, tool calls, speech, and transcription with OpenTelemetry. Point those native spans at Voxmith; no webhook or Voxmith SDK wrapper is required.

1. Configure the OTLP destination

Set these variables in the agent worker environment:

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otel.voxmith.com/v1/traces
OTEL_EXPORTER_OTLP_HEADERS="X-Voxmith-Org-ID=your-org-id"
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

2. Register one batch exporter

Call LiveKit's tracer-provider hook before AgentSession.start().

from livekit.agents.telemetry import set_tracer_provider
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
set_tracer_provider(provider, metadata={
    "session.id": conversation_id,
    "user.id": user_id,
})

import { telemetry } from '@livekit/agents';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';

const fanout = new telemetry.FanoutSpanProcessor();
const provider = new NodeTracerProvider({
  spanProcessors: [
    new BatchSpanProcessor(new OTLPTraceExporter()),
    fanout,
  ],
});
provider.register();
telemetry.setTracerProvider(provider, {
  metadata: {
    'session.id': conversationId,
    'user.id': userId,
  },
  registerSpanProcessor: (processor) => fanout.add(processor),
});

Install the OTel packages if the application does not already have them:

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

npm install @opentelemetry/api @opentelemetry/exporter-trace-otlp-http @opentelemetry/sdk-trace-node

The TypeScript FanoutSpanProcessor is required by the current OTel 2.x API so LiveKit can attach its metadata processor (and its Cloud exporter, when enabled) after provider construction.

3. Add standard conversation context

Pass metadata to set_tracer_provider; LiveKit copies it to every native span. Use standard attributes rather than Voxmith-specific names:

set_tracer_provider(provider, metadata={
    "session.id": ctx.room.name,
    "user.id": customer_id,
    "user.plan": "enterprise",
    "user.locale": "en-US",
    "conversation.channel": "voice",
    "conversation.environment": "production",
})

If session.id is absent, Voxmith falls back to LiveKit's lk.job_id, then lk.room_name. For user identity, explicit user.id is best; the participant identity on a native user-turn span is a safe fallback.

What appears in Voxmith

• agent_turn spans become the ordered user/assistant conversation turns.
• function_tool spans become tool calls with native arguments, output, and error state.
• LLM request spans retain model, token, and gen_ai.* attributes.
• STT, TTS, speaking, evaluator, session, job, and activity spans remain visible in the trace.
• Native lk.*, standard gen_ai.*, and your custom attributes remain available on events.

LiveKit webhooks are useful for room and participant lifecycle events, but they do not carry the complete agent turn, model, tool, and speech span tree. Use native OTLP export for observability.

Flush on shutdown

Batch export is asynchronous. Register a shutdown callback so the worker sends the final turns before it exits:

async def flush_traces():
    provider.force_flush()

ctx.add_shutdown_callback(flush_traces)

ctx.addShutdownCallback(async () => {
  await provider.shutdown();
});

Verify

Run one real LiveKit agent session, then open Users in Voxmith. Confirm:

1. The user appears under the value sent in user.id.
2. The conversation shows alternating user and assistant turns.
3. The trace contains the LiveKit agent, LLM, tool, STT, and TTS spans used by the session.
4. Tool details show their native input and output.

Troubleshooting

• Register the provider before AgentSession.start(); earlier spans cannot be recovered.
• Use the traces URL ending in /v1/traces with the HTTP/protobuf exporter.
• Confirm X-Voxmith-Org-ID is present in OTEL_EXPORTER_OTLP_HEADERS.
• Do not point a generic OTLP exporter at LiveKit's private observability URL.
• Flush the provider when a short-lived worker or test exits.

References

• LiveKit: Export traces
• LiveKit Python OTel example
• LiveKit TypeScript OTel example
• LiveKit TypeScript setTracerProvider reference

Next steps

• Conversations: review complete voice interactions.
• Events: inspect native LiveKit spans and attributes.
• Tool calls: analyze tool arguments, results, errors, and latency.