voxgraph 0.2.27

Observability SDK for LiveKit voice agents — captures prompts, metrics, logs, and latency data.

Voxgraph SDK

Observability for LiveKit Voice Agents — see what happens inside the "black box" between user speech and agent response.

Access

This SDK requires a Voxgraph API key.

The SDK sends telemetry exclusively to the Voxgraph backend. Without a valid API key issued by Voxgraph, all telemetry is silently discarded. Contact your Voxgraph account team to obtain credentials.

What does it do?

LiveKit tells you the voice was slow. Voxgraph tells you why your code made the voice slow.

The Voxgraph SDK wraps your LiveKit AgentSession and captures:

Signal	Detail
Logs	Contextually linked to conversation turns
Prompts	Versioned & captured per session
Latency	Code-level waterfall (STT → Your Code → LLM → TTS)
Costs	Token/USD breakdown per turn
Metrics	Structured, typed, and batched

Quick Start

Install

pip install voxgraph

Integrate (2 lines of change)

from livekit.agents import AgentSession, Agent, AgentServer
from voxgraph import VoxSession  # ← add this import

class MyAgent(Agent):
    def __init__(self):
        super().__init__(instructions="You are a helpful assistant.")

    async def on_enter(self):
        self.session.generate_reply()

server = AgentServer()

@server.rtc_session()
async def entrypoint(ctx):
    session = AgentSession(
        stt="deepgram/nova-3:multi",
        llm="openai/gpt-4.1-mini",
        tts="cartesia/sonic-3",
    )

    # ← Wrap with VoxSession — one arg, done
    vox = VoxSession(session, api_key="vxg_...", agent_id="<your-agent-id>")

    await vox.start(agent=MyAgent(), room=ctx.room)
    # Shutdown callback is auto-registered via get_job_context()

That's it. The SDK automatically:

• ✅ Captures session report at call end (transcripts, latency, tool calls, events)
• ✅ Aggregates LLM token counts, STT audio duration, TTS character counts
• ✅ Tags your Python logs with the current session context
• ✅ Sends telemetry to the Voxgraph backend in non-blocking batches
• ✅ Drains all buffered data on session shutdown (cancel-safe)

VoxSession Parameters

VoxSession(
    session,
    api_key="vxg_...",
    agent_id="...",
    environment="main",
    tags={},
    enable_recording=False,
    base_instructions="",
)

Parameter	Type	Default	Description
session	AgentSession	(required)	The LiveKit AgentSession to observe
api_key	str | None	None	Voxgraph API key. Falls back to VOXGRAPH_API_KEY env var if not passed. A warning is emitted and telemetry is discarded if neither is set.
agent_id	str | None	None	UUID of your agent from the Voxgraph dashboard. Required for prompt fetch and usage attribution. Falls back to VOXGRAPH_AGENT_ID env var.
environment	str | None	"main"	Prompt branch to fetch ("main", "dev", "staging", etc.). Falls back to VOXGRAPH_ENVIRONMENT env var.
tags	dict[str, str] | None	{}	Arbitrary key-value metadata attached to the session report (e.g. {"customer_tier": "enterprise"}).
enable_recording	bool	False	When True, captures session audio (user mic + agent TTS as stereo Opus/OGG) and uploads it to Voxgraph-managed storage. See Session Recording.
base_instructions	str	""	Optional user-owned prompt string injected at call time. Use it to pass runtime context that changes per session — such as caller details, account status, business hours, or routing rules. When set, the final instructions are a merge of the Voxgraph-fetched prompt (high priority) and these base instructions. If the remote fetch fails or returns empty, base_instructions are still injected so the agent never loses its core context.

Debug Mode

Set VOXGRAPH_DEBUG=true to see captured telemetry printed to stdout without sending it to the backend:

VOXGRAPH_DEBUG=true python agent.py console

Session Recording

To capture full session audio (user mic + agent TTS as a stereo Opus/OGG file):

vox = VoxSession(session, api_key="vxg_abc123", enable_recording=True)

⚠️ Recording & Consent — Operator Responsibility

Setting enable_recording=True captures audio from both call participants and uploads it to Voxgraph-managed S3 storage. Recording is disabled by default (enable_recording=False).

As the operator deploying this SDK, you are solely responsible for:

• Obtaining explicit user consent before enabling recording
• Complying with applicable laws in your jurisdiction, including:
  • GDPR (EU) — voice recordings may qualify as biometric data; explicit prior consent required
  • CCPA/CPRA (California) — voice recordings are biometric information; notice at collection required
  • US wiretapping laws — ~13 states (CA, IL, FL, MA, WA, etc.) require all-party consent; phone calls (call_channel: "phone") carry the strictest requirements
  • EU AI Act (August 2026) — AI-human interactions must be disclosed

Context-Aware Logging

Any Python logger automatically gets tagged with the current session:

import logging
logger = logging.getLogger(__name__)

@function_tool
async def check_inventory(ctx, product_id: str):
    logger.info(f"Checking stock for {product_id}")  # ← automatically tagged
    result = await db.query(product_id)
    return result

Or use the pre-configured structured logger:

from voxgraph import vox_logger

vox_logger.info("Querying database", product_id=123, stock=True)
# Output: {"event": "Querying database", "product_id": 123, "vox_session_id": "vox_...", ...}

Architecture

Your Agent Code
      │
      ▼
┌─────────────────────┐
│   VoxSession        │  ← Composition wrapper (does NOT extend AgentSession)
│                     │
│  ┌───────────────┐  │
│  │ Log Handler   │  │  ← Tags Python logs with ContextVar session ID
│  └───────┬───────┘  │
│          │          │
│  ┌───────▼───────┐  │
│  │ Telemetry     │  │  ← Async queue → batched HTTP with retry + backoff
│  │ Sender        │  │
│  └───────────────┘  │
│                     │
│  ┌───────────────┐  │
│  │ AudioRecorder │  │  ← Optional. RecorderIO + S3 streaming upload
│  └───────────────┘  │
└─────────────────────┘
      │
      ▼
  Voxgraph Backend

License

Apache License 2.0 — free to use, modify, and distribute.