Merge pull request #46 from seymourtang/feat/2.8-2.9

feat:add engine 2.8 & 2.9 features

Author: plutoless

docs/concepts/vendors.md

@@ -66,8 +66,10 @@ Used with `agent.with_tts()`. Each TTS vendor produces audio at a specific sampl
 | `FishAudioTTS` | Fish Audio | `key`, `reference_id`, `backend` | — |
 | `MurfTTS` | Murf | `key`, `voice_id`, `model` | — |
 | `MiniMaxTTS` | MiniMax | `model` for supported Agora-managed global models; `key`, `group_id`, `model`, `voice_id`, `url` for BYOK | — |
+| `GenericTTS` | Generic OpenAI-compatible TTS | `url`, `headers`, `model`, `voice` | Configurable |
 | `DeepgramTTS` | Deepgram | `api_key`, `model` | Configurable |
 | `SarvamTTS` | Sarvam | `api_key` | — |
+| `XaiTTS` | xAI | `api_key`, `language` | Configurable |
 
 ### CN TTS Vendors
 
@@ -82,6 +84,7 @@ Used with `agent.with_tts()` when routing to `Area.CN`. Use `MiniMaxCNTTS` and `
 | `CosyVoiceTTS` | CosyVoice | `api_key`, `model`, `voice` | — |
 | `BytedanceDuplexTTS` | ByteDance Duplex | `app_id`, `token`, `resource_id`, `speaker` | — |
 | `StepFunTTS` | StepFun | `api_key`, `model`, `voice_id` | — |
+| `GenericTTS` | Generic OpenAI-compatible TTS | `url`, `headers`, `model`, `voice` | Configurable |
 
 <!-- snippet: executable -->
 ```python
@@ -113,6 +116,7 @@ Use `turn_detection.language` for Agora interaction language; it defaults to `en
 | `AssemblyAISTT` | AssemblyAI | `api_key`, `language` |
 | `AresSTT` | Ares | — (all optional) |
 | `SarvamSTT` | Sarvam | `api_key`, `language` |
+| `XaiSTT` | xAI | `api_key` |
 
 ### CN STT Vendors
 
@@ -164,6 +168,7 @@ Used with `agent.with_avatar()` in the cascading ASR + LLM + TTS pipeline. Some
 | `AnamAvatar` | Anam | `api_key` | None |
 | `GenericAvatar` | Generic Avatar | `api_key`, `api_base_url`, `avatar_id`, `agora_uid` | None |
 | `SenseTimeAvatar` | SenseTime (CN) | `agora_uid`, `app_key`, `sceneList` | None |
+| `SpatiusAvatar` | Spatius (CN) | `spatius_api_key`, `spatius_app_id`, `spatius_avatar_id`, `agora_uid` | Optional avatar-declared sample rate |
 
 <!-- snippet: executable -->
 ```python

docs/guides/avatars.md

@@ -18,12 +18,13 @@ Avatars are currently supported only with the cascading ASR + LLM + TTS pipeline
 | Anam | `AnamAvatar` | None |
 | Generic | `GenericAvatar` | None |
 | SenseTime (CN) | `SenseTimeAvatar` | None |
+| Spatius (CN) | `SpatiusAvatar` | Optional avatar-declared sample rate |
 
 ## Token Model
 
 The agent and avatar join the same RTC channel with separate UIDs. The agent token is scoped to `agent_uid`; `avatar.params.agora_token` is scoped to the avatar `agora_uid`.
 
-When using `AgentSession.start()`, `agora_token` is optional for LiveAvatar, HeyGen, Generic, and SenseTime avatars. If omitted, AgentKit generates it with the same ConvoAI token path as the agent, using the avatar UID. You can still pass `agora_token` explicitly.
+When using `AgentSession.start()`, `agora_token` is optional for LiveAvatar, HeyGen, Generic, SenseTime, and Spatius avatars. If omitted, AgentKit generates it with the same ConvoAI token path as the agent, using the avatar UID. You can still pass `agora_token` explicitly.
 
 ## Sample Rate Constraint
 
@@ -126,6 +127,39 @@ agent = (
 )
 ```
 
+## Spatius Avatar (CN)
+
+`SpatiusAvatar` is available for `Area.CN` sessions. Provide `spatius_api_key`, `spatius_app_id`, `spatius_avatar_id`, and `agora_uid` when constructing the avatar. `agora_token` is optional and is generated at session start when omitted, like SenseTime and Generic avatars.
+
+```python
+from agora_agent import Agora, Area, CNAgent, GenericTTS, SpatiusAvatar, TencentSTT
+
+client = Agora(
+    area=Area.CN,
+    app_id="your-app-id",
+    app_certificate="your-app-certificate",
+)
+
+agent = (
+    CNAgent(client=client)
+    .with_stt(TencentSTT(key="...", app_id="...", secret="...", engine_model_type="16k_zh", voice_id="..."))
+    .with_tts(GenericTTS(
+        url="https://tts.example.com/v1/audio",
+        headers={"Authorization": "Bearer token"},
+        model="tts-model",
+        voice="voice-1",
+    ))
+    .with_avatar(SpatiusAvatar(
+        spatius_api_key="your-spatius-api-key",
+        spatius_app_id="your-spatius-app-id",
+        spatius_avatar_id="your-spatius-avatar-id",
+        agora_uid="2",
+        region="cn-beijing",
+        sample_rate=16000,
+    ))
+)
+```
+
 ## Akool Avatar (16 kHz)
 
 Akool requires a TTS vendor configured at 16000 Hz:
@@ -246,3 +280,18 @@ If you call `with_avatar()` before `with_tts()`, the sample rate check is deferr
 | `appId` | `str` | No | SenseTime application ID |
 | `enable` | `bool` | No | Whether to enable the avatar |
 | `additional_params` | `Dict[str, Any]` | No | Additional SenseTime avatar parameters |
+
+## Spatius Options
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `spatius_api_key` | `str` | Yes | Spatius API key |
+| `spatius_app_id` | `str` | Yes | Spatius application ID |
+| `spatius_avatar_id` | `str` | Yes | Spatius avatar ID |
+| `agora_uid` | `str` | Yes | Avatar publisher RTC UID |
+| `agora_token` | `str` | No | Avatar publisher RTC token; generated at session start when omitted |
+| `region` | `str` | No | Spatius service region, for example `cn-beijing` |
+| `sample_rate` | `int` | No | Optional avatar-declared sample rate. When set, TTS sample rate should match it. |
+| `session_expire_minutes` | `int` | No | Spatius session validity duration in minutes |
+| `enable` | `bool` | No | Whether to enable the avatar |
+| `additional_params` | `Dict[str, Any]` | No | Additional Spatius avatar parameters |

docs/guides/regional-routing.md

@@ -39,8 +39,8 @@ Bind `client` into `Agent(client=client, ...)` and construct vendors directly wi
 
 | Client area | STT classes | LLM classes | TTS classes | Avatar classes |
 |---|---|---|---|---|
-| `Area.US`, `Area.EU`, `Area.AP` | `DeepgramSTT`, `SpeechmaticsSTT`, `MicrosoftSTT`, `OpenAISTT`, `GoogleSTT`, `AmazonSTT`, `AssemblyAISTT`, `AresSTT`, `SarvamSTT` | `OpenAI`, `AzureOpenAI`, `Anthropic`, `Gemini`, `Groq`, `VertexAILLM`, `AmazonBedrock`, `Dify`, `CustomLLM` | `ElevenLabsTTS`, `MicrosoftTTS`, `OpenAITTS`, `CartesiaTTS`, `GoogleTTS`, `AmazonTTS`, `DeepgramTTS`, `HumeAITTS`, `RimeTTS`, `FishAudioTTS`, `MiniMaxTTS`, `MurfTTS`, `SarvamTTS` | `LiveAvatarAvatar`, `HeyGenAvatar`, `AkoolAvatar`, `AnamAvatar`, `GenericAvatar` |
-| `Area.CN` | `FengmingSTT`, `TencentSTT`, `MicrosoftCNSTT`, `XfyunSTT`, `XfyunBigModelSTT`, `XfyunDialectSTT` | `AliyunLLM`, `BytedanceLLM`, `DeepSeekLLM`, `TencentLLM` | `MiniMaxCNTTS`, `TencentTTS`, `BytedanceTTS`, `MicrosoftCNTTS`, `CosyVoiceTTS`, `BytedanceDuplexTTS`, `StepFunTTS` | `SenseTimeAvatar` |
+| `Area.US`, `Area.EU`, `Area.AP` | `DeepgramSTT`, `SpeechmaticsSTT`, `MicrosoftSTT`, `OpenAISTT`, `GoogleSTT`, `AmazonSTT`, `AssemblyAISTT`, `AresSTT`, `SarvamSTT`, `XaiSTT` | `OpenAI`, `AzureOpenAI`, `Anthropic`, `Gemini`, `Groq`, `VertexAILLM`, `AmazonBedrock`, `Dify`, `CustomLLM` | `ElevenLabsTTS`, `MicrosoftTTS`, `OpenAITTS`, `CartesiaTTS`, `GoogleTTS`, `AmazonTTS`, `DeepgramTTS`, `HumeAITTS`, `RimeTTS`, `FishAudioTTS`, `MiniMaxTTS`, `MurfTTS`, `SarvamTTS`, `GenericTTS`, `XaiTTS` | `LiveAvatarAvatar`, `HeyGenAvatar`, `AkoolAvatar`, `AnamAvatar`, `GenericAvatar` |
+| `Area.CN` | `FengmingSTT`, `TencentSTT`, `MicrosoftCNSTT`, `XfyunSTT`, `XfyunBigModelSTT`, `XfyunDialectSTT` | `AliyunLLM`, `BytedanceLLM`, `DeepSeekLLM`, `TencentLLM` | `MiniMaxCNTTS`, `TencentTTS`, `BytedanceTTS`, `MicrosoftCNTTS`, `CosyVoiceTTS`, `BytedanceDuplexTTS`, `StepFunTTS`, `GenericTTS` | `SenseTimeAvatar`, `SpatiusAvatar` |
 
 Global client example:
 

docs/index.md

@@ -47,7 +47,7 @@ The Agora Conversational AI Python SDK lets you build voice-powered AI agents on
 | [Vendors](./concepts/vendors.md) | Browse all LLM, TTS, STT, MLLM, and Avatar providers |
 | [Cascading Flow](./guides/cascading-flow.md) | Build an ASR -> LLM -> TTS pipeline |
 | [MLLM Flow](./guides/mllm-flow.md) | Use OpenAI Realtime, Gemini Live, Vertex AI, or xAI Grok for end-to-end audio |
-| [Avatars](./guides/avatars.md) | Add a digital avatar with LiveAvatar, Akool, Anam, or Generic Avatar |
+| [Avatars](./guides/avatars.md) | Add a digital avatar with LiveAvatar, Akool, Anam, Generic Avatar, SenseTime, or Spatius |
 | [Regional Routing](./guides/regional-routing.md) | Route requests to the nearest region |
 | [Error Handling](./guides/error-handling.md) | Handle API errors with ApiError |
 | [Pagination](./guides/pagination.md) | Iterate over paginated list endpoints |

docs/reference/vendors.md

@@ -19,8 +19,8 @@ Construct vendors directly from `agora_agent`, then bind a client with `Agent(cl
 
 | Area | STT classes | LLM classes | TTS classes | Avatar classes |
 |---|---|---|---|---|
-| `Area.US`, `Area.EU`, `Area.AP` | `DeepgramSTT`, `SpeechmaticsSTT`, `MicrosoftSTT`, `OpenAISTT`, `GoogleSTT`, `AmazonSTT`, `AssemblyAISTT`, `AresSTT`, `SarvamSTT` | `OpenAI`, `AzureOpenAI`, `Anthropic`, `Gemini`, `Groq`, `VertexAILLM`, `AmazonBedrock`, `Dify`, `CustomLLM` | `ElevenLabsTTS`, `MicrosoftTTS`, `OpenAITTS`, `CartesiaTTS`, `GoogleTTS`, `AmazonTTS`, `DeepgramTTS`, `HumeAITTS`, `RimeTTS`, `FishAudioTTS`, `MiniMaxTTS`, `MurfTTS`, `SarvamTTS` | `LiveAvatarAvatar`, `HeyGenAvatar`, `AkoolAvatar`, `AnamAvatar`, `GenericAvatar` |
-| `Area.CN` | `FengmingSTT`, `TencentSTT`, `MicrosoftCNSTT`, `XfyunSTT`, `XfyunBigModelSTT`, `XfyunDialectSTT` | `AliyunLLM`, `BytedanceLLM`, `DeepSeekLLM`, `TencentLLM` | `MiniMaxCNTTS`, `TencentTTS`, `BytedanceTTS`, `MicrosoftCNTTS`, `CosyVoiceTTS`, `BytedanceDuplexTTS`, `StepFunTTS` | `SenseTimeAvatar` |
+| `Area.US`, `Area.EU`, `Area.AP` | `DeepgramSTT`, `SpeechmaticsSTT`, `MicrosoftSTT`, `OpenAISTT`, `GoogleSTT`, `AmazonSTT`, `AssemblyAISTT`, `AresSTT`, `SarvamSTT`, `XaiSTT` | `OpenAI`, `AzureOpenAI`, `Anthropic`, `Gemini`, `Groq`, `VertexAILLM`, `AmazonBedrock`, `Dify`, `CustomLLM` | `ElevenLabsTTS`, `MicrosoftTTS`, `OpenAITTS`, `CartesiaTTS`, `GoogleTTS`, `AmazonTTS`, `DeepgramTTS`, `HumeAITTS`, `RimeTTS`, `FishAudioTTS`, `MiniMaxTTS`, `MurfTTS`, `SarvamTTS`, `GenericTTS`, `XaiTTS` | `LiveAvatarAvatar`, `HeyGenAvatar`, `AkoolAvatar`, `AnamAvatar`, `GenericAvatar` |
+| `Area.CN` | `FengmingSTT`, `TencentSTT`, `MicrosoftCNSTT`, `XfyunSTT`, `XfyunBigModelSTT`, `XfyunDialectSTT` | `AliyunLLM`, `BytedanceLLM`, `DeepSeekLLM`, `TencentLLM` | `MiniMaxCNTTS`, `TencentTTS`, `BytedanceTTS`, `MicrosoftCNTTS`, `CosyVoiceTTS`, `BytedanceDuplexTTS`, `StepFunTTS`, `GenericTTS` | `SenseTimeAvatar`, `SpatiusAvatar` |
 
 Global example:
 
@@ -85,6 +85,7 @@ tts = MiniMaxCNTTS(
 | `max_tokens` | `int` | No | `None` | Maximum tokens to generate |
 | `system_messages` | `List[Dict]` | No | `None` | System messages |
 | `greeting_message` | `str` | No | `None` | Greeting message |
+| `greeting_audio_url` | `str` | No | `None` | Publicly accessible greeting audio URL |
 | `failure_message` | `str` | No | `None` | Failure message |
 | `input_modalities` | `List[str]` | No | `None` | Input modalities |
 | `output_modalities` | `List[str]` | No | `None` | Output modalities |
@@ -93,6 +94,8 @@ tts = MiniMaxCNTTS(
 | `greeting_configs` | `Dict[str, Any]` | No | `None` | Greeting playback configuration |
 | `template_variables` | `Dict[str, str]` | No | `None` | Template variables for messages |
 
+`greeting_configs` may also include `audio_download_timeout_ms`, `audio_pcm_sample_rate`, and `uninterruptible_asr_policy`.
+
 <!-- snippet: fragment -->
 ```python
 from agora_agent import OpenAI
@@ -378,6 +381,33 @@ The SDK also includes named helpers for the remaining Agora-supported LLM provid
 | `sample_rate` | `int` | No | `None` | Audio sample rate |
 | `skip_patterns` | `List[int]` | No | `None` | Skip patterns |
 
+### `GenericTTS`
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `url` | `str` | Yes | — | Callback address of the generic TTS service |
+| `headers` | `Dict[str, str]` | Yes | — | Custom headers to include in requests to the generic TTS service |
+| `model` | `str` | Yes | — | TTS model name |
+| `voice` | `str` | Yes | — | Voice name |
+| `api_key` | `str` | No | `None` | API key for the generic TTS service |
+| `speed` | `float` | No | `None` | Speech rate |
+| `sample_rate` | `int` | No | `None` | Output audio sample rate in Hz |
+| `response_format` | `str` | No | `None` | Output audio format; use `pcm` |
+| `instruction` | `str` | No | `None` | Additional voice style control instruction |
+| `additional_params` | `Dict[str, Any]` | No | `None` | Additional generic TTS parameters |
+| `skip_patterns` | `List[int]` | No | `None` | Skip patterns |
+
+### `XaiTTS`
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `api_key` | `str` | Yes | — | xAI API key |
+| `language` | `str` | Yes | — | BCP-47 language code for speech synthesis |
+| `voice_id` | `str` | No | `None` | xAI voice identifier |
+| `sample_rate` | `int` | No | `None` | Audio sample rate in Hz |
+| `additional_params` | `Dict[str, Any]` | No | `None` | Additional xAI TTS parameters |
+| `skip_patterns` | `List[int]` | No | `None` | Skip patterns |
+
 ---
 
 ## STT Vendors
@@ -471,6 +501,16 @@ For `nova-2` and `nova-3`, omit `api_key` to use Agora-managed credentials. For
 | `language` | `str` | Yes | — | Language code (e.g., `en`, `hi`) |
 | `additional_params` | `Dict[str, Any]` | No | `None` | Additional parameters |
 
+### `XaiSTT`
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `api_key` | `str` | Yes | — | xAI API key |
+| `base_url` | `str` | No | `None` | WebSocket endpoint URL for the xAI streaming STT API |
+| `sample_rate` | `int` | No | `None` | Audio sample rate in Hz |
+| `language` | `str` | No | `None` | Language code for speech recognition |
+| `additional_params` | `Dict[str, Any]` | No | `None` | Additional xAI STT parameters |
+
 ---
 
 ## CN Vendors
@@ -658,6 +698,21 @@ No constructor parameters. Use `FengmingSTT()`.
 | `enable` | `bool` | No | `None` | Whether to enable the avatar |
 | `additional_params` | `Dict[str, Any]` | No | `None` | Additional SenseTime avatar parameters |
 
+#### `SpatiusAvatar`
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `spatius_api_key` | `str` | Yes | — | Spatius API key |
+| `spatius_app_id` | `str` | Yes | — | Spatius application ID |
+| `spatius_avatar_id` | `str` | Yes | — | Spatius avatar ID |
+| `agora_uid` | `str` | Yes | — | Agora UID used by the avatar service |
+| `agora_token` | `str` | No | `None` | RTC token for avatar publisher; generated by AgentSession when omitted |
+| `region` | `str` | No | `None` | Spatius service region, for example `cn-beijing` |
+| `sample_rate` | `int` | No | `None` | Optional avatar-declared sample rate; TTS sample rate should match when set |
+| `session_expire_minutes` | `int` | No | `None` | Spatius session validity duration in minutes |
+| `enable` | `bool` | No | `None` | Whether to enable the avatar |
+| `additional_params` | `Dict[str, Any]` | No | `None` | Additional Spatius avatar parameters |
+
 ## MLLM Vendors
 
 ### `OpenAIRealtime`

src/agora_agent/__init__.py

@@ -21,6 +21,7 @@
         CNAgent,
         GlobalAgent,
         GenericAvatar,
+        SpatiusAvatar,
         RegionalAgent,
         XaiGrok,
         generate_rtc_token,
@@ -39,6 +40,7 @@
     "AsyncAgora": ".pool_client",
     "AsyncAgentClient": ".pool_client",
     "GenericAvatar": ".agentkit",
+    "SpatiusAvatar": ".agentkit",
     "XaiGrok": ".agentkit",
     "GenerateTokenOptions": ".agentkit",
     "__version__": ".version",
@@ -62,6 +64,7 @@
     "AsyncAgora",
     "AsyncAgentClient",
     "GenericAvatar",
+    "SpatiusAvatar",
     "XaiGrok",
     "GenerateTokenOptions",
     "Pool",

src/agora_agent/agentkit/__init__.py

@@ -92,6 +92,7 @@
     is_live_avatar_avatar,
     is_rtc_avatar,
     is_sensetime_avatar,
+    is_spatius_avatar,
     validate_avatar_config,
     validate_tts_sample_rate,
 )
@@ -189,15 +190,19 @@
     OpenAISampleRate,
     OpenAISTT,
     OpenAITTS,
+    GenericTTS,
     RimeTTS,
     SampleRate,
     SarvamSTT,
     SarvamTTS,
     SpeechmaticsSTT,
+    XaiSTT,
+    XaiTTS,
     VertexAI,
     VertexAILLM,
     XaiGrok,
     LiveAvatarAvatar,
+    SpatiusAvatar,
 )
 from .vendors.cn import (
     AliyunLLM,
@@ -382,6 +387,7 @@
     "MicrosoftTTS",
     "MicrosoftCNTTS",
     "OpenAITTS",
+    "GenericTTS",
     "CartesiaTTS",
     "DeepgramTTS",
     "GoogleTTS",
@@ -398,6 +404,7 @@
     "StepFunTTS",
     "MurfTTS",
     "SarvamTTS",
+    "XaiTTS",
     "SpeechmaticsSTT",
     "DeepgramSTT",
     "MicrosoftSTT",
@@ -408,6 +415,7 @@
     "AssemblyAISTT",
     "AresSTT",
     "SarvamSTT",
+    "XaiSTT",
     "TencentSTT",
     "FengmingSTT",
     "XfyunBigModelSTT",
@@ -422,13 +430,15 @@
     "AkoolAvatar",
     "AnamAvatar",
     "GenericAvatar",
+    "SpatiusAvatar",
     "SenseTimeAvatar",
     "is_heygen_avatar",
     "is_live_avatar_avatar",
     "is_akool_avatar",
     "is_anam_avatar",
     "is_generic_avatar",
     "is_sensetime_avatar",
+    "is_spatius_avatar",
     "validate_avatar_config",
     "validate_tts_sample_rate",
 ]

src/agora_agent/agentkit/agent_session.py

@@ -31,6 +31,7 @@
     is_live_avatar_avatar,
     is_rtc_avatar,
     is_sensetime_avatar,
+    is_spatius_avatar,
     validate_avatar_config,
     validate_tts_sample_rate,
 )
@@ -221,6 +222,7 @@ def _validate_avatar_config(self) -> None:
             or is_anam_avatar(avatar)
             or is_generic_avatar(avatar)
             or is_sensetime_avatar(avatar)
+            or is_spatius_avatar(avatar)
         ):
             validate_avatar_config(avatar)
 
@@ -249,6 +251,13 @@ def _validate_avatar_config(self) -> None:
                 "Warning: Akool avatar detected but TTS sample_rate is not explicitly set. "
                 "Akool requires 16,000 Hz. Please ensure your TTS provider is configured for 16kHz."
             )
+        elif is_spatius_avatar(avatar):
+            avatar_sample_rate = avatar.get("params", {}).get("sample_rate")
+            if isinstance(avatar_sample_rate, int):
+                self._warn(
+                    "Warning: Spatius avatar declares a sample_rate but TTS sample_rate is not explicitly set. "
+                    "Please ensure your TTS provider matches the avatar sample_rate."
+                )
 
     def _enrich_avatar_for_session(
         self, properties: typing.Dict[str, typing.Any]