LiveKit Agents Integration Server

This guide covers the server side of LiveKit Agents Integration. 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 LiveKit Agents

If you already use LiveKit Agents to build your voice agent, add livekit-plugins-spatius. The package hooks into your agent pipeline and sends agent audio to Spatius; Motion Server publishes the lip-synced audio and motion stream into your LiveKit room. For a working end-to-end project, see AvatarKit Voice Agent Demo.

Install

pip install livekit-plugins-spatius

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.
`SPATIUS_AUDIO_FORMAT`	No	Audio format sent to Spatius. Defaults to `AudioFormat.OGG_OPUS`.

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

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:

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.

Use in your agent

from livekit.agents import AgentSession, JobContext
from livekit.plugins import spatius

async def entrypoint(ctx: JobContext):
    session = AgentSession(vad=vad, stt=stt, llm=llm, tts=tts)
    avatar = spatius.AvatarSession(
        avatar_id="...",
    )

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

Full API and options: the plugin reference (GitHub: livekit-plugins-spatius).

Start Here

Quickstarts

Platform Integrations

Standalone Integrations

Concepts

Examples & Support

LiveKit Agents Integration Server

Using LiveKit Agents

Install

Configure

Use in your agent

​Using LiveKit Agents

​Install

​Configure

​Use in your agent

Using LiveKit Agents

Install

Configure

Use in your agent