Skip to main content

Documentation Index

Fetch the complete documentation index at: https://lemonslice.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

LemonSlice avatars always have natural, expressive hand gestures when they speak. Actions allow you to go a step further and programmatically trigger specific, custom motion sequences that you define, like pointing, waving, or cheering. Our RESTful API makes it easy to integrate actions into all of your workflows. This guide walks you through different design architectures for how and when to leverage this powerful feature in your interactive avatar calls.
Actions are an enterprise-only feature and must be onboarded for your avatar by the LemonSlice team. Contact support@lemonslice.com to get access.

​
Common trigger patterns

​
LLM Tool Calls

LLM tool calls are a great way to trigger actions that naturally flow with the context and emotional arc of your conversation. Examples include:
  • Pointing to emphasize content when screen sharing (e.g. for education applications)
  • Looking away to signal disappointment or boredom (e.g. for roleplaying)
  • Celebrating when the user shares exciting news
For all of these, the LLM can be used to infer from context when the action should be triggered. If you are using our LiveKit Agents integration, you can easily create tool calls that get read by your agent using the function_tool decorator. By default, the function’s docstring is used to give the LLM proper context for when it should be called.
PYTHON
from livekit.agents import Agent, function_tool

class Assistant(Agent):
    @function_tool()
    async def celebrate(self) -> str:
        """Call this function when the user shares positive news."""
        return await self.trigger_action("celebrate")

​
Call Event Triggers

You may want certain actions to be tied to lifecycle events and happen reliably, independent of what’s being said. For example, to make your avatar wave hello at the start of a call, a robust startup pattern is:
  1. Wait for avatar to join the room (see helper)
  2. Trigger wave action
  3. Continue with greeting / conversation
Example code using our LiveKit Agents integration is below. Using this wait pattern avoids a race condition where control calls are sent before the avatar is ready.
PYTHON
avatar = lemonslice.AvatarSession(...)
session_id = await avatar.start(session, room=ctx.room)

avatar_ready = await wait_for_avatar_ready(session_id)
if not avatar_ready:
    return
await trigger_action("wave")
await session.generate_reply(instructions="Greet the user.")

​
Background Actions

Background actions can help make your avatar feel more alive over the course of a call. A common approach is to run a background loop that randomly triggers subtle motions like swaying or body adjustments. Using subtle movements in this way can help improve the realism of your avatar without being overly distracting.

​
External Events

Sometimes, you may want to trigger an action from a product/backend event rather than conversation context. Examples include:
  • Triggering a celebratory dance when viewer count crosses a threshold (livestreaming app)
  • Waving when a VIP joins the room (livestreaming app)
  • Triggering a branded motion when a user completes checkout (website assistant)
  • Reacting to a game win with a celebratory jump (game companion)

​
How to trigger an action

No matter where the intent originates, action playback is triggered by sending a POST request to the LemonSlice control endpoint: 
curl -X POST "https://lemonslice.com/api/liveai/sessions/<session_id>/control" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LEMONSLICE_API_KEY" \
  -d '{
    "event": "pose-trigger",
    "pose_trigger": { "name": "<ACTION_NAME>" }
  }'

​
System Architecture

Action System Architecture
We recommend that developers route triggers through an “action dispatcher” that manages action lifecycles to avoid triggering multiple actions at the same time. However, we have intentionally kept the API simple. At the transport layer, triggering an action only requires a simple POST request. You can keep your runtime architecture simple or advanced depending on your product needs.

​
Demo

Try talking to the avatar on our homepage, and you will see many of these design principles in action:
  • The avatar will wave hello at the start of the conversation (call event trigger)
  • Ask the avatar to wave and it will oblige (LLM tool call)
  • Trigger an action explicitly by clicking the corresponding button (external event trigger)
  • The avatar will periodically sway to add more movement (background action)