Agent

Use this quickstart to run the LiveKit Agent + SpatialReal Avatar demo quickly. This page focuses on clone-and-run. The frontend is built with AvatarKit UI, and code-level explanation is in a separate Guide page.

GitHub Repository

Source code for this quickstart.

Code Walkthrough

Backend and frontend architecture walkthrough.

How LiveKit + SpatialReal Work Together

In this architecture, each system has a clear responsibility:

LiveKit handles room lifecycle, client/worker connectivity, microphone transport, and agent dispatch.
SpatialReal takes agent response audio, generates lip-sync + avatar animation, and publishes avatar output back into the room.
Frontend only needs to join LiveKit and render with AvatarKit UI

Prerequisites

Node.js 18+
Python 3.10+
pnpm
uv
SpatialReal credentials (SPATIALREAL_API_KEY, SPATIALREAL_APP_ID, SPATIALREAL_AVATAR_ID)
LiveKit credentials (LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET)
Gemini key (GOOGLE_API_KEY)

Clone the repo and enter the quickstart folder

git clone https://github.com/spatialwalk/avatarkit-voice-agent-demo.git
cd avatarkit-voice-agent-demo/spatialreal-agent-quickstart

Create env files

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

Fill backend/.env:

backend/.env

LIVEKIT_URL=wss://your-project.livekit.cloud # https://cloud.livekit.io
LIVEKIT_API_KEY=your_api_key # https://cloud.livekit.io
LIVEKIT_API_SECRET=your_api_secret # https://cloud.livekit.io

GOOGLE_API_KEY=your_google_api_key # https://aistudio.google.com/api-keys
E2E_GOOGLE_MODEL=gemini-2.5-flash-native-audio-preview-12-2025
E2E_GOOGLE_VOICE=Puck

SPATIALREAL_API_KEY=your_api_key # https://app.spatialreal.ai/apps
SPATIALREAL_APP_ID=your_app_id # https://app.spatialreal.ai/apps
SPATIALREAL_AVATAR_ID=6aed28f9-674c-4ffb-89ee-b447b28aa3ed # https://app.spatialreal.ai/avatars/library

Fill frontend/.env:

frontend/.env

VITE_SPATIALREAL_APP_ID=your_app_id # https://app.spatialreal.ai/apps
VITE_SPATIALREAL_AVATAR_ID=6aed28f9-674c-4ffb-89ee-b447b28aa3ed # https://app.spatialreal.ai/avatars/library
VITE_TOKEN_ENDPOINT=http://localhost:8080/token
VITE_ROOM_NAME=voice-agent-room

Install dependencies

# backend
cd backend
uv sync

# frontend
cd ../frontend
pnpm install

Run the stack (3 terminals)

# Terminal 1: token server
cd avatarkit-voice-agent-demo/spatialreal-agent-quickstart/backend
uv run token_server.py

# Terminal 2: LiveKit agent worker
cd avatarkit-voice-agent-demo/spatialreal-agent-quickstart/backend
uv run agent.py dev

# Terminal 3: frontend
cd avatarkit-voice-agent-demo/spatialreal-agent-quickstart/frontend
pnpm dev

Open http://localhost:3000, click Connect, then Enable Mic to start speaking.

Want to understand the backend dispatch flow and AvatarKit UI frontend logic? See Agent Quickstart Walkthrough.

Getting Started

Concepts

SpatialReal Studio

Resources

GitHub Repository

Code Walkthrough

How LiveKit + SpatialReal Work Together

Prerequisites

Next

GitHub Repository

Code Walkthrough

​How LiveKit + SpatialReal Work Together

​Prerequisites

​Next

How LiveKit + SpatialReal Work Together

Prerequisites

Next