Python SDK

LiveKit Agents' uploader (LIVEKIT_OBSERVABILITY_URL, see Connect your agent) is the default connection. The Python SDK, voicegateway.attach(session), adds what the uploader cannot do:

• Send to VoiceGateway without LIVEKIT_OBSERVABILITY_URL, so LiveKit Cloud's own observability stays.
• Put your own fields on a call, filterable in the call list.
• Report user and agent state while the call is still running.

InstallCopy Anchor Link

uv add voicegateway==1.0.0rc6
# or: pip install --pre voicegateway

The SDK follows VoiceGateway's 1.0.0 previews: 1.0.0rc6 is 1.0.0-preview.6 in Python's version form. A pre-release installs only with an exact pin or --pre (uv add --prerelease allow voicegateway); without either, pip picks the retired 0.x package. Python 3.11 to 3.13, livekit-agents 1.8.6 or later.

AttachCopy Anchor Link

import voicegateway


@server.rtc_session(agent_name="my-agent")
async def entrypoint(ctx: agents.JobContext) -> None:
    session = AgentSession(...)
    vg = voicegateway.attach(session, fields={"customer": "acme"})
    await session.start(room=ctx.room, agent=MyAgent())

Call attach in the job entrypoint, before session.start. Set:

VOICEGATEWAY_URL=https://<host>/ingest/<organisation-id>/<project-id>

It is the agent upload URL from the Connect your agent panel. The request is signed with the agent's own LIVEKIT_API_KEY and LIVEKIT_API_SECRET; no new credential.

The SDK sends the session's user and agent states, messages with their latency metrics, per-model usage, tool calls, errors and close. It flushes on close and on job shutdown.

FieldsCopy Anchor Link

vg.set_field("plan", "trial")

Keys match ^[a-z0-9_.-]{1,64}$; values are strings of at most 256 characters. Later values win. An invalid field is dropped and counted on vg.dropped_fields. A call holds at most 64 fields: VoiceGateway drops new keys past that, and a key the call already has still takes a new value.

Fails openCopy Anchor Link

The agent never waits on VoiceGateway, and the SDK never raises into it. Without a URL or credentials, attach logs one warning and does nothing. When VoiceGateway is unreachable or refuses a batch, the SDK retries, then drops the events and counts them on vg.dropped.

With the uploader onCopy Anchor Link

Both can run. The upload stays the source for spans, recording and turns; the SDK adds fields and live state, and nothing is counted twice.

The example agent has an SDK variant: make example-call ATTACH=1.