Skip to main content
Use this page when your voice agent runs on Agora Convo AI. Convo AI owns the managed ASR, LLM, TTS, and agent runtime; Spatius is configured as the avatar provider in the agent’s properties.avatar block. If you run a TEN Framework graph directly instead of starting a managed Convo AI agent, use the TEN Extension guide.

​
Token usage

Agora RTC tokens are used in three places when Spatius avatar output is enabled:
TokenWhere it is used
Agent RTC tokenUsed by the Convo AI agent so it can join the Agora channel.
Avatar RTC tokenproperties.avatar.params.agora_token so Motion Server can publish avatar output into the same channel.
Client RTC tokenPassed to the Web, iOS, or Android client so the user can join the same channel.
The client joins channel with its own UID and RTC token and does not need a Spatius Session Token on this path.
Use distinct Agora UIDs for the user, the Convo AI agent, and the Spatius avatar publisher. Do not reuse the avatar publisher UID as a client UID.

​
Spatius avatar provider

Add properties.avatar to the Convo AI agent configuration: 
{
  "properties": {
    "channel": "room-a",
    "avatar": {
      "enable": true,
      "vendor": "spatius",
      "params": {
        "spatius_api_key": "${SPATIUS_API_KEY}",
        "spatius_app_id": "${SPATIUS_APP_ID}",
        "spatius_avatar_id": "${SPATIUS_AVATAR_ID}",
        "agora_uid": "77777",
        "agora_token": "avatar-rtc-token",
        "region": "us-west",
        "sample_rate": 24000,
        "session_expire_minutes": 30
      }
    }
  }
}

​
Avatar fields

FieldRequiredDescription
properties.avatar.enableYesSet to true to enable avatar output for the Convo AI agent.
properties.avatar.vendorYesSet to spatius.
properties.avatar.params.spatius_api_keyYesSpatius API Key. Keep it server-side.
properties.avatar.params.spatius_app_idYesSpatius App ID.
properties.avatar.params.spatius_avatar_idYesAvatar ID to render.
properties.avatar.params.agora_uidYesAgora UID used by the avatar publisher. Must be distinct from the user and agent UIDs.
properties.avatar.params.agora_tokenYesRTC token for agora_uid in properties.channel.
properties.avatar.params.regionNoSpatius region. See Regions.
properties.avatar.params.sample_rateNoAvatar speech audio sample rate. Use 24000 unless your Convo AI setup requires a different value.
properties.avatar.params.session_expire_minutesNoSpatius server session lifetime.

​
Next steps

Client

Join the Agora channel and render avatar output with AgoraProvider.

TEN Extension

Use spatius_avatar_python when you run a TEN Framework graph directly.