Skip to main content

​
Overview

LiveKit Agents provides a realtime framework for voice, video, and physical AI agents. Through our open-source integration you can seamlessly add a LemonSlice avatar to real-time voice AI systems.

​
Quick Start

This section includes a basic usage example and some reference material. For links to more detailed documentation, see Additional resources.

​
Prerequisites

  1. LemonSlice agent information Either a base image URL or a LemonSlice Agent ID.
    • Agent base image — a publicly accessible image URL of your avatar, focused on the face. The image should be 368 × 560 pixels. LemonSlice will automatically center-crop your image to the target aspect ratio if the dimensions do not match the expected values. Best results are achieved with anthropomorphic images where the face and mouth are clearly identifiable.
    • LemonSlice Agent ID
      Selected voices and personalities for a LemonSlice agent will be ignored when using the LiveKit plugin.
  2. LiveKit Agents App

​
Integration Guide

1

Install the plugin

  1. Within your LiveKit Agents app, install the plugin:
# When using PIP
pip install "livekit-agents[lemonslice]"

# When using UV
uv add "livekit-agents[lemonslice]"
2

Authenticate

  1. Create a LemonSlice API key
  2. In your LiveKit Agents app, set LEMONSLICE_API_KEY in your .env file
3

Add AvatarSession to AgentSession

In your LiveKit Agents app, create a lemonslice.AvatarSession alongside your AgentSession:
from livekit import agents
from livekit.agents import AgentSession, RoomOutputOptions
from livekit.plugins import lemonslice

async def entrypoint(ctx: agents.JobContext):
    await ctx.connect()

    session = AgentSession(
        # Add STT, LLM, TTS, and other components here
    )

    avatar = lemonslice.AvatarSession(
        # Publicly accessible image URL for the avatar
        agent_image_url="...",
        # Prompt to guide the avatar's demeanor
        agent_prompt="a person talking"
    )

    # Start the avatar and wait for it to join
    await avatar.start(session, room=ctx.room)

    # Start your agent session with the user
    await session.start(
        # ... room, agent, room_options, etc....
    )
Parameters for lemonslice.AvatarSession. Either agent_image_url or agent_id is required.
ParameterDescription
agent_image_urlA URL to an agent image to use.
agent_idThe ID of the LemonSlice agent.
agent_prompt(Optional) A high-level system prompt that subtly influences the avatar’s movements, expressions, and emotional demeanor. This prompt is best used to suggest general affect or demeanor (for example, “feel excited” or “look sad”) rather than precise or deterministic actions.
agent_idle_prompt(Optional) A high-level system prompt that influences the avatar’s movements, expressions, and emotional demeanor during the idle state.
idle_timeout(Optional) Idle timeout in seconds. Defaults to 60. If a negative number is provided, the session will have no idle timeout.
response_done_timeout(Optional) Time in seconds to wait without receiving new audio bytes before marking the response as complete. Some TTS models do not send an end response event, or do not send it in a timely manner, after transmitting all audio bytes. This parameter enables detection of response completion when such events are missing or delayed.
JavaScript parameters use camelCase. For example: agent_image_url becomes agentImageUrl.
When using the Gemini Live S2S model for realtime interactions, set response_done_timeout=0.5 to handle end of responses correctly.If you encounter stutters or glitches with any other TTS, please contact support@lemonslice.com.
4

Preview

Preview the avatar in the Agents Playground or a frontend starter app that you build.
5

Shutdown the LiveKit room

Gracefully shut down the LiveKit room, LiveKit agent, and/or LemonSlice avatar session:
  1. Call ctx.room.disconnect() to close the LiveKit room connection which will end the LemonSlice avatar session.
  2. Call ctx.shutdown() to stop the Agent’s JobContext and the LemonSlice avatar session if you don’t want to shutdown the LiveKit room.
  3. Call the session control endpoint with the terminate event to shutdown only the LemonSlice avatar without shutting down the LiveKit room or agent.
Where ctx is LiveKit’s agents.JobContext defined by the function annotated with @server.rtc_session()
@server.rtc_session()
async def my_agent(ctx: agents.JobContext):
  ...
If the LemonSlice session is not shut down, the LemonSlice session will remain active until the configured idle timeout is reached or the 30-minute maximum session duration expires.

​
Additional resources

The following resources provide more information about using LemonSlice with LiveKit Agents.

Ready-to-use LemonSlice LiveKit Python Example Agent

LemonSlice LiveKit JS Example Agent

LemonSlice Salary Negotiation Coach Example

LiveKit Documentation

LiveKit Agents Playground

LiveKit Frontend Starter Apps