Zum Hauptinhalt springen
Der Avaluma-LiveKit-Agent ist ein Python-Worker auf Basis des livekit-agents-Frameworks. Er verbindet sich mit einem LiveKit-Raum und steuert einen Avaluma-Avatar, indem er Audio über die AvatarSession-API leitet — die Brücke zwischen deiner Sprach-Pipeline und dem Avatar-Server, der die .hvia-Datei animiert. Zwei einsatzbereite Agent-Muster sind enthalten, sodass du mit dem Ansatz beginnen kannst, der am besten zu deiner Architektur passt.

​
Agent-Muster

Konversations-Agent

Vollständige Sprach-KI-Pipeline: STT → LLM → TTS → Avaluma-Avatar. Angetrieben von LiveKit Inference mit AssemblyAI, OpenAI GPT-4.1-mini und Cartesia Sonic-3.

Externes Audio

Streame rohes PCM-Audio direkt zum Avatar per LiveKit-DataStream und umgehe die AgentSession-Pipeline vollständig — ideal für eigene TTS- oder Audioquellen.

​
So funktioniert die AvatarSession

Beide Agenten basieren auf AvatarSession aus dem Paket avaluma-livekit-plugin. Du instanziierst sie mit deinen Zugangsdaten, rufst avatar.start() auf, und sie übernimmt das Beitreten zum Raum als separater Avatar-Teilnehmer sowie das Weiterleiten der Audio-Frames an den Avatar-Server zum Rendern. 
from avaluma_livekit_plugin import AvatarSession

avatar = AvatarSession(
    license_key=license_key,
    avatar_id=avatar_id,          # entspricht your-avatar-id.hvia
    avatar_server_url=avatar_server_url,
)
await avatar.start(agent_session=session, room=ctx.room)

​
Ein Muster wählen

Konversations-AgentExternes Audio
AudioquelleLiveKit Inference (STT → LLM → TTS)Beliebiger externer Dienst oder Datei
AgentSessionErforderlichOptional
DataStreamVon AvatarSession verwaltetExplizit (lk.audio_stream)
Am besten fürSchlüsselfertige SprachassistentenEigenes TTS / vorerzeugtes Audio

​
Abhängigkeiten

Alle Abhängigkeiten sind in pyproject.toml deklariert und werden von uv verwaltet:
pyproject.toml
[project]
name = "avaluma-livekit-agent"
version = "1.0.0"
description = "Simple example for LiveKit Agents with Avaluma Avatar"
requires-python = ">=3.12"

dependencies = [
    "livekit",
    "livekit-agents[silero,turn-detector]~=1.2",
    "livekit-plugins-noise-cancellation~=0.2",
    "python-dotenv",
    "avaluma-livekit-plugin @ git+https://github.com/avaluma-ai/avaluma-livekit-plugin.git"
]
PaketZweck
livekitLiveKit-RTC-SDK — Raum-, Track- und DataStream-Primitive
livekit-agentsKern-Agent-Framework (enthält silero VAD und turn-detector)
livekit-plugins-noise-cancellationUnterdrückung von Hintergrundgeräuschen per BVC
avaluma-livekit-pluginAvatarSession — Avaluma-Avatar-Integration
python-dotenvLädt Zugangsdaten aus .env.local

​
Voraussetzungen

Stelle vor dem Start eines der Agenten sicher, dass du Folgendes hast:

Docker & Docker Compose

Beide Agenten werden mit einer docker-compose.yaml für einen konfigurationsfreien lokalen Start ausgeliefert.

LiveKit-Konto

Ein LiveKit-Cloud-Projekt oder eine selbst gehostete Instanz. Du brauchst URL, API-Key und API-Secret.

Avatar-Server

Eine laufende avatar-server-Instanz oder den gehosteten Endpunkt unter https://api.avaluma.ai.

Avaluma-Lizenzschlüssel

Dein AVALUMA_LICENSE_KEY aus dem Avaluma-Dashboard — direkt an AvatarSession übergeben.

​
Deinen Agent testen

Sobald Agent und Avatar-Server laufen, verbinde dich mit einem dieser Clients:
ClientWann verwenden
Avaluma Test-ClientFunktioniert mit jedem LiveKit-Setup — selbst gehostet oder Cloud
LiveKit Agent PlaygroundVerfügbar bei Nutzung eines LiveKit-Cloud-Projekts
Setze im LiveKit Agent Playground das Feld Agent Name auf die Umgebungsvariable AGENT_NAME, die du konfiguriert hast (z. B. agent-1). Reagiert der Agent nach dem Ändern des Namens nicht, lade die Seite neu und verbinde dich erneut.