> ## 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.

# Choose Your Integration Path

> Pick a Platform Integration or a Standalone Integration based on whether you build on a third-party agent platform.

<Info>
  Spatius is an **avatar-only** service. It takes avatar speech audio and returns real-time motion data. Conversation logic (ASR, LLM, TTS) and turn-taking are owned by your app or by the agent framework you choose.
</Info>

## Pick your category first

Spatius integrations come in two categories.

<CardGroup cols={2}>
  <Card title="Platform Integrations" icon="tower-broadcast" href="#livekit-agents-integration">
    You already use a third-party realtime / agent platform. Spatius slots in through LiveKit Agents or Agora Convo AI.
  </Card>

  <Card title="Standalone Integrations" icon="code" href="#direct-mode">
    You build directly with Spatius SDKs. Start with Direct Mode, or use Backend Mode when your backend owns the runtime.
  </Card>
</CardGroup>

## Decision matrix

| Category                   | Path                                                          | Choose it when                                                              | What connects to Spatius                                   |
| -------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------- |
| 🧩 Platform Integrations   | **[LiveKit Agents Integration](#livekit-agents-integration)** | You already use LiveKit Agents or want a turnkey voice-agent path.          | 🎙️ LiveKit agent worker through `livekit-plugins-spatius` |
| 🧩 Platform Integrations   | **[Agora Convo AI Integration](/agora-convoai/overview)**     | You already use Agora Convo AI and want avatar output in an Agora channel.  | 🧠 Convo AI `avatar` provider or TEN extension             |
| 🧱 Standalone Integrations | **[Direct Mode](#direct-mode)**                               | You have avatar speech audio and want the smallest client-side integration. | 🧩 AvatarKit client SDK                                    |
| 🧱 Standalone Integrations | **[Backend Mode](#backend-mode)**                             | Your backend owns ASR / LLM / TTS / transport.                              | 🖥️ Server SDK                                             |

## Path snapshots

<CardGroup cols={2}>
  <Card title="Direct Mode" icon="bolt" href="#direct-mode">
    Lowest integration surface. Your backend mints Session Tokens; the client connects to Motion Server and renders locally.
  </Card>

  <Card title="LiveKit Agents" icon="radio" href="#livekit-agents-integration">
    Fastest packaged Web voice-agent path if your stack already uses LiveKit Agents.
  </Card>

  <Card title="Agora Convo AI" icon="tower-broadcast" href="#agora-convo-ai-integration">
    Best when Agora Convo AI or TEN Framework already owns your voice-agent runtime.
  </Card>

  <Card title="Backend Mode" icon="server" href="#backend-mode">
    Highest control and highest ownership. Your backend runs the pipeline and chooses the downstream transport.
  </Card>
</CardGroup>

## Compare integration effort

Use this table before opening an SDK guide. **Dev effort** includes the runtime pieces your team must own in production: conversation pipeline, credentials, token/session handling, transport, reconnect, interruption, and client rendering.

| Path                                                          | Best fit                                                                                   | Latency                                                                                             | Dev effort                                                                                               | What you build                                                                                                    | Client support                                          |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **[Direct Mode](#direct-mode)**                               | You already have avatar speech audio and want the smallest integration.                    | 🕒 **Moderate**<br />Client sends audio to Motion Server directly.                                  | 🟢 **Low**                                                                                               | 🔑 Token endpoint<br />🧩 AvatarKit client integration                                                            | 🌐 Web<br />🍎 iOS<br />🤖 Android<br />📱 Flutter      |
| **[LiveKit Agents Integration](#livekit-agents-integration)** | You already use LiveKit Agents, or you want the fastest packaged Web voice-agent path.     | ⚡ **Ultra-low**<br />Agent audio flows from the LiveKit worker and output returns through the room. | 🟢 **Low** if LiveKit Agents is already in your stack<br />🟡 **Medium** if you are adopting LiveKit too | 🎙️ LiveKit Agents worker<br />🔌 `livekit-plugins-spatius`<br />🎟️ LiveKit token flow<br />🌐 Web RTC client    | 🌐 Web today                                            |
| **[Agora Convo AI Integration](#agora-convo-ai-integration)** | You already use Agora Convo AI or TEN Framework.                                           | ⚡ **Ultra-low**<br />Spatius publishes avatar output into the Agora channel.                        | 🟡 **Medium**                                                                                            | 🧠 Convo AI avatar config or TEN extension<br />🎟️ Agora RTC credentials<br />📡 RTC client setup                | 🌐 Web<br />🍎 iOS<br />🤖 Android                      |
| **[Backend Mode](#backend-mode), own transport**              | Your backend owns ASR / LLM / TTS and you want full transport control.                     | ⚙️ **Low / tunable**<br />Your backend controls chunking, buffering, and delivery.                  | 🔴 **High**                                                                                              | 🖥️ Server SDK session<br />🎙️ Audio pipeline<br />🔀 WebSocket / transport<br />🧩 Client message feed          | 🌐 Web<br />🍎 iOS<br />🤖 Android<br />📱 Flutter      |
| **[Backend Mode](#backend-mode), RTC transport**              | Your backend owns the pipeline, but you want LiveKit or Agora as the downstream transport. | ⚙️ **Low / tunable**<br />RTC transport behavior sits in the middle.                                | 🔴 **High**                                                                                              | 🖥️ Server SDK session<br />📡 RTC egress / room setup<br />🎟️ RTC credentials<br />🧩 Client RTC rendering path | 📡 Depends on provider and AvatarKit RTC client support |

## How to read the effort score

The score is not package-install time. It is the amount of production surface your team owns.

<CardGroup cols={2}>
  <Card title="Conversation pipeline" icon="bot">
    Lower effort when a platform owns ASR / LLM / TTS / turn-taking, or when you already have avatar speech audio. Higher effort when your backend must build and operate the whole pipeline.
  </Card>

  <Card title="Motion Server connection" icon="plug">
    Lower effort when AvatarKit or a platform package owns the connection. Higher effort when your backend opens, recovers, and observes the Server SDK session.
  </Card>

  <Card title="Transport" icon="route">
    Lower effort when transport is built into the path. Higher effort when you design WebSocket, RTC egress, room/channel tokens, reconnect, and buffering.
  </Card>

  <Card title="Client integration" icon="monitor">
    Lower effort when one client package and a quickstart prove the path. Higher effort when multiple platforms or custom rendering/transport glue are required.
  </Card>

  <Card title="Production hardening" icon="shield-check">
    Lower effort means fewer recovery paths and credentials. Higher effort means provider credentials, backend state, room/channel auth, retries, and observability.
  </Card>
</CardGroup>

## LiveKit Agents Integration

LiveKit Agents Integration is the Platform Integration for [LiveKit Agents](https://docs.livekit.io/agents/). The `livekit-plugins-spatius` Python package attaches to your agent's `AgentSession` and pipes agent audio to Motion Server.

Use it when:

* Your backend runs a LiveKit Agents worker.
* You want LiveKit room transport handled for you.
* Your Web client renders avatar audio and motion from the LiveKit room.

<CardGroup cols={2}>
  <Card title="LiveKit Agents Integration guide" icon="book" href="/livekit-agents/overview">
    Add `livekit-plugins-spatius` and the AvatarKit RTC client to your app.
  </Card>

  <Card title="LiveKit Agents Integration quickstart" icon="radio" href="/quickstarts/livekit-agents">
    Run the React + LiveKit Agents + Gemini Live demo.
  </Card>
</CardGroup>

## Agora Convo AI Integration

Agora Convo AI Integration is the Platform Integration for Agora Convo AI. Convo AI is Agora's managed conversational AI service; Spatius is configured as the Convo AI avatar provider in the start-agent request. If you run a TEN Framework graph directly, use the `spatius_avatar_python` TEN extension instead.

Use it when:

* Your voice agent is built with Agora Convo AI.
* You want the Agora channel to carry user audio and avatar output.
* Your Web, iOS, or Android client renders avatar audio and motion from the Agora channel.

<CardGroup cols={3}>
  <Card title="Agora integration guide" icon="book" href="/agora-convoai/overview">
    Choose the Convo AI, TEN Framework, and client setup docs.
  </Card>

  <Card title="Convo AI Agent setup" icon="bot" href="/agora-convoai/convo-ai-agent">
    Add Spatius to the Convo AI start-agent payload.
  </Card>

  <Card title="TEN Extension setup" icon="blocks" href="/agora-convoai/ten-extension">
    Configure Spatius and Agora fields inside a TEN graph.
  </Card>
</CardGroup>

## Direct Mode

Direct Mode maps to `DrivingServiceMode.direct` in SDK code. It is the simplest Standalone Integration: your client app connects to Motion Server directly using a short-lived Session Token issued by your backend.

Use it when:

* You already have avatar speech audio — your own TTS, a TTS provider, or prerecorded audio.
* You want Web, iOS, Android, or Flutter clients to own avatar playback.
* Your backend can host a minimal Session Token endpoint that calls the [Console API](/api-reference/api-reference).

<CardGroup cols={2}>
  <Card title="Direct Mode guide" icon="book" href="/direct-mode/overview">
    Architecture, requirements, and per-platform setup.
  </Card>

  <Card title="Web SDK quickstart" icon="globe" href="/quickstarts/web-sdk">
    Validate App ID, Avatar ID, Session Token, and rendering in a browser.
  </Card>

  <Card title="Flutter SDK quickstart" icon="mobile" href="/quickstarts/flutter-sdk">
    Validate the Flutter package on iOS or Android.
  </Card>
</CardGroup>

## Backend Mode

Backend Mode is the Standalone Integration for teams that need full control over the audio pipeline and downstream transport. Your backend uses the Server SDK to connect to Motion Server, then delivers encoded audio payloads and motion data payloads to AvatarKit clients over a transport you choose.

Use it when:

* Your backend owns ASR, LLM, TTS, turn-taking, and interruption policy.
* You need to tune latency or transport behavior.
* You need a custom WebSocket or RTC transport between your backend and clients.

<CardGroup cols={2}>
  <Card title="Backend Mode guide" icon="server" href="/backend-mode/overview">
    Server SDK, transport options, and architecture.
  </Card>

  <Card title="Browse all demos" icon="github" href="/resources/demo-projects">
    Run the Backend Mode reference implementations.
  </Card>
</CardGroup>

## Transport is a second decision

Transport options live inside an integration path, not as separate top-level choices:

<CardGroup cols={2}>
  <Card title="Direct to Motion Server" icon="bolt" href="/direct-mode/overview">
    Default transport for Direct Mode.
  </Card>

  <Card title="Your own WebSocket" icon="route" href="/backend-mode/own-transport">
    Backend Mode when your backend relays encoded audio payloads and motion data payloads directly to clients.
  </Card>

  <Card title="LiveKit Room" icon="radio" href="/backend-mode/with-livekit">
    Appears in two distinct shapes: LiveKit Agents Integration, or Backend Mode with LiveKit as downstream transport.
  </Card>

  <Card title="Agora channel" icon="tower-broadcast" href="/agora-convoai/overview">
    Used by Agora Convo AI Integration. Server SDK Agora egress is also available for custom Backend Mode work.
  </Card>
</CardGroup>

LiveKit appears in two completely different positions and these must not be confused:

* **LiveKit Agents Integration** uses LiveKit both as the agent framework (via `livekit-plugins-spatius`) and as the room transport. Choose this when you build agents on LiveKit Agents.
* **[Backend Mode with LiveKit](/backend-mode/with-livekit)** uses your own backend with the Server SDK, and merely uses LiveKit as the downstream transport between your backend and your clients. No LiveKit Agents involved.

Agora has a similar distinction:

* **Agora Convo AI Integration** uses Agora Convo AI as the agent platform and an Agora channel as the transport. The Spatius integration is configured through the Convo AI `avatar` provider block, or through `spatius_avatar_python` when you run a TEN Framework graph directly.
* **Backend Mode with Agora egress** is a custom Server SDK pattern where your backend owns the whole pipeline and uses Agora only as the downstream transport. See [Python SDK Agora Egress Mode](/sdk-reference/python-sdk/python-sdk#agora-egress-mode).

## Next steps

<CardGroup cols={2}>
  <Card title="Get credentials" icon="key" href="/getting-started/credentials">
    App ID, Avatar ID, Session Token, and API Key — who issues each and where each is used.
  </Card>

  <Card title="Demo matrix" icon="grid" href="/resources/demo-projects">
    Every runnable demo by platform and integration path.
  </Card>
</CardGroup>