fix(agentkit): flatten Deepgram TTS passthrough params

Author: digitallysavvy

README.md

@@ -20,6 +20,7 @@ pip install agora-agents
 ## Quick Start
 
 Start with the `Agent` builder: create a client with app credentials, choose your ASR, LLM, and TTS providers, then start a session. Omit vendor API keys for supported Agora-managed models, or provide keys when you want BYOK.
+Use `with_interaction_language()` for Agora `asr.language`; provider-specific STT language values remain under `asr.params`.
 
 ```python
 import os
@@ -29,12 +30,9 @@ from agora_agent import (
     Agent,
     Agora,
     Area,
-    DataChannel,
     DeepgramSTT,
-    GenericAvatar,
     MiniMaxTTS,
     OpenAI,
-    XaiGrok,
     expires_in_hours,
 )
 
@@ -56,35 +54,7 @@ def start_conversation() -> str:
         app_certificate=app_certificate,
     )
 
-    agent = Agent(
-        name=f"conversation-{int(time.time())}",
-        turn_detection={
-            "config": {
-                "speech_threshold": 0.5,
-                "start_of_speech": {
-                    "mode": "vad",
-                    "vad_config": {
-                        "interrupt_duration_ms": 160,
-                        "prefix_padding_ms": 300,
-                    },
-                },
-                "end_of_speech": {
-                    "mode": "vad",
-                    "vad_config": {
-                        "silence_duration_ms": 480,
-                    },
-                },
-            },
-        },
-        advanced_features={
-            "enable_rtm": True,
-            "enable_tools": True,
-        },
-        parameters={
-            "data_channel": DataChannel.RTM,
-            "enable_error_message": True,
-        },
-    ).with_stt(
+    agent = Agent(name=f"conversation-{int(time.time())}").with_interaction_language("en-US").with_stt(
         DeepgramSTT(
             model="nova-3",
             language="en",
@@ -131,7 +101,7 @@ def start_conversation() -> str:
 Use the same `Agent` builder shape, but provide credentials explicitly when you want vendor-managed billing and routing instead of Agora-managed models.
 
 ```python
-agent = Agent().with_stt(
+agent = Agent().with_interaction_language("en-US").with_stt(
     DeepgramSTT(
         api_key=os.environ["DEEPGRAM_API_KEY"],
         model="nova-3",

changelog.md

@@ -52,7 +52,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Added
 
-- **`DeepgramTTS`** — New TTS vendor wrapper for Deepgram (Beta). Accepts `api_key`, `model`, `base_url`, `sample_rate`, `params`, and `skip_patterns`.
+- **`DeepgramTTS`** — New TTS vendor wrapper for Deepgram (Beta). Accepts `api_key`, `model`, `base_url`, `sample_rate`, `additional_params`, and `skip_patterns`.
 - **`Agent.with_tools(enabled=True)`** — Dedicated builder method to enable MCP tool invocation (`advanced_features.enable_tools`). Replaces the raw `with_advanced_features(AdvancedFeatures(enable_tools=True))` call.
 - **LLM vendors: `headers` field** — All four LLM vendors (`OpenAI`, `AzureOpenAI`, `Anthropic`, `Gemini`) now accept an optional `headers: Dict[str, str]` parameter. Use this to pass custom HTTP headers to the LLM provider (e.g., tenant identifiers, routing headers).
 - **`AgentSession.think()` / `AsyncAgentSession.think()`** — Send a custom instruction to a running agent through the `agent_management` API.

docs/reference/vendors.md

@@ -233,7 +233,7 @@ The SDK also includes named helpers for the remaining Agora-supported LLM provid
 | `model` | `str` | Yes | — | Deepgram TTS model (e.g., `aura-2-thalia-en`) |
 | `base_url` | `str` | No | `None` | WebSocket endpoint; defaults server-side to `wss://api.deepgram.com/v1/speak` |
 | `sample_rate` | `int` | No | `None` | Sample rate in Hz (for example, `24000`) |
-| `params` | `Dict[str, Any]` | No | `None` | Additional Deepgram TTS parameters |
+| `additional_params` | `Dict[str, Any]` | No | `None` | Additional Deepgram TTS parameters, flattened into `params` |
 | `skip_patterns` | `List[int]` | No | `None` | Skip patterns |
 
 ### `HumeAITTS`

src/agora_agent/agentkit/vendors/tts.py

@@ -268,7 +268,7 @@ class DeepgramTTSOptions(BaseModel):
     model: str = Field(..., description="Deepgram TTS model (e.g., 'aura-2-thalia-en')")
     base_url: Optional[str] = Field(default=None, description="WebSocket endpoint")
     sample_rate: Optional[int] = Field(default=None, description="Sample rate in Hz")
-    params: Optional[Dict[str, Any]] = Field(default=None, description="Additional Deepgram TTS parameters")
+    additional_params: Optional[Dict[str, Any]] = Field(default=None, description="Additional Deepgram TTS parameters")
     skip_patterns: Optional[List[int]] = Field(default=None)
 
 class DeepgramTTS(BaseTTS):
@@ -280,17 +280,16 @@ def sample_rate(self) -> Optional[int]:
         return self.options.sample_rate
 
     def to_config(self) -> Dict[str, Any]:
-        params: Dict[str, Any] = {
+        params: Dict[str, Any] = dict(self.options.additional_params or {})
+        params.update({
             "api_key": self.options.api_key,
             "model": self.options.model,
-            **(self.options.params or {}),
-        }
+        })
 
         if self.options.base_url is not None:
             params["base_url"] = self.options.base_url
         if self.options.sample_rate is not None:
             params["sample_rate"] = self.options.sample_rate
-
         result: Dict[str, Any] = {"vendor": "deepgram", "params": params}
         if self.options.skip_patterns is not None:
             result["skip_patterns"] = self.options.skip_patterns

tests/custom/test_tts_vendors.py

@@ -1,6 +1,6 @@
 import pytest
 
-from agora_agent import AmazonTTS, CartesiaTTS, ElevenLabsTTS, FishAudioTTS, GoogleTTS, HumeAITTS, MiniMaxTTS, MurfTTS, OpenAITTS, RimeTTS, SarvamTTS
+from agora_agent import AmazonTTS, CartesiaTTS, DeepgramTTS, ElevenLabsTTS, FishAudioTTS, GoogleTTS, HumeAITTS, MiniMaxTTS, MurfTTS, OpenAITTS, RimeTTS, SarvamTTS
 
 
 def test_tts_vendor_params_match_generated_core_shapes() -> None:
@@ -44,6 +44,14 @@ def test_tts_vendor_params_match_generated_core_shapes() -> None:
         "voice_id": "voice",
     }
 
+    assert DeepgramTTS(api_key="deepgram-key", model="aura-2-thalia-en", base_url="wss://api.deepgram.com/v1/speak", sample_rate=24000, additional_params={"encoding": "linear16"}).to_config()["params"] == {
+        "api_key": "deepgram-key",
+        "model": "aura-2-thalia-en",
+        "base_url": "wss://api.deepgram.com/v1/speak",
+        "sample_rate": 24000,
+        "encoding": "linear16",
+    }
+
     assert OpenAITTS(api_key="openai-key", voice="coral", model="gpt-4o-mini-tts", base_url="https://api.openai.com/v1").to_config()["params"] == {
         "voice": "coral",
         "api_key": "openai-key",