fix(agentkit): source ASR language from turn detection

  Optional longer body:

  Keep provider STT language settings inside asr.params, populate REST asr.language from
  turn_detection.language, and treat Ares as provider-only.

Author: digitallysavvy

README.md

@@ -20,7 +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.
-Set Agora interaction language with `turn_detection.language`; provider-specific STT language values remain under `asr.params`.
+Set Agora interaction language with `turn_detection.language`; provider-specific STT language values remain under `asr.params`. Ares uses only the REST `asr.language` value sourced from `turn_detection.language`.
 
 ```python
 import os

changelog.md

@@ -8,7 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Added
 
-- **Turn detection language** — AgentKit now manages Agora interaction language through `turn_detection.language`, validates it against the supported BCP-47 language list, and sends the default `en` when no language is provided.
+- **Turn detection language** — AgentKit now manages Agora interaction language through `turn_detection.language`, validates it against the supported BCP-47 language list, and sends the default `en-US` when no language is provided.
 - **Provider parameter parity** — ASR, LLM, MLLM, TTS, and avatar wrappers expose typed provider parameters plus passthrough fields where the generated core supports additional properties.
 
 ### Changed
@@ -21,7 +21,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 ### Fixed
 
 - **Managed-provider validation** — AgentKit validation now distinguishes preset-backed providers from BYOK providers so required provider fields are only required when credentials are caller-supplied.
-- **Language placement** — Provider-specific STT language values remain under `asr.params`, while Agora interaction language is emitted separately as `turn_detection.language`.
+- **Language placement** — Provider-specific STT language values remain under `asr.params`; the REST `asr.language` field is populated from `turn_detection.language`.
 
 ## [v2.0.0] — 2026-05-21
 
@@ -114,7 +114,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Fixed
 
-- **`AresSTT`** — Removed redundant `language` key from the `params` dict. Language is now emitted only at the top level. `params` is only included when `additional_params` is provided.
+- **`AresSTT`** — Removed redundant `language` key from the `params` dict. Ares only selects the provider; AgentKit populates REST `asr.language` from `turn_detection.language`. `params` is only included when `additional_params` is provided.
 - **`OpenAIRealtime` / `VertexAI` (MLLM)** — Agent-level `greeting` and `failure_message` defaults are now correctly applied when missing in MLLM mode. Previously these values were silently dropped.
 - **`VertexAI` (MLLM)** — `messages` is emitted at the MLLM top level, matching the generated core SDK contract.
 

docs/concepts/vendors.md

@@ -75,7 +75,7 @@ tts = ElevenLabsTTS(
 
 Used with `agent.with_stt()`.
 
-Use `turn_detection.language` for Agora interaction language; it defaults to `en`. STT vendor `language` options are serialized under `asr.params` using each provider's own format.
+Use `turn_detection.language` for Agora interaction language; it defaults to `en-US`. STT vendor `language` options are serialized under `asr.params` using each provider's own format. Ares does not take a provider language option; AgentKit uses `turn_detection.language` for REST `asr.language`.
 
 | Class | Provider | Required Parameters |
 |---|---|---|

docs/reference/vendors.md

@@ -318,7 +318,7 @@ The SDK also includes named helpers for the remaining Agora-supported LLM provid
 
 ## STT Vendors
 
-Use `turn_detection.language` for Agora interaction language; it defaults to `en`. Provider-specific language values remain under `asr.params` and may use a different format.
+Use `turn_detection.language` for Agora interaction language; it defaults to `en-US`. Provider-specific language values remain under `asr.params` and may use a different format. AgentKit populates REST `asr.language` from `turn_detection.language`.
 
 ### `SpeechmaticsSTT`
 
@@ -396,7 +396,6 @@ For `nova-2` and `nova-3`, omit `api_key` to use Agora-managed credentials. For
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `language` | `str` | No | `None` | Language code |
 | `additional_params` | `Dict[str, Any]` | No | `None` | Additional parameters |
 
 ### `SarvamSTT`

src/agora_agent/agentkit/agent.py

@@ -247,7 +247,7 @@ class SessionOptions(typing_extensions.TypedDict, total=False):
     "vi-VN",
 ]
 
-DEFAULT_TURN_DETECTION_LANGUAGE: TurnDetectionLanguage = "en"
+DEFAULT_TURN_DETECTION_LANGUAGE: TurnDetectionLanguage = "en-US"
 TURN_DETECTION_LANGUAGE_VALUES: typing.Tuple[TurnDetectionLanguage, ...] = (
     "ar-EG",
     "ar-JO",
@@ -921,9 +921,10 @@ def to_properties(
         allow_missing_llm = "llm" in allow_missing_categories
         allow_missing_tts = "tts" in allow_missing_categories
 
+        turn_detection_config = self._resolve_turn_detection_config()
         if not skip_asr_validation and (self._stt is not None or not allow_missing_asr):
-            base_kwargs["asr"] = self._resolve_asr_config()
-        base_kwargs["turn_detection"] = self._resolve_turn_detection_config()
+            base_kwargs["asr"] = self._resolve_asr_config(turn_detection_config)
+        base_kwargs["turn_detection"] = turn_detection_config
 
         if skip_vendor_validation:
             return StartAgentsRequestProperties(**base_kwargs)
@@ -957,11 +958,11 @@ def _resolve_llm_config(self) -> typing.Dict[str, typing.Any]:
             llm_config["max_history"] = self._max_history
         return llm_config
 
-    def _resolve_asr_config(self) -> typing.Dict[str, typing.Any]:
+    def _resolve_asr_config(self, turn_detection_config: TurnDetectionConfig) -> typing.Dict[str, typing.Any]:
         asr_config = dict(self._stt or {})
-        asr_config.pop("language", None)
         if not asr_config:
             asr_config["vendor"] = "ares"
+        asr_config["language"] = self._field_value(turn_detection_config, "language")
         return asr_config
 
     def _resolve_turn_detection_config(self) -> TurnDetectionConfig:

src/agora_agent/agentkit/vendors/stt.py

@@ -1,89 +1,12 @@
-from typing import Any, Dict, Optional, Tuple
+from typing import Any, Dict, Optional
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
-from typing_extensions import Literal
 
 from .base import BaseSTT
 
-TurnDetectionLanguage = Literal[
-    "ar-EG",
-    "ar-JO",
-    "ar-SA",
-    "ar-AE",
-    "bn-IN",
-    "zh-CN",
-    "zh-HK",
-    "zh-TW",
-    "nl-NL",
-    "en-IN",
-    "en-US",
-    "fil-PH",
-    "fr-FR",
-    "de-DE",
-    "gu-IN",
-    "he-IL",
-    "hi-IN",
-    "id-ID",
-    "it-IT",
-    "ja-JP",
-    "kn-IN",
-    "ko-KR",
-    "ms-MY",
-    "fa-IR",
-    "pt-PT",
-    "ru-RU",
-    "es-ES",
-    "ta-IN",
-    "te-IN",
-    "th-TH",
-    "tr-TR",
-    "vi-VN",
-]
-
-TURN_DETECTION_LANGUAGE_VALUES: Tuple[TurnDetectionLanguage, ...] = (
-    "ar-EG",
-    "ar-JO",
-    "ar-SA",
-    "ar-AE",
-    "bn-IN",
-    "zh-CN",
-    "zh-HK",
-    "zh-TW",
-    "nl-NL",
-    "en-IN",
-    "en-US",
-    "fil-PH",
-    "fr-FR",
-    "de-DE",
-    "gu-IN",
-    "he-IL",
-    "hi-IN",
-    "id-ID",
-    "it-IT",
-    "ja-JP",
-    "kn-IN",
-    "ko-KR",
-    "ms-MY",
-    "fa-IR",
-    "pt-PT",
-    "ru-RU",
-    "es-ES",
-    "ta-IN",
-    "te-IN",
-    "th-TH",
-    "tr-TR",
-    "vi-VN",
-)
-_TURN_DETECTION_LANGUAGES = set(TURN_DETECTION_LANGUAGE_VALUES)
 _DEEPGRAM_MANAGED_MODELS = {"nova-2", "nova-3"}
 
 
-def _turn_detection_language(language: Optional[str]) -> Optional[TurnDetectionLanguage]:
-    if language in _TURN_DETECTION_LANGUAGES:
-        return language  # type: ignore[return-value]
-    return None
-
-
 class SpeechmaticsSTTOptions(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
@@ -112,9 +35,6 @@ def to_config(self) -> Dict[str, Any]:
             "vendor": "speechmatics",
             "params": params,
         }
-        turn_detection_language = _turn_detection_language(self.options.language)
-        if turn_detection_language is not None:
-            config["language"] = turn_detection_language
         return config
 
 
@@ -155,9 +75,6 @@ def to_config(self) -> Dict[str, Any]:
             "vendor": "deepgram",
             "params": params,
         }
-        turn_detection_language = _turn_detection_language(self.options.language)
-        if turn_detection_language is not None:
-            config["language"] = turn_detection_language
         return config
 
 
@@ -186,9 +103,6 @@ def to_config(self) -> Dict[str, Any]:
             "vendor": "microsoft",
             "params": params,
         }
-        turn_detection_language = _turn_detection_language(self.options.language)
-        if turn_detection_language is not None:
-            config["language"] = turn_detection_language
         return config
 
 
@@ -223,9 +137,6 @@ def to_config(self) -> Dict[str, Any]:
             "vendor": "openai",
             "params": params,
         }
-        turn_detection_language = _turn_detection_language(self.options.language)
-        if turn_detection_language is not None:
-            config["language"] = turn_detection_language
         return config
 
 
@@ -260,9 +171,6 @@ def to_config(self) -> Dict[str, Any]:
             "vendor": "google",
             "params": params,
         }
-        turn_detection_language = _turn_detection_language(self.options.language)
-        if turn_detection_language is not None:
-            config["language"] = turn_detection_language
         return config
 
 
@@ -293,9 +201,6 @@ def to_config(self) -> Dict[str, Any]:
             "vendor": "amazon",
             "params": params,
         }
-        turn_detection_language = _turn_detection_language(self.options.language)
-        if turn_detection_language is not None:
-            config["language"] = turn_detection_language
         return config
 
 
@@ -323,16 +228,12 @@ def to_config(self) -> Dict[str, Any]:
             "vendor": "assemblyai",
             "params": params,
         }
-        turn_detection_language = _turn_detection_language(self.options.language)
-        if turn_detection_language is not None:
-            config["language"] = turn_detection_language
         return config
 
 
 class AresSTTOptions(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
-    language: Optional[TurnDetectionLanguage] = Field(default=None, description="Language code")
     additional_params: Optional[Dict[str, Any]] = Field(default=None)
 
 class AresSTT(BaseSTT):
@@ -341,8 +242,6 @@ def __init__(self, **kwargs: Any):
 
     def to_config(self) -> Dict[str, Any]:
         config: Dict[str, Any] = {"vendor": "ares"}
-        if self.options.language is not None:
-            config["language"] = self.options.language
         if self.options.additional_params:
             config["params"] = self.options.additional_params
         return config
@@ -373,7 +272,4 @@ def to_config(self) -> Dict[str, Any]:
             "vendor": "sarvam",
             "params": params,
         }
-        turn_detection_language = _turn_detection_language(self.options.language)
-        if turn_detection_language is not None:
-            config["language"] = turn_detection_language
         return config

tests/custom/test_stt_language.py

@@ -43,17 +43,17 @@ def test_bcp47_stt_language_stays_in_asr_params_and_defaults_turn_detection() ->
     props = properties(base_agent().with_stt(SpeechmaticsSTT(api_key="stt-key", language="en")))
 
     assert props["asr"]["vendor"] == "speechmatics"
-    assert "language" not in props["asr"]
-    assert props["turn_detection"]["language"] == "en"
+    assert props["asr"]["language"] == "en-US"
+    assert props["turn_detection"]["language"] == "en-US"
     assert props["asr"]["params"]["language"] == "en"
 
 
-def test_provider_language_defaults_turn_detection_language_when_not_supported_by_ares() -> None:
+def test_provider_language_does_not_set_turn_detection_language() -> None:
     props = properties(base_agent().with_stt(SpeechmaticsSTT(api_key="stt-key", language="en")))
 
     assert props["asr"]["vendor"] == "speechmatics"
-    assert "language" not in props["asr"]
-    assert props["turn_detection"]["language"] == "en"
+    assert props["asr"]["language"] == "en-US"
+    assert props["turn_detection"]["language"] == "en-US"
     assert props["asr"]["params"]["language"] == "en"
 
 
@@ -66,7 +66,7 @@ def test_turn_detection_language_can_differ_from_provider_language() -> None:
     )
 
     assert props["turn_detection"]["language"] == "fr-FR"
-    assert "language" not in props["asr"]
+    assert props["asr"]["language"] == "fr-FR"
     assert props["asr"]["params"]["language"] == "en"
 
 
@@ -78,12 +78,14 @@ def test_invalid_turn_detection_language_is_rejected() -> None:
 def test_default_turn_detection_language_is_sent_without_stt() -> None:
     props = properties(base_agent())
 
-    assert props["asr"] == {"vendor": "ares"}
-    assert props["turn_detection"] == {"language": "en"}
+    assert props["asr"] == {"vendor": "ares", "language": "en-US"}
+    assert props["turn_detection"] == {"language": "en-US"}
 
 
 def test_stt_vendor_params_match_documented_shapes() -> None:
-    assert DeepgramSTT(model="nova-3", language="en-US").to_config()["params"] == {
+    deepgram_managed = DeepgramSTT(model="nova-3", language="en-US").to_config()
+    assert "language" not in deepgram_managed
+    assert deepgram_managed["params"] == {
         "model": "nova-3",
         "language": "en-US",
     }
@@ -132,8 +134,30 @@ def test_stt_vendor_params_match_documented_shapes() -> None:
         "language_code": "en-US",
     }
 
-    assert AssemblyAISTT(api_key="assembly-key", language="en-US", uri="wss://example.test/ws").to_config()["params"] == {
+    assemblyai_config = AssemblyAISTT(api_key="assembly-key", language="en-US", uri="wss://example.test/ws").to_config()
+    assert "language" not in assemblyai_config
+    assert assemblyai_config["params"] == {
         "api_key": "assembly-key",
         "language": "en-US",
         "uri": "wss://example.test/ws",
     }
+
+
+def test_assemblyai_params_stay_nested_and_asr_language_comes_from_turn_detection() -> None:
+    props = properties(
+        Agent(turn_detection=TurnDetectionConfig(language="fr-FR"))
+        .with_llm(OpenAI(api_key="llm-key", model="gpt-4o-mini", base_url="https://api.openai.com/v1/chat/completions"))
+        .with_tts(ElevenLabsTTS(key="tts-key", voice_id="voice", model_id="eleven_flash_v2_5", base_url="wss://api.elevenlabs.io/v1"))
+        .with_stt(AssemblyAISTT(api_key="assembly-key", language="en-US", uri="wss://example.test/ws"))
+    )
+
+    assert props["asr"] == {
+        "vendor": "assemblyai",
+        "language": "fr-FR",
+        "params": {
+            "api_key": "assembly-key",
+            "language": "en-US",
+            "uri": "wss://example.test/ws",
+        },
+    }
+    assert props["turn_detection"] == {"language": "fr-FR"}