Skip to main content

GitHub Repository

Source code for this quickstart.
This quickstart targets the LiveKit Agents Integration path. For Direct Mode first-run paths, see Web / iOS / Android / Flutter Quickstarts.

​
Prerequisites

  • Node.js 18+, pnpm, Python 3.10+, uv
  • Spatius credentials: SPATIUS_API_KEY, SPATIUS_APP_ID, SPATIUS_AVATAR_ID. See Credentials.
  • LiveKit Cloud credentials: LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET.
  • Google AI Studio API key with Gemini Live API access for the chosen model: GOOGLE_API_KEY. Verify access in AI Studio’s “Stream Realtime” tab if unsure.

​
Run it

1

Clone the repo and enter the quickstart folder

git clone https://github.com/spatius-ai/spatius-avatar-demo.git
cd spatius-avatar-demo/platform-integrations/livekit-agents-demo/livekit-agent-quickstart
2

Create env files

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
Fill backend/.env and frontend/.env with your Spatius, LiveKit, and Google AI Studio credentials.
3

Install dependencies

# backend
cd backend
uv sync

# frontend
cd ../frontend
pnpm install
The backend’s pyproject.toml pins livekit-agents, livekit-plugins-google, and livekit-plugins-spatius to matching versions. Keep these pins aligned when bumping the plugin — livekit-plugins-spatius tracks specific livekit-agents releases.
4

Run the stack (3 terminals)

# Terminal 1: token server
cd spatius-avatar-demo/platform-integrations/livekit-agents-demo/livekit-agent-quickstart/backend
uv run token_server.py

# Terminal 2: LiveKit agent worker
cd spatius-avatar-demo/platform-integrations/livekit-agents-demo/livekit-agent-quickstart/backend
uv run agent.py dev

# Terminal 3: frontend
cd spatius-avatar-demo/platform-integrations/livekit-agents-demo/livekit-agent-quickstart/frontend
pnpm dev
Open http://localhost:3000, click Connect, then Enable Mic to start speaking.

​
What this validates

CheckWhat it tells you
Token server returnsLiveKit and Spatius credentials are correct.
Agent worker connectslivekit-plugins-spatius is installed and able to reach Motion Server.
Browser connects + avatar appearsAvatarKit RTC client is wired into the LiveKit room.
Avatar speaks when you talkEnd-to-end agent pipeline (mic → STT → LLM → TTS → Spatius → render) works.

​
Troubleshooting

​
Agent worker exits with TypeError ... 'avatar_identity'

livekit-plugins-spatius tracks specific livekit-agents releases. If your installed livekit-agents is newer than the one the plugin targets, AvatarSession() cannot satisfy the abstract BaseAvatarSession.avatar_identity method added in newer agents core. Confirm backend/pyproject.toml pins all three packages to matching versions (the quickstart pins them at install time), then uv sync:
backend/pyproject.toml
"livekit-agents==1.5.8",
"livekit-plugins-google==1.5.8",
"livekit-plugins-spatius==1.5.8",

​
Gemini Live returns APIError: 1008 ... denied access

The Google project behind GOOGLE_API_KEY cannot reach Gemini Live API for the model in E2E_GOOGLE_MODEL. Options, in order of effort:
  • Verify Live access in AI Studio’s “Stream Realtime” tab with the same key. If the test there fails too, the project itself is denied — issue a key from a project that has Live API enabled.
  • Switch model — change E2E_GOOGLE_MODEL to a model your project is allowed to call. The quickstart defaults to gemini-2.5-flash-native-audio-preview-12-2025; widely-available alternatives include gemini-2.0-flash-live-001 and gemini-live-2.5-flash-preview.
  • Use a different realtime LLM — replace google.realtime.RealtimeModel in agent.py with OpenAI / Azure / xAI Realtime. The reference demos show several provider wirings.

​
Next steps

Server

Add livekit-plugins-spatius to your LiveKit Agents worker.

Client

Render the avatar in your Web app with @spatius/avatarkit-rtc.