Skip to main content

livekit-plugins-avarole

Avarole plugin for LiveKit Agents. It puts an Avarole avatar in your LiveKit room: it listens to the people there, answers out loud with its face and voice, and can do everything an Avarole assistant does on the platform (its knowledge base, tickets, scheduling, the tools you enable) plus actions you give it in your own app.

Avarole runs the whole conversation. This package is the bridge: people in your room reach Avarole, and the avatar's video and voice come back into your room as one participant.

people in your room ──(microphone, 16 kHz)──▶ Avarole
Avarole avatar ──(video + voice)──▶ published into your room

Install

pip install livekit-plugins-avarole

You need an Avarole assistant: sign in at app.avarole.com, build one, and copy its agent id and API key from Integrations.

Quick start (LiveKit Agents)

from livekit.agents import JobContext, WorkerOptions, cli
from livekit.plugins import avarole


async def entrypoint(ctx: JobContext):
    await ctx.connect()
    session = avarole.AvatarSession(agent_id="YOUR_AGENT_ID", api_key="sk_YOUR_KEY")
    await session.start(ctx.room)  # the avatar joins and greets whoever is in the room


if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))

The avatar listens to every person in the room (not to other agents), and the call ends when the room closes, you call await session.aclose(), or the plan's session time runs out. Use listen_to=lambda p: p.identity == "alice" to narrow who it hears.

Keep the key in an environment variable, not in code.

Let the avatar act in your app

List what your app can do. The assistant can call these and nothing else. Anything that changes something should set confirm=True: the user must allow it first.

from livekit.plugins.avarole import Action


async def apply_coupon(args):
    return await cart.apply(str(args["code"]))  # validate arguments like any user input


session = avarole.AvatarSession(
    agent_id=...,
    api_key=...,
    confirm=ask_the_user,  # async (title, body) -> bool
    actions=[
        Action(
            "apply_coupon",
            "Apply a coupon code to the cart",
            apply_coupon,
            params={"type": "object", "properties": {"code": {"type": "string"}}, "required": ["code"]},
        ),
        Action("cancel_order", "Cancel the current order", cancel_order, confirm=True),
    ],
)
session.set_screen(
    avarole.ScreenInfo("Checkout", "Cart with 2 items", [{"id": "email", "label": "Email", "filled": True}])
)

Handlers return data, or {"ok": False, "status": "...", "reason": "..."} to report a problem; the assistant reads it and tells the user. At most 3 actions run at once and 30 per minute. set_screen takes labels only, never what the user typed.

Captions, transcripts and the rest

call = session.client
call.on("transcript", lambda text: print("user:", text))  # what the user said
call.on("caption", lambda text: print("avatar:", text))  # what the avatar is saying
call.on("agent_status", print)  # "looking that up"
call.on("emotion", print)
call.on("interrupt", lambda _: print("barge-in"))
call.on("limit", lambda seconds: ...)  # session length, then "ending" and "expired"

Events: status, session, agent_status, transcript, caption, emotion, interrupt, limit, ending, expired, error, end. Listeners may be plain functions or coroutines; one that raises never breaks the call.

Without LiveKit

AvaroleClient is the same call for any app that can supply microphone audio (16 kHz, mono, 16-bit PCM):

from livekit.plugins.avarole import AvaroleClient

async with AvaroleClient(agent_id="...", api_key="sk_...") as call:
    call.on("caption", print)
    await call.send_audio(pcm_bytes)  # any chunk size; sent as 60 ms frames
    join = await call.livekit_join()  # url + token to watch the avatar yourself

It also reads account data: await call.agent_config() (the assistant's public settings) and await call.sessions(limit=50) (past calls, newest first; needs the API key).

Good to know

  • Everyone in the room is mixed into one microphone signal, so several people can talk at once.
  • Calls last at most the agent's session limit (set on the Build page); limit / ending / expired tell you.
  • If the connection drops the client retries three times, then ends the call and emits error.
  • When the call ends, the avatar's video and voice are removed from your room (they are never left frozen there).
  • Page tools (clicking, scrolling) only exist in a browser; here the assistant is told they are unavailable.
  • Use one avatar per room. Another agent that also speaks in the room is not heard by the avatar.
  • Tested against a real LiveKit server (1.13.11) with real WebRTC: picture and voice reach the room, one or several people are heard at the right pitch and rate, reconnects, interrupts, leaving and rejoining, repeated calls without leaks, and a 30-second run with people joining, leaving and the connection dropping twice.

Development

pip install -e ".[test]"
pytest tests --ignore=tests/e2e                   # fast, no server needed

# against a real LiveKit server (WebRTC, nothing faked)
git clone --branch v1.13.11 https://github.com/livekit/livekit && (cd livekit && go build -o ../livekit-server ./cmd/server)
LIVEKIT_SERVER_BIN=$PWD/livekit-server pytest tests/e2e

ruff check . && ruff format --check .

Apache-2.0. © Avarole.

Metadata

Release files for livekit-plugins-avarole 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for livekit-plugins-avarole 0.1.1
File Size Uploaded Provenance Actions
livekit_plugins_avarole-0.1.1.tar.gz 28.5 kB With provenance Details for livekit_plugins_avarole-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for livekit-plugins-avarole 0.1.1
File Interpreter ABI Platform Actions
livekit_plugins_avarole-0.1.1-py3-none-any.whl Python 3 none any Details for livekit_plugins_avarole-0.1.1-py3-none-any.whl

Total release size: 48.0 kB

Release files / livekit_plugins_avarole-0.1.1.tar.gz

Download URL livekit_plugins_avarole-0.1.1.tar.gz
Size 28.5 kB
Tags Source
SHA-256 checksum
How to use checksums
d549d48aef8fa5084f31c7c44468a26d4598cb0d29946a94ba990119233b55a8
BLAKE2b-256 checksum
How to use checksums
cf665eb221bbb6831faa9204b0d570ae7aa920b0a20b41d64f425a88b2987534
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / livekit_plugins_avarole-0.1.1-py3-none-any.whl

Download URL livekit_plugins_avarole-0.1.1-py3-none-any.whl
Size 19.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b1020111e80964d08ee64a65ab17d2f245f7847212c72d8a51e21963390b393d
BLAKE2b-256 checksum
How to use checksums
262c6f7ee0ffc5f725be9b72926d7b6a4ed9953e04284ba2d652b5224d523aa9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for livekit-plugins-avarole 0.1.1

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for livekit_plugins_avarole-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

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.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page