> ## 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
> Use LiveKit Agents and Spatius to build voice avatars.
export const LiveKitPluginDiagram = () => {
return
;
};
LiveKit Agents Integration is a **Platform Integration**. Use it when your voice agent runs in [LiveKit Agents](https://docs.livekit.io/agents/) and you want `livekit-plugins-spatius` to connect that agent worker to Motion Server. The package attaches to your agent and pipes agent audio to Motion Server; Motion Server publishes lip-synced audio and motion data back into the same LiveKit room.
LiveKit Agents is the platform integration; the [RTC Adapter](/sdk-reference/web-sdk/rtc-adapter) (`@spatius/avatarkit-rtc`) is the Web client adapter that renders the avatar stream from the LiveKit room. The LiveKit room itself is the transport.
**Web Only:** The current AvatarKit RTC client demo path targets Web. LiveKit ships iOS and Android client SDKs, but Spatius does not yet provide iOS or Android demos for this path.
## At a glance
| Dimension | LiveKit Agents Integration |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Dev effort** | 🟢 Low if you already use LiveKit Agents; 🟡 Medium if you are adopting LiveKit too. |
| **Latency profile** | ⚡ Ultra-low; agent audio is handled in the LiveKit worker and avatar output returns through the room. |
| **You build** | 🎙️ LiveKit Agents worker wiring, 🔌 Spatius plugin configuration, 🎟️ LiveKit token flow, and 🌐 Web RTC client. |
| **You do not build** | 🚫 A custom Server SDK pipeline or downstream transport. |
| **Best first demo** | 🚀 [LiveKit Agents Integration quickstart](/quickstarts/livekit-agents). |
| **Client support** | 🌐 Web today |
## Architecture
* **LiveKit room** handles transport.
* **Agent worker** runs your voice agent with `livekit-plugins-spatius` attached.
* **Motion Server** generates motion data from the agent audio and publishes the synchronized audio + motion stream back into the room.
* **AvatarKit RTC client** joins the room and renders the avatar.
Spatius is not a video streaming service. Even when you use LiveKit as the transport layer and LiveKit Agents as the voice agent framework, LiveKit transports avatar audio and motion data, not finished avatar video. `@spatius/avatarkit` renders the avatar locally in the browser.
## Frontend installation
```bash theme={null}
pnpm add @spatius/avatarkit-rtc @spatius/avatarkit
```
```bash theme={null}
npm install @spatius/avatarkit-rtc @spatius/avatarkit
```
```bash theme={null}
yarn add @spatius/avatarkit-rtc @spatius/avatarkit
```
```bash theme={null}
bun add @spatius/avatarkit-rtc @spatius/avatarkit
```
## Frontend setup
Configure your build tool to load the AvatarKit WebAssembly assets. See [Toolchain Setup](/sdk-reference/web-sdk/toolchain).
* For drop-in React components, use [AvatarKit UI](/sdk-reference/web-sdk/avatarkit-ui).
* To own the UI and connection flow yourself, use the JavaScript API below.
```typescript theme={null}
import { AvatarSDK, DrivingServiceMode } from '@spatius/avatarkit'
await AvatarSDK.initialize('your-app-id', {
drivingServiceMode: DrivingServiceMode.backend,
})
```
```typescript theme={null}
const avatar = await AvatarManager.shared.load('avatar-id')
const container = document.getElementById('avatar-container')!
const avatarView = new AvatarView(avatar, container)
```
```typescript theme={null}
import { AvatarPlayer, LiveKitProvider } from '@spatius/avatarkit-rtc'
const provider = new LiveKitProvider()
const player = new AvatarPlayer(provider, avatarView, {
logLevel: 'warning',
})
```
```typescript theme={null}
await player.connect({
url: 'wss://your-livekit-server.com',
token: 'your-livekit-token',
roomName: 'room-name',
})
```
```typescript theme={null}
// Start microphone publishing
await player.startPublishing()
// Stop microphone
await player.stopPublishing()
// Disconnect when done
await player.disconnect()
```
Full RTC client API reference: [LiveKit Agents Client](/livekit-agents/client).
## LiveKit Agents plugin installation
```bash theme={null}
pip install livekit-plugins-spatius
```
```bash theme={null}
uv add livekit-plugins-spatius
```
## Server setup
If you already use [LiveKit Agents](https://docs.livekit.io/agents/), add `livekit-plugins-spatius` to your agent worker. The package attaches to your `AgentSession` and pipes TTS audio to Spatius; Motion Server publishes the resulting audio and motion data to the same LiveKit room.
Required environment variables:
* Spatius: `SPATIUS_API_KEY`, `SPATIUS_APP_ID`, `SPATIUS_AVATAR_ID`
* Optional region: `SPATIUS_REGION` defaults to `us-west`
* LiveKit: `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`
Create an `AvatarSession` and start it with your agent session and room:
```python theme={null}
from livekit.agents import AgentSession, JobContext
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)
```
See the [LiveKit Agents Integration Server guide](/livekit-agents/server) for the full `livekit-plugins-spatius` flow, interruption behavior, and API links.
## Next steps
Run the end-to-end LiveKit Agents voice avatar demo.
Add `livekit-plugins-spatius` to your LiveKit Agents worker.
Render the avatar in your Web app with `@spatius/avatarkit-rtc`.