Skip to main content
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 avatar speech audio source and timing guidance, see Audio. 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; ap-northeast and cn-beijing are also supported.
LIVEKIT_URLYesYour LiveKit server URL
LIVEKIT_API_KEYYesLiveKit API key
LIVEKIT_API_SECRETYesLiveKit API secret
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.
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)
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 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).