prefactor-livekit

prefactor-livekit

LiveKit Agents integration for Prefactor observability. This package wraps livekit-agents sessions and emits Prefactor spans from public LiveKit session events.

Installation

pip install prefactor-livekit

Usage

Factory pattern

from livekit.agents import AgentSession
from prefactor_livekit import PrefactorLiveKitSession

session = AgentSession(...)

tracer = PrefactorLiveKitSession.from_config(
    api_url="https://api.prefactor.ai",
    api_token="your-api-token",
    agent_id="voice-agent",
    agent_name="Voice Agent",
)

await tracer.start(session=session, agent=my_agent)
await tracer.close()

Example repo

This example contains a LiveKit web search agent using Exa search that has been instrumented with prefactor. prefactordev/livekit-agent.

Example runner

The example script has a local smoke mode that emits representative LiveKit session events into Prefactor without needing STT/TTS providers or a room.

uv run python packages/livekit/examples/simple_session.py --mode smoke

It prints the Prefactor instance ID plus ready-to-run Prefactor CLI commands for retrieving the instance and listing spans for the example’s time window.

prefactor agent_instances retrieve <instance-id>
prefactor agent_spans list \
  --agent_instance_id <instance-id> \
  --start_time <recent-start-time> \
  --end_time <recent-end-time> \
  --include_summaries

There is also a model-backed mode for a real text turn:

uv run python packages/livekit/examples/simple_session.py \
  --mode live \
  --model anthropic/claude-sonnet-4-5-20250929

Manual attachment

Use this when your app manages the session lifecycle itself and you just want the LiveKit events traced.

from prefactor_livekit import PrefactorLiveKitSession

tracer = PrefactorLiveKitSession(instance=instance)
await tracer.attach(session)

await session.generate_reply(user_input="hello")

await tracer.close()

Traced span types

• livekit:session
• livekit:user_turn
• livekit:assistant_turn
• livekit:tool
• livekit:llm
• livekit:stt
• livekit:tts
• livekit:state
• livekit:error

Development

uv run pytest packages/livekit/tests -v