This release is a pre-release and may not be stable for production use.
voicegateway
attach(session) for LiveKit Agents: sends an AgentSession's events to VoiceGateway.
LiveKit Agents' own uploader (LIVEKIT_OBSERVABILITY_URL) is the default way to connect an agent. Use this SDK for 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.
Install
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.
Attach
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())
vg.set_field("plan", "trial")
Call attach in the job entrypoint, before session.start. It reads:
VOICEGATEWAY_URL: the project's agent upload URL from the console's Connect your agent panel,https://<host>/ingest/<org>/<project>. Or passurl=.LIVEKIT_API_KEYandLIVEKIT_API_SECRET: the agent's own LiveKit credentials, which sign the request.
The SDK flushes on the session's close event and on job shutdown. await vg.close() flushes and stops earlier; it takes at most 2 s.
Fields
Keys match ^[a-z0-9_.-]{1,64}$; values are strings of at most 256 characters. Later values win. An invalid key or value is dropped and counted on vg.dropped_fields; it never raises. 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.
What it sends
user_state_changed, agent_state_changed, conversation_item_added (messages, with each message's own latency metrics), session_usage_updated (per-model usage), function_tools_executed, error and close, plus your fields, as batches of the versioned contract in sdk/contract/v1.schema.json. It reads the job id and room from the job context. It never patches LiveKit.
Fails open
The agent never waits on VoiceGateway and nothing raises into it.
- Missing URL, credentials or job context: one warning, and
attachreturns an attachment that does nothing. - Events wait in a bounded queue (10,000) and are posted every second or every 100 events, gzipped.
- A 429, a 5xx or a network error is retried with backoff; any other 4xx drops the batch. A full queue, a refused batch or a close that runs past 2 s drops events and counts them on
vg.dropped.
What it does not do
- Spans or the call recording: those come only from the uploader. With both on, the upload stays the source for spans, recording and turns, and nothing is counted twice.
- Frameworks other than LiveKit Agents.
Develop
cd sdk/python
uv sync --locked
uv run ruff check && uv run ruff format --check && uv run mypy && uv run pytest
1 maintainer
Metadata
1 maintainer
Release files for voicegateway 1.0.0rc6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| voicegateway-1.0.0rc6.tar.gz | 131.3 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| voicegateway-1.0.0rc6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 141.0 kB
Release files / voicegateway-1.0.0rc6.tar.gz
| Download URL | voicegateway-1.0.0rc6.tar.gz |
|---|---|
| Size | 131.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c3dc60e82876c373c56262d8d5270968447d81bdafd2f27f0b050085442ad2e6
|
|
BLAKE2b-256 checksum How to use checksums |
3ee040fc0e402e6c2a808c6efe0968d8eec90c791728ea463375f51882ebb56a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / voicegateway-1.0.0rc6-py3-none-any.whl
| Download URL | voicegateway-1.0.0rc6-py3-none-any.whl |
|---|---|
| Size | 9.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
92ba68810bbca89ec7f1c5a0d22adb1c3b69307b42701cc19e2b7e4d5f6cdb5a
|
|
BLAKE2b-256 checksum How to use checksums |
92f3098e229d8b0c844b7360f33bf840319ac227eb130325c8584f0025074457
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for voicegateway 1.0.0rc6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
