Separate STT provider language from turn detection defaults

Author: digitallysavvy

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-US` 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` 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

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-US`. 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`. STT vendor `language` options are serialized under `asr.params` using each provider's own format.
 
 | 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-US`. 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`. Provider-specific language values remain under `asr.params` and may use a different format.
 
 ### `SpeechmaticsSTT`
 

src/agora_agent/agentkit/agent.py

@@ -221,6 +221,7 @@ class SessionOptions(typing_extensions.TypedDict, total=False):
     "zh-HK",
     "zh-TW",
     "nl-NL",
+    "en",
     "en-IN",
     "en-US",
     "fil-PH",
@@ -246,7 +247,7 @@ class SessionOptions(typing_extensions.TypedDict, total=False):
     "vi-VN",
 ]
 
-DEFAULT_TURN_DETECTION_LANGUAGE: TurnDetectionLanguage = "en-US"
+DEFAULT_TURN_DETECTION_LANGUAGE: TurnDetectionLanguage = "en"
 TURN_DETECTION_LANGUAGE_VALUES: typing.Tuple[TurnDetectionLanguage, ...] = (
     "ar-EG",
     "ar-JO",
@@ -257,6 +258,7 @@ class SessionOptions(typing_extensions.TypedDict, total=False):
     "zh-HK",
     "zh-TW",
     "nl-NL",
+    "en",
     "en-IN",
     "en-US",
     "fil-PH",
@@ -963,13 +965,10 @@ def _resolve_asr_config(self) -> typing.Dict[str, typing.Any]:
         return asr_config
 
     def _resolve_turn_detection_config(self) -> TurnDetectionConfig:
-        existing_stt_language = self._stt.get("language") if self._stt is not None else None
         existing_turn_detection_language = self._field_value(self._turn_detection, "language")
         language = (
             existing_turn_detection_language
             if existing_turn_detection_language is not None
-            else existing_stt_language
-            if _is_turn_detection_language(existing_stt_language)
             else DEFAULT_TURN_DETECTION_LANGUAGE
         )
         language = _validate_turn_detection_language(language)

tests/custom/test_stt_language.py

@@ -39,21 +39,21 @@ def properties(agent: Agent) -> dict:
     )
 
 
-def test_bcp47_stt_language_sets_turn_detection_language_and_provider_param() -> None:
-    props = properties(base_agent().with_stt(SpeechmaticsSTT(api_key="stt-key", language="en-US")))
+def test_bcp47_stt_language_stays_in_asr_params_and_defaults_turn_detection() -> 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-US"
-    assert props["asr"]["params"]["language"] == "en-US"
+    assert props["turn_detection"]["language"] == "en"
+    assert props["asr"]["params"]["language"] == "en"
 
 
 def test_provider_language_defaults_turn_detection_language_when_not_supported_by_ares() -> 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-US"
+    assert props["turn_detection"]["language"] == "en"
     assert props["asr"]["params"]["language"] == "en"
 
 
@@ -71,15 +71,15 @@ def test_turn_detection_language_can_differ_from_provider_language() -> None:
 
 
 def test_invalid_turn_detection_language_is_rejected() -> None:
-    with pytest.raises(ValueError, match="Invalid interaction language: en"):
-        properties(Agent(turn_detection=TurnDetectionConfig(language="en")))  # type: ignore[arg-type]
+    with pytest.raises(ValueError, match="Invalid interaction language: xx"):
+        properties(Agent(turn_detection=TurnDetectionConfig(language="xx")))  # type: ignore[arg-type]
 
 
 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-US"}
+    assert props["turn_detection"] == {"language": "en"}
 
 
 def test_stt_vendor_params_match_documented_shapes() -> None: