Skip to main content

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.

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 the LiveKit Agents framework

If you already use LiveKit Agents to build your voice agent, add 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 a working end-to-end reference, see AvatarKit Voice Agent 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 
pip install livekit-plugins-spatius
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 shows the currently aligned pair.
Configure
VariableRequiredDescription
SPATIUS_API_KEYYesYour Spatius API key
SPATIUS_APP_IDYesYour Spatius app ID
SPATIUS_AVATAR_IDYesAvatar to use
SPATIUS_REGIONNoRegion used to compose endpoints. Defaults to us-west
LIVEKIT_URLYesYour LiveKit server URL
LIVEKIT_API_KEYYesLiveKit API key
LIVEKIT_API_SECRETYesLiveKit API secret
For normal production use, set only SPATIUS_REGION=us-west and the plugin composes the endpoints automatically. Set these only when proxying or testing against a staging environment.
VariableDescription
SPATIUS_CONSOLE_ENDPOINTOverride Console API URL (default: https://console.<region>.spatius.ai/v1/console)
SPATIUS_INGRESS_ENDPOINTOverride ingress WebSocket URL (default: wss://api.<region>.spatius.ai/v2/driveningress)
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. 
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 (PyPI: livekit-plugins-spatius).