Skip to main content

​
Before you start

Use an existing LiveKit Agents worker and a room that your client can join. Keep its LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET configured. Get the Spatius App ID and API Key from Apps and the Avatar ID from the Avatar Library.

​
Install

​
Configure

Keep the API Key in the worker. The current plugin selects a region automatically when SPATIUS_REGION is unset. Only set it when you need to pin us-west, ap-northeast, or cn-beijing. See Regions for endpoint details.
.env
Load these values through your worker’s existing environment configuration before creating AvatarSession. If you use a local .env file, keep it out of version control.

​
Add the Avatar session

Connect the worker to the LiveKit room, start AvatarSession, then start the agent session. The avatar publishes into the same room.
AvatarSession.start() registers playback RPC handlers on the worker’s local participant. Call await ctx.connect() before await avatar.start(...); otherwise startup fails with cannot access local participant before connecting.
Call this helper from your existing LiveKit Agents entrypoint with your configured AgentSession and Agent. It preserves your choice of STT, LLM, and TTS.
Merge this sequence into your entrypoint rather than adding a second session.start() call. If you already connect to the room, keep that connection before avatar startup. The plugin sends the agent’s speech audio to Motion Server and publishes synchronized audio and motion data into the room. audio_output=False disables the agent’s direct room audio output so the avatar provides playback. Keep any existing input or text settings when merging RoomOptions.

​
Choose the avatar per session

SPATIUS_AVATAR_ID is a convenient default for a fixed-avatar worker. To choose an avatar per conversation, pass the ID explicitly instead:
Your business layer can supply the ID in LiveKit dispatch metadata (ctx.job.metadata). Parse and validate your application’s metadata contract before creating the avatar session. In that flow, omit SPATIUS_AVATAR_ID from the worker environment; SPATIUS_APP_ID and SPATIUS_API_KEY remain worker configuration. The plugin does not require a particular metadata schema.

​
Run locally

With dependencies installed and your environment configured, run the current LiveKit CLI from the Python agent project directory:
The CLI detects agent.py or src/agent.py and reloads the worker when files change. For another entrypoint, pass its path, for example lk agent dev worker.py. See Agent commands. The Python CLI’s dev mode is deprecated and no longer provides in-process hot reload. Use lk agent dev instead of python agent.py dev.

​
Troubleshooting

  • cannot access local participant before connecting: Connect with await ctx.connect() before starting the avatar. A registered worker can receive jobs before its job process joins the room. The plugin’s final credential or network error message can wrap this connection-order error; check the underlying traceback first.
  • no warmed process available: The development worker may create its job process on demand. If the next logs show successful process initialization, this warning indicates a cold start, not an avatar failure.

​
Next steps

Client

Integration demo

Plugin API