Skip to main content

Avatar with External Agent

This example demonstrates how to use an external agent to control an avatar in a LiveKit room. It uses LiveKit Ingress to connect any external agent to the avatar.

Start the Avatar only Agent​

avatar-only-agent.py
from dotenv import load_dotenv
from avaluma_livekit_plugin import LocalAvatarSession
from livekit.agents import (
    JobContext,
    WorkerOptions,
    cli,
)

load_dotenv(".env.local")


async def entrypoint(ctx: JobContext):
    # Add any other context you want in all log entries here
    ctx.log_context_fields = {
        "room": ctx.room.name,
    }

    avatar = LocalAvatarSession(
        license_key="",  # Optional
        avatar_id="2025-09-06-Kadda_very_long_DS_v2_release_v5_gcs",  # Avatar identifier
        assets_dir="assets/avatars"),
    )
    # Start the avatar and wait for it to join
    await avatar.start(room=ctx.room)
    await ctx.connect()


if __name__ == "__main__":
    cli.run_app(
        WorkerOptions(entrypoint_fnc=entrypoint, job_memory_warn_mb=4096, agent_name="")
    )

Creating an Ingress for the LiveKit Room​

In order to create an Ingress external audio into a LiveKit room, you need to create an Ingress via the LiveKit Ingress API.

When creating the ingress it's importent to set participant_identity to external-agent-ingress

note

Even if all ingress types are supported, we recommand using WHIP as input type due to the lowest latency.