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

  • 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.
  • 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 will not be heard by the avatar.
  • Status: beta (0.x). The call client is covered by tests against a stand-in for the call service; run your own end-to-end check against your LiveKit server before going live.

Development

pip install -e ".[test]"
pytest
ruff check . && ruff format --check .

Apache-2.0. © Avarole.

Metadata

Release files for livekit-plugins-avarole 0.1.0

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.0
File Size Uploaded Provenance Actions
livekit_plugins_avarole-0.1.0.tar.gz 20.7 kB With provenance Details for livekit_plugins_avarole-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 38.6 kB

Release files / livekit_plugins_avarole-0.1.0.tar.gz

Download URL livekit_plugins_avarole-0.1.0.tar.gz
Size 20.7 kB
Tags Source
SHA-256 checksum
How to use checksums
632aaff897d8f3f099cc622d329e928bdfdecd2b8f7f7f066cbab45b1dbb11cf
BLAKE2b-256 checksum
How to use checksums
c6b844cf1aa9ec6ca0d7eb104090cb700662677fdc827bebddb61dded7cd6f1d
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.0-py3-none-any.whl

Download URL livekit_plugins_avarole-0.1.0-py3-none-any.whl
Size 17.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dbba9272d69b24bccbb60dbe5847eb74995e19eb977f4658c2ed68de5deaa4f6
BLAKE2b-256 checksum
How to use checksums
3fd918a460a760341ff348109f92a0d4868a913e2a7c8c53628c95b7d8231f88
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.0

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