Skip to main content
This guide covers the TEN Framework setup path for Agora Convo AI Integration. Use it when you run and configure a TEN Framework graph directly. The spatius_avatar_python extension receives agent speech audio inside that graph, sends it to Spatius, and configures Motion Server to publish synchronized audio and motion data into the configured Agora channel. If you start a managed Agora Convo AI agent through the REST API, use Convo AI Agent instead. In that path, Spatius is configured through the Convo AI properties.avatar provider block.

spatius_avatar_python

TEN extension source in the TEN Framework repository.

​
How it works

  1. Your TEN graph runs the voice agent pipeline.
  2. The TTS stage sends PCM audio frames to spatius_avatar_python through pcm_frame.
  3. spatius_avatar_python starts a Spatius server session with AgoraEgressConfig.
  4. Motion Server publishes synchronized avatar audio and motion data into the Agora channel.
  5. Your client joins the same channel and renders the avatar with AgoraProvider.
The extension also listens for:
TEN inputPurpose
audio_frame_in: pcm_frameAgent speech audio sent to Spatius.
data_in: tts_audio_endEnd-of-speech signal. The extension sends EOF to Spatius.
cmd_in: flushInterruption signal. The extension interrupts the current avatar speech.

​
Configure

{
  "params": {
    "spatius_api_key": "${env:SPATIUS_API_KEY|}",
    "spatius_app_id": "${env:SPATIUS_APP_ID|}",
    "spatius_avatar_id": "your-spatius-avatar-id",
    "agora_appid": "${env:AGORA_APP_ID|}",
    "agora_appcert": "${env:AGORA_APP_CERTIFICATE|}",
    "agora_channel": "your-agora-channel",
    "agora_uid": "2001",
    "region": "us-west",
    "sample_rate": 24000,
    "session_expire_minutes": 30
  }
}

​
Required fields

FieldRequiredDescription
params.spatius_api_keyYesYour Spatius API key. Keep it server-side.
params.spatius_app_idYesYour Spatius app ID.
params.spatius_avatar_idYesAvatar to use.
params.agora_appidYesAgora App ID.
params.agora_channelYesAgora channel where Motion Server publishes avatar output.
params.agora_uidYesNumeric Agora UID used by the avatar publisher. Must parse as an integer.
params.agora_tokenConditionalAgora RTC token for the avatar publisher UID. Required unless params.agora_appcert is provided.
params.agora_appcertConditionalAgora App Certificate. If params.agora_token is empty, the extension generates an RTC token from this value.

​
Optional fields

FieldDefaultDescription
params.regionSDK defaultSpatius region. See Regions.
params.sample_rate24000Audio sample rate expected by the extension. Audio frames with other sample rates are rejected by the base extension.
params.session_expire_minutes30Lifetime for the Spatius server session and generated Agora token privilege window.
dumpfalseWrite inbound audio to disk for debugging.
dump_pathEmptyDirectory for audio dumps when dump is enabled.
channelEmptyAlias used by the extension to populate params.agora_channel when present.
Use distinct Agora UIDs for the avatar publisher and every client participant. Configure params.agora_uid for the avatar publisher, then issue separate client tokens for browser users.

​
Token behavior

spatius_avatar_python accepts either a prebuilt Agora RTC token or an App Certificate:
  • If params.agora_token is set, the extension uses it directly.
  • If params.agora_token is empty and params.agora_appcert is set, the extension generates a token for params.agora_uid, params.agora_channel, and params.session_expire_minutes.
For production systems, prefer issuing short-lived Agora tokens from your own backend and passing the avatar publisher token into the TEN graph. Use App Certificate generation inside the extension only when that matches your deployment model and secret-handling policy.

​
Graph wiring notes

Place spatius_avatar_python after the stage that produces final avatar speech audio. It expects PCM audio frames at the configured sample rate and sends those bytes to Spatius without resampling. Use the same Agora channel on both sides:
ComponentChannel field
TEN extensionparams.agora_channel
Clientplayer.connect({ channel }) or the platform equivalent
The extension uses new_avatar_session() from the Spatius Python SDK and configures: 
AgoraEgressConfig(
    channel_name=config.agora_channel,
    token=agora_token,
    uid=int(config.agora_uid),
    publisher_id=config.agora_uid,
)
When Agora egress is enabled, Motion Server publishes avatar output into the Agora channel. The client should not call yieldAudioData() or yieldFramesData() manually; AgoraProvider owns the channel-to-renderer data flow.

​
Next steps

Overview

Review the end-to-end Agora Convo AI architecture.

Convo AI Agent

Configure Spatius in the managed Convo AI start-agent request.

Client

Join the Agora channel and render avatar output with AgoraProvider.