> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LiveKit Agents Integration Server

> Use livekit-plugins-spatius in a LiveKit Agents worker.

This guide covers the server side of [LiveKit Agents Integration](/livekit-agents/overview). Your LiveKit Agents worker uses `livekit-plugins-spatius` to send avatar speech audio to Spatius and receive Spatius-published audio and motion data in the LiveKit room.

***

## Using the LiveKit Agents framework

If you already use [LiveKit Agents](https://docs.livekit.io/agents/) to build your voice agent, add [livekit-plugins-spatius](https://github.com/spatius-ai/livekit-plugins-spatius). The package hooks into your agent pipeline and sends TTS audio to Spatius; Motion Server publishes the lip-synced audio and motion stream into your LiveKit room.

For avatar speech audio source and timing guidance, see [Audio](/concepts/audio).

For a working end-to-end reference, see [AvatarKit Voice Agent Demo](https://github.com/spatius-ai/spatius-avatar-demo/tree/main/platform-integrations/livekit-agents-demo/livekit-agents-reference-demo).

### How it works

1. Your agent runs as usual (VAD, STT, LLM, TTS or Realtime), your current AgentSession setup.
2. `livekit-plugins-spatius` intercepts TTS audio from the agent and sends it to Spatius.
3. Motion Server generates motion data from the agent audio and publishes the synchronized audio + motion stream to the same LiveKit room.
4. Your client joins the room and uses the Spatius RTC client to render the avatar.

Interruption and conversation state are handled inside `livekit-plugins-spatius`.

### livekit-plugins-spatius

**Install**

```bash theme={null}
pip install livekit-plugins-spatius
```

<Note>
  `livekit-plugins-spatius` tracks specific `livekit-agents` releases. Pin both in your `pyproject.toml` together — letting your resolver pull the newest `livekit-agents` independently can drift past what the plugin supports and break `AgentSession` construction at runtime. The [quickstart demo](/quickstarts/livekit-agents) shows the currently aligned pair.
</Note>

**Configure**

| Variable             | Required | Description                                                                                                  |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `SPATIUS_API_KEY`    | Yes      | Your Spatius API key                                                                                         |
| `SPATIUS_APP_ID`     | Yes      | Your Spatius app ID                                                                                          |
| `SPATIUS_AVATAR_ID`  | Yes      | Avatar to use                                                                                                |
| `SPATIUS_REGION`     | No       | Region used to compose endpoints. Defaults to `us-west`; `ap-northeast` and `cn-beijing` are also supported. |
| `LIVEKIT_URL`        | Yes      | Your LiveKit server URL                                                                                      |
| `LIVEKIT_API_KEY`    | Yes      | LiveKit API key                                                                                              |
| `LIVEKIT_API_SECRET` | Yes      | LiveKit API secret                                                                                           |

<Accordion title="Advanced: endpoint overrides">
  For normal production use, set only `SPATIUS_REGION` and the plugin composes the endpoints automatically. Leave it unset for `us-west`, or set it to `ap-northeast` or `cn-beijing` for another supported region. Set endpoint overrides only when proxying or testing against a staging environment.

  | Variable                   | Description                                                                                |
  | -------------------------- | ------------------------------------------------------------------------------------------ |
  | `SPATIUS_CONSOLE_ENDPOINT` | Override Console API URL (default: `https://console.<region>.spatius.ai/v1/console`)       |
  | `SPATIUS_INGRESS_ENDPOINT` | Override ingress WebSocket URL (default: `wss://api.<region>.spatius.ai/v2/driveningress`) |
</Accordion>

<Accordion title="Advanced: LiveKit egress room">
  By default, Motion Server publishes the avatar into the same LiveKit room as the agent. For specialized routing setups, pass `livekit_room_name` to publish the avatar into a different room:

  ```python theme={null}
  await avatar.start(
      session,
      room=ctx.room,
      livekit_room_name="avatar-output-room",
  )
  ```

  Use this only when your LiveKit routing intentionally separates the agent room from the room where clients receive avatar audio and motion data. In the default LiveKit Agents Integration flow, leave `livekit_room_name` unset and connect the client to the same room as the agent.
</Accordion>

**Use in your agent**

Create an `AvatarSession` and start it with your agent session and room. `livekit-plugins-spatius` attaches to the pipeline and sends avatar speech audio to Spatius; Motion Server publishes the avatar's audio and motion stream to the room.

```python theme={null}
from livekit.agents import Agent, AgentSession, JobContext, cli, WorkerOptions
from livekit.plugins import spatius

async def entrypoint(ctx: JobContext):
    await ctx.connect()

    session = AgentSession(vad=vad, stt=stt, llm=llm, tts=tts)
    avatar = spatius.AvatarSession()
    await avatar.start(session, room=ctx.room)

    await session.start(agent=YourAgent(), room=ctx.room)

if __name__ == "__main__":
    cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))
```

Full API and options: **[livekit-plugins-spatius](https://github.com/spatius-ai/livekit-plugins-spatius)** (PyPI: [livekit-plugins-spatius](https://pypi.org/project/livekit-plugins-spatius/)).