Agora Convo AI Agent

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:

Token	Where it is used
Agent RTC token	Used by the Convo AI agent so it can join the Agora channel.
Avatar RTC token	`properties.avatar.params.agora_token` so Motion Server can publish avatar output into the same channel.
Client RTC token	Passed 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

Field	Required	Description
`properties.avatar.enable`	Yes	Set to `true` to enable avatar output for the Convo AI agent.
`properties.avatar.vendor`	Yes	Set to `spatius`.
`properties.avatar.params.spatius_api_key`	Yes	Spatius API Key. Keep it server-side.
`properties.avatar.params.spatius_app_id`	Yes	Spatius App ID.
`properties.avatar.params.spatius_avatar_id`	Yes	Avatar ID to render.
`properties.avatar.params.agora_uid`	Yes	Agora UID used by the avatar publisher. Must be distinct from the user and agent UIDs.
`properties.avatar.params.agora_token`	Yes	RTC token for `agora_uid` in `properties.channel`.
`properties.avatar.params.region`	No	Spatius region. See Regions.
`properties.avatar.params.sample_rate`	No	Avatar speech audio sample rate. Use `24000` unless your Convo AI setup requires a different value.
`properties.avatar.params.session_expire_minutes`	No	Spatius session token TTL.

For avatar speech audio source and timing guidance, see Audio.

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.

Start Here

Quickstarts

Platform Integrations

Standalone Integrations

Concepts

Examples & Support

Agora Convo AI Agent

Token usage

Spatius avatar provider

Avatar fields

Next steps

Client

TEN Extension

​Token usage

​Spatius avatar provider

​Avatar fields

​Next steps

Client

TEN Extension

Token usage

Spatius avatar provider

Avatar fields

Next steps