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.
  • The avatar's picture is published at its full size (1280x720). Re-encoding it costs about half a CPU core per call.
  • 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.2

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.2
File Size Uploaded Provenance Actions
livekit_plugins_avarole-0.1.2.tar.gz 28.9 kB With provenance Details for livekit_plugins_avarole-0.1.2.tar.gz

Built distribution (wheel)

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

Total release size: 48.6 kB

Release files / livekit_plugins_avarole-0.1.2.tar.gz

Download URL livekit_plugins_avarole-0.1.2.tar.gz
Size 28.9 kB
Tags Source
SHA-256 checksum
How to use checksums
88f5a25b4ef7f23e0cfc54b1f25beaf18825f292029ac925c1a80b699c0f27ca
BLAKE2b-256 checksum
How to use checksums
f61445ffb7345b0bab39606948aa84c3c311e65e8382b63f0b36e676911feabb
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.2-py3-none-any.whl

Download URL livekit_plugins_avarole-0.1.2-py3-none-any.whl
Size 19.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c29381fb9eef8940e9ae3771fe3625acfa375cbb6583dd00bcc5938cb529c5de
BLAKE2b-256 checksum
How to use checksums
147e213ac56eac37205ad3e4f124f6be18d4f926b527f1f8e2bbb57cfb558194
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.2

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.2.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