Align managed vendor validation with generated core shapes

Author: digitallysavvy

docs/concepts/vendors.md

@@ -54,7 +54,7 @@ Used with `agent.with_tts()`. Each TTS vendor produces audio at a specific sampl
 | `RimeTTS` | Rime | `key`, `speaker`, `model_id` | — |
 | `FishAudioTTS` | Fish Audio | `key`, `reference_id`, `backend` | — |
 | `GroqTTS` | Groq | `key` | — |
-| `MiniMaxTTS` | MiniMax | `key` | — |
+| `MiniMaxTTS` | MiniMax | `model` for supported Agora-managed models; `key`, `group_id`, `model`, `voice_id`, `url` for BYOK | — |
 | `DeepgramTTS` | Deepgram | `api_key`, `model` | Configurable |
 | `SarvamTTS` | Sarvam | `api_key` | — |
 
@@ -80,7 +80,7 @@ Use `agent.with_interaction_language()` for Agora `asr.language`; it defaults to
 | Class | Provider | Required Parameters |
 |---|---|---|
 | `SpeechmaticsSTT` | Speechmatics | `api_key`, `language` |
-| `DeepgramSTT` | Deepgram | — (all optional) |
+| `DeepgramSTT` | Deepgram | `model` for Agora-managed `nova-2`/`nova-3`; `api_key` for BYOK |
 | `MicrosoftSTT` | Microsoft Azure | `key`, `region`, `language` |
 | `OpenAISTT` | OpenAI | `api_key` |
 | `GoogleSTT` | Google Cloud | `project_id`, `location`, `adc_credentials_string`, `language` |

docs/reference/vendors.md

@@ -190,11 +190,10 @@ The SDK also includes named helpers for the remaining Agora-supported LLM provid
 | `voice` | `str` | Yes | — | Voice: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer` |
 | `model` | `str` | BYOK only | `None` | Model: `tts-1` or `tts-1-hd` |
 | `base_url` | `str` | BYOK only | `None` | OpenAI TTS endpoint URL |
-| `response_format` | `str` | No | `None` | Audio format (e.g., `pcm`) |
 | `speed` | `float` | No | `None` | Speech speed multiplier |
 | `skip_patterns` | `List[int]` | No | `None` | Skip patterns |
 
-`api_key`, `model`, and `base_url` are required together for BYOK. Without `api_key`, AgentKit uses the Agora-managed `tts-1` path. Fixed sample rate: 24000 Hz.
+`api_key`, `model`, and `base_url` are required together for BYOK. Without `api_key`, `model` must be omitted or set to the Agora-managed `tts-1` path. Fixed sample rate: 24000 Hz.
 
 ### `CartesiaTTS`
 
@@ -323,14 +322,16 @@ Use `agent.with_interaction_language()` for Agora `asr.language`; it defaults to
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `api_key` | `str` | No | `None` | Deepgram API key |
+| `api_key` | `str` | BYOK only | `None` | Deepgram API key. Optional only for Agora-managed `nova-2` and `nova-3`. |
 | `model` | `str` | No | `None` | Model (e.g., `nova-2`) |
 | `language` | `str` | No | `None` | Language code (e.g., `en-US`) |
 | `interaction_language` | `str` | No | `None` | Agora `asr.language` override |
 | `smart_format` | `bool` | No | `None` | Enable smart formatting |
 | `punctuation` | `bool` | No | `None` | Enable punctuation |
 | `additional_params` | `Dict[str, Any]` | No | `None` | Additional parameters |
 
+For `nova-2` and `nova-3`, omit `api_key` to use Agora-managed credentials. For all other Deepgram models, AgentKit requires `api_key`.
+
 ### `MicrosoftSTT`
 
 | Parameter | Type | Required | Default | Description |

src/agora_agent/agentkit/vendors/stt.py

@@ -1,6 +1,6 @@
 from typing import Any, Dict, Optional
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 from typing_extensions import Literal
 
 from .base import BaseSTT
@@ -41,6 +41,7 @@
 ]
 
 _INTERACTION_LANGUAGES = set(InteractionLanguage.__args__)
+_DEEPGRAM_MANAGED_MODELS = {"nova-2", "nova-3"}
 
 
 def _interaction_language(language: Optional[str], interaction_language: Optional[InteractionLanguage]) -> Optional[InteractionLanguage]:
@@ -97,6 +98,12 @@ class DeepgramSTTOptions(BaseModel):
     punctuation: Optional[bool] = Field(default=None, description="Enable punctuation")
     additional_params: Optional[Dict[str, Any]] = Field(default=None)
 
+    @model_validator(mode="after")
+    def _validate_managed_model(self) -> "DeepgramSTTOptions":
+        if self.api_key is None and (self.model is None or self.model.strip().lower() not in _DEEPGRAM_MANAGED_MODELS):
+            raise ValueError("DeepgramSTT requires api_key unless using a supported Agora-managed model")
+        return self
+
 class DeepgramSTT(BaseSTT):
     def __init__(self, **kwargs: Any):
         self.options = DeepgramSTTOptions(**kwargs)

src/agora_agent/agentkit/vendors/tts.py

@@ -3,6 +3,7 @@
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from .base import BaseTTS, CartesiaSampleRate, ElevenLabsSampleRate, GoogleTTSSampleRate, MicrosoftSampleRate
+from ..presets import MiniMaxPresetModels, OpenAITtsPresetModels
 
 class ElevenLabsTTSOptions(BaseModel):
     model_config = ConfigDict(extra="forbid")
@@ -100,7 +101,6 @@ class OpenAITTSOptions(BaseModel):
     voice: str = Field(..., description="Voice name (alloy, echo, fable, onyx, nova, shimmer)")
     model: Optional[str] = Field(default=None, description="Model name (tts-1, tts-1-hd)")
     base_url: Optional[str] = Field(default=None, description="Endpoint URL")
-    response_format: Optional[str] = Field(default=None, description="Audio format (e.g., pcm)")
     instructions: Optional[str] = Field(default=None, description="Custom voice instructions")
     speed: Optional[float] = Field(default=None, description="Speech speed multiplier")
     skip_patterns: Optional[List[int]] = Field(default=None)
@@ -118,8 +118,11 @@ def _validate_byok_params(self) -> "OpenAITTSOptions":
             ]
             if missing:
                 raise ValueError(f"OpenAITTS requires {', '.join(missing)} when api_key is set")
-        elif self.base_url is not None:
-            raise ValueError("OpenAITTS base_url is only valid when api_key is set")
+        else:
+            if self.model is not None and self.model.strip().lower() not in OpenAITtsPresetModels:
+                raise ValueError("OpenAITTS requires api_key unless using the Agora-managed tts-1 model")
+            if self.base_url is not None:
+                raise ValueError("OpenAITTS base_url is only valid when api_key is set")
         return self
 
 class OpenAITTS(BaseTTS):
@@ -141,8 +144,6 @@ def to_config(self) -> Dict[str, Any]:
         elif self.options.model is not None:
             params["model"] = self.options.model
 
-        if self.options.response_format is not None:
-            params["response_format"] = self.options.response_format
         if self.options.instructions is not None:
             params["instructions"] = self.options.instructions
         if self.options.speed is not None:
@@ -423,6 +424,8 @@ def _validate_byok_params(self) -> "MiniMaxTTSOptions":
             ]
             if missing:
                 raise ValueError(f"MiniMaxTTS requires {', '.join(missing)} when key is set")
+        elif self.model.strip().lower() not in MiniMaxPresetModels:
+            raise ValueError("MiniMaxTTS requires key unless using a supported Agora-managed model")
         return self
 
 class MiniMaxTTS(BaseTTS):

tests/custom/test_stt_language.py

@@ -81,6 +81,14 @@ def test_default_interaction_language_is_sent_without_stt() -> None:
 
 
 def test_stt_vendor_params_match_documented_shapes() -> None:
+    assert DeepgramSTT(model="nova-3", language="en-US").to_config()["params"] == {
+        "model": "nova-3",
+        "language": "en-US",
+    }
+
+    with pytest.raises(Exception, match="api_key"):
+        DeepgramSTT(model="enhanced")
+
     assert DeepgramSTT(api_key="dg-key", language="en").to_config()["params"] == {
         "key": "dg-key",
         "language": "en",

tests/custom/test_tts_vendors.py

@@ -1,3 +1,5 @@
+import pytest
+
 from agora_agent import AmazonTTS, CartesiaTTS, ElevenLabsTTS, FishAudioTTS, GoogleTTS, HumeAITTS, MiniMaxTTS, MurfTTS, OpenAITTS, RimeTTS, SarvamTTS
 
 
@@ -97,3 +99,11 @@ def test_tts_vendor_params_match_generated_core_shapes() -> None:
     assert MurfTTS(key="murf-key").to_config()["params"] == {
         "api_key": "murf-key",
     }
+
+
+def test_tts_managed_mode_validation_matches_core_shapes() -> None:
+    with pytest.raises(Exception, match="OpenAITTS requires api_key"):
+        OpenAITTS(voice="coral", model="tts-1-hd")
+
+    with pytest.raises(Exception, match="MiniMaxTTS requires key"):
+        MiniMaxTTS(model="speech-02-turbo")