> ## Documentation Index
> Fetch the complete documentation index at: https://spatialwalk-6179c111.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent

> Run the full LiveKit + SpatialReal agent demo directly from the official repository

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](https://spatialwalk-6179c111.mintlify.site/sdk-reference/web-sdk/avatarkit-ui.md), and code-level explanation is in a separate Guide page.

> **[GitHub Repository](https://github.com/spatialwalk/avatarkit-voice-agent-demo/tree/main/spatialreal-agent-quickstart)**
>
> Source code for this quickstart.

> **[Code Walkthrough](https://spatialwalk-6179c111.mintlify.site/guide/agent-quickstart-walkthrough.md)**
>
> Backend and frontend architecture walkthrough.

## How LiveKit + SpatialReal Work Together

```mermaid actions={false} theme={null}
---
config:
  "look": "handDrawn"
  "theme": "base"
  "themeVariables":
    "background": "#ffffff"
    "textColor": "#111827"
    "lineColor": "#000000"
    "primaryColor": "#e8f4fd"
    "primaryTextColor": "#111827"
    "primaryBorderColor": "#2196F3"
    "secondaryColor": "#f3e5f5"
    "secondaryTextColor": "#000000"
    "secondaryBorderColor": "#9C27B0"
    "tertiaryColor": "#fff3e0"
    "tertiaryTextColor": "#111827"
    "tertiaryBorderColor": "#FF9800"
    "clusterBkg": "#f8fafc"
    "clusterBorder": "#cbd5e1"
    "edgeLabelBackground": "#ffffff"
    "actorBkg": "#e8f4fd"
    "actorBorder": "#2196F3"
    "actorTextColor": "#111827"
    "noteBkgColor": "#fff7ed"
    "noteTextColor": "#111827"
    "signalColor": "#64748b"
    "signalTextColor": "#111827"
---
sequenceDiagram
    participant FE as Frontend (React)
    participant TS as token_server.py
    participant LK as LiveKit
    participant AW as agent.py worker
    participant GM as Gemini Live
    participant SR as SpatialReal Avatar Service

    Note over AW,LK: agent.py is already running & <br/> registered before any room dispatch
    AW->>LK: Start worker and wait for jobs

    FE->>TS: POST /token { room }
    TS->>LK: create room <br/> dispatch agent
    TS-->>FE: { token, url, room, identity }

    FE->>LK: Join room (client token)
    LK->>AW: Dispatch job to running worker
    AW-->>LK: Join room (worker)

    AW->>GM: User audio
    GM-->>AW: AI response audio
    AW->>SR: Forward response audio
    SR-->>LK: Publish avatar audio + animation stream
    LK-->>FE: Deliver room tracks/data
    FE->>FE: SpatialRealAvatarProvider renders avatar
```

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](https://spatialwalk-6179c111.mintlify.site/sdk-reference/web-sdk/avatarkit-ui.md)

## 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`)

**1. Clone the repo and enter the quickstart folder**

```bash theme={null}
git clone https://github.com/spatialwalk/avatarkit-voice-agent-demo.git
cd avatarkit-voice-agent-demo/spatialreal-agent-quickstart
```

**2. Create env files**

```bash theme={null}
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
```

Fill `backend/.env`:

```bash title="backend/.env" theme={null}
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`:

```bash title="frontend/.env" theme={null}
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
```

**3. Install dependencies**

```bash theme={null}
# backend
cd backend
uv sync

# frontend
cd ../frontend
pnpm install
```

**4. Run the stack (3 terminals)**

```bash theme={null}
# Terminal 1: token server
cd avatarkit-voice-agent-demo/spatialreal-agent-quickstart/backend
uv run token_server.py
```

```bash theme={null}
# Terminal 2: LiveKit agent worker
cd avatarkit-voice-agent-demo/spatialreal-agent-quickstart/backend
uv run agent.py dev
```

```bash theme={null}
# 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.

## Next

* Want to understand the backend dispatch flow and AvatarKit UI frontend logic? See [Agent Quickstart Walkthrough](https://spatialwalk-6179c111.mintlify.site/guide/agent-quickstart-walkthrough.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.