> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spatialreal.ai/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](/sdk-reference/web-sdk/avatarkit-ui), and code-level explanation is in a separate Guide page.

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/spatialwalk/avatarkit-voice-agent-demo/tree/main/spatialreal-agent-quickstart">
    Source code for this quickstart.
  </Card>

  <Card title="Code Walkthrough" icon="book-open" href="/guide/agent-quickstart-walkthrough">
    Backend and frontend architecture walkthrough.
  </Card>
</CardGroup>

## How LiveKit + SpatialReal Work Together

<div style={{ backgroundColor: '#ffffff', border: '1px solid #e5e7eb', borderRadius: 12, padding: 12 }}>
  ```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
  ```
</div>

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](/sdk-reference/web-sdk/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`)

<Steps>
  <Step title="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
    ```
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    # backend
    cd backend
    uv sync

    # frontend
    cd ../frontend
    pnpm install
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Next

* Want to understand the backend dispatch flow and AvatarKit UI frontend logic? See [Agent Quickstart Walkthrough](/guide/agent-quickstart-walkthrough).