Skip to main content
The fastest way to a good avatar experience is our LiveKit starter project — a Next.js frontend, token server, and Python agent worker wired together with the patterns we recommend for production (ringing UI, secure tokens, bot_ready handling).

​
What you’ll run

03-livekit-app-python is a complete app you can clone and run locally:
ComponentWhat it does
Next.js app + /api/tokenBrowser UI and a server-side token endpoint (keeps your LiveKit secret off the client)
agent/ workerLiveKit Agents worker with STT, LLM, TTS via LiveKit Inference and the LemonSlice avatar plugin
UI before joining a call
UI during an active call
Avatar video takes a few seconds to initialize. The starter project stays in a ringing state until the agent sends a bot_ready event on the lemonslice data topic — then it transitions to the full in-call layout. This avoids the black-screen flash you get if you show video as soon as the participant joins.

​
Prerequisites

​
1. Clone the repo

git clone https://github.com/lemonsliceai/lemonslice-examples.git
cd lemonslice-examples/03-livekit-app-python

​
2. Set environment variables

Required before you run the app. The starter will not connect without a filled-in .env.local. Do not skip this step — copy the example file, then replace every placeholder with your own credentials.
cp .env.example .env.local
Edit .env.local at the repo root (both Next.js and the agent worker read it). Replace the placeholders with your values:
.env.local
# --- Shared (Next.js `/api/token` + LiveKit agent worker) ---
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
AGENT_NAME=lemonslice

# --- Agent only ---
LEMONSLICE_API_KEY=your_lemonslice_api_key
VariableWhere to get it
LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRETLiveKit Cloud project settings
LEMONSLICE_API_KEYLemonSlice API keys
AGENT_NAMEAny dispatch name — default lemonslice works for local dev

​
3. Install dependencies

npm install
cd agent && uv sync && cd ..

​
4. Run locally

npm run dev:all
This starts the web app and agent worker together. Open http://localhost:3000, join a room, and talk to your avatar. If the app fails to connect, confirm .env.local is filled in (step 2) and restart both processes.
Prefer two terminals? Run npm run dev in one and npm run dev:agent in the other. Same result.

​
5. Customize your avatar

Open agent/src/agent.py and change AGENT_IMAGE_URL to any publicly accessible face image. You can also swap STT, LLM, and TTS models in that file. For every AvatarSession option (agent ID, idle timeout, events, shutdown), see LiveKit integration.

​
What’s already handled for you

These are the production patterns baked into the starter project — you get them for free by starting here: Secure token server. Browsers never see LIVEKIT_API_SECRET. Your Next.js route signs a short-lived JWT; the client connects with { token, serverUrl, room }. See the repo README for the /api/token contract. Ringing → active UI. The frontend listens for bot_ready on the lemonslice topic before showing the live avatar — not on ParticipantConnected. See Best practices for the full pattern and disconnect handling. Agent dispatch. The worker registers under AGENT_NAME so LiveKit routes room jobs to your agent automatically.

​
Agent-only prototyping

If you just want to iterate on the agent without a frontend, use 02-livekit-playground-demo and connect via the LiveKit Agents Playground. Come back to 03-livekit-app-python when you’re ready to ship a UI.

​
Next steps

LiveKit integration

Full configuration, RPC events, and graceful shutdown.

Best practices

Agent stack, latency, call lifecycle, and production hardening.