> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# LiveKit Integration

Automatically track usage for LiveKit Agents using the `LiveKitPaygentHook`.

> **Warning**
>
> **Prerequisite:** Complete the [Voice Agent Setup](/documentation/voice-tracking/voice-agent-setup) before implementing voice tracking.

> **Info**
>
> **How it works.** The `LiveKitPaygentHook` intercepts metrics from LiveKit's `AgentSession` or `VoicePipelineAgent` and maps them to Paygent's voice tracking API. It handles LLM tokens, STT duration, and TTS character counts automatically.

> **Tip**
>
> **Manual Configuration.** If your LiveKit metrics don't include provider/model information, or if you want to override the detected values, you can pass `llm_config`, `stt_config`, and `tts_config` directly to the hook.

## Example Usage

Integrating Paygent into your LiveKit Agent is as simple as creating a hook and attaching it to your session:

**`livekit_agent.py`**

```python title="livekit_agent.py"
from paygent_sdk import Client
from paygent_sdk.wrappers import LiveKitPaygentHook
from paygent_sdk.models import LLMConfig, STTConfig, TTSConfig

# 1. Initialize Paygent
paygent = Client("your-paygent-api-key")

@server.rtc_session()
async def my_agent(ctx: JobContext):
    # 2. Setup your LiveKit AgentSession
    session = AgentSession(...)

    # 3. Attach Paygent Hook
    hook = LiveKitPaygentHook(
        paygent_client=paygent,
        agent_id="your-agent-id",
        customer_name="Customer 123",
        customer_id="customer-123",
        session_id=ctx.job.id, # Use LiveKit job ID as session ID
        indicator_name="voice-call-completed",
        additional_indicators=["total-payout"], # optional
        llm_config=LLMConfig(model="gpt-4o-mini", provider="openai"),
        stt_config=STTConfig(model="nova-3", provider="deepgram"),
        tts_config=TTSConfig(model="sonic-3", provider="cartesia")
    )
    hook.attach(session)

    # 4. Start your session normally
    await session.start(agent=Assistant(), room=ctx.room)
    await ctx.connect()
```

## Why use the LiveKit Hook?

**Automatic Conversion:** Automatically converts LiveKit metric formats (seconds, tokens) into Paygent-ready billing data.

**Session Lifecycle:** Automatically starts and finalizes voice sessions in Paygent based on LiveKit session events.

**Multi-Component Tracking:** Simultaneously tracks LLM tokens, STT minutes, and TTS characters without additional manual tracking code.