Move AgentKit language to turn detection

  Move the Agora interaction language setting from the unlaunched top-level
  AgentKit API into turn_detection.language across TypeScript, Python, and Go.

  Remove the top-level interaction language helpers and STT vendor override
  fields, keep provider-specific STT language under asr.params, and default
  turn_detection.language to en-US when omitted.

  Update tests, READMEs, docs, and changelogs to reflect the final v2.1.0 API
  surface.

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.
-Use `with_interaction_language()` for Agora `asr.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`.
 
 ```python
 import os
@@ -54,7 +54,7 @@ def start_conversation() -> str:
         app_certificate=app_certificate,
     )
 
-    agent = Agent(name=f"conversation-{int(time.time())}").with_interaction_language("en-US").with_stt(
+    agent = Agent(name=f"conversation-{int(time.time())}", turn_detection={"language": "en-US"}).with_stt(
         DeepgramSTT(
             model="nova-3",
             language="en",
@@ -101,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_interaction_language("en-US").with_stt(
+agent = Agent(turn_detection={"language": "en-US"}).with_stt(
     DeepgramSTT(
         api_key=os.environ["DEEPGRAM_API_KEY"],
         model="nova-3",

changelog.md

@@ -8,7 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Added
 
-- **ASR interaction language** — AgentKit now manages Agora `asr.language` through `interaction_language` / `Agent.with_interaction_language()`, validates it against the supported BCP-47 interaction 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-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.
-- **ASR language separation** — Provider-specific STT language values remain under `asr.params`, while Agora interaction language is emitted separately as `asr.language`.
+- **Language placement** — Provider-specific STT language values remain under `asr.params`, while Agora interaction language is emitted separately as `turn_detection.language`.
 
 ## [v2.0.0] — 2026-05-21
 

docs/concepts/agent.md

@@ -64,7 +64,7 @@ Each `with_*` method returns a **new** `Agent` instance — the original is unch
 | `with_instructions(text)` | `str` | Deprecated. Use LLM vendor `system_messages` instead. |
 | `with_greeting(text)` | `str` | Deprecated. Use LLM/MLLM vendor `greeting_message` instead. |
 | `with_name(name)` | `str` | Override the agent name |
-| `with_turn_detection(config)` | `TurnDetectionConfig` | Override cascading-flow SOS/EOS detection; use `with_interruption()` for interruption behavior |
+| `with_turn_detection(config)` | `TurnDetectionConfig` | Configure `turn_detection.language` and cascading-flow SOS/EOS detection; use `with_interruption()` for interruption behavior |
 | `with_sal(config)` | `SalConfig` | Set SAL configuration |
 | `with_advanced_features(features)` | `Dict[str, Any]` | Set advanced features |
 | `with_parameters(parameters)` | `SessionParams` | Set session parameters |

docs/concepts/vendors.md

@@ -75,7 +75,7 @@ tts = ElevenLabsTTS(
 
 Used with `agent.with_stt()`.
 
-Use `agent.with_interaction_language()` for Agora `asr.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-US`. STT vendor `language` options are serialized under `asr.params` using each provider's own format.
 
 | Class | Provider | Required Parameters |
 |---|---|---|

docs/reference/agent.md

@@ -34,7 +34,7 @@ Agent(
 |---|---|---|---|
 | `name` | `Optional[str]` | `None` | Agent name, used as default session name |
 | `instructions` | `Optional[str]` | `None` | Deprecated. Use LLM vendor `system_messages` instead. |
-| `turn_detection` | `Optional[TurnDetectionConfig]` | `None` | Turn detection configuration |
+| `turn_detection` | `Optional[TurnDetectionConfig]` | `None` | Interaction language and turn detection configuration |
 | `interruption` | `Optional[InterruptionConfig]` | `None` | Unified interruption control configuration |
 | `sal` | `Optional[SalConfig]` | `None` | Speech Activity Level configuration |
 | `advanced_features` | `Optional[Dict[str, Any]]` | `None` | Advanced features dict (e.g., `{'enable_rtm': True}`) |
@@ -109,7 +109,7 @@ agent = agent.with_avatar(HeyGenAvatar(api_key='your-key', quality='medium', ago
 
 ### `with_turn_detection(config: TurnDetectionConfig) -> Agent`
 
-Override cascading-flow turn detection settings. Use `config.start_of_speech` and `config.end_of_speech` for SOS/EOS detection. Use `with_interruption()` for interruption behavior and MLLM vendor `turn_detection` for MLLM turn detection.
+Override cascading-flow turn detection settings. Use `language` for the Agora interaction language, `config.start_of_speech` and `config.end_of_speech` for SOS/EOS detection, `with_interruption()` for interruption behavior, and MLLM vendor `turn_detection` for MLLM turn detection.
 
 Pause-state detection is configured under semantic end-of-speech:
 
@@ -257,7 +257,7 @@ to_properties(
 | `stt` | `Optional[Dict[str, Any]]` | STT config dict |
 | `mllm` | `Optional[Dict[str, Any]]` | MLLM config dict |
 | `avatar` | `Optional[Dict[str, Any]]` | Avatar config dict |
-| `turn_detection` | `Optional[TurnDetectionConfig]` | Turn detection settings |
+| `turn_detection` | `Optional[TurnDetectionConfig]` | Interaction language and turn detection settings |
 | `sal` | `Optional[SalConfig]` | SAL configuration |
 | `advanced_features` | `Optional[Dict[str, Any]]` | Advanced features |
 | `parameters` | `Optional[SessionParams]` | Session parameters |

docs/reference/vendors.md

@@ -318,15 +318,14 @@ The SDK also includes named helpers for the remaining Agora-supported LLM provid
 
 ## STT Vendors
 
-Use `agent.with_interaction_language()` for Agora `asr.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-US`. Provider-specific language values remain under `asr.params` and may use a different format.
 
 ### `SpeechmaticsSTT`
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `api_key` | `str` | Yes | — | Speechmatics API key |
 | `language` | `str` | Yes | — | Language code (e.g., `en`) |
-| `interaction_language` | `str` | No | `None` | Agora `asr.language` override |
 | `uri` | `str` | No | `None` | Speechmatics streaming WebSocket URL |
 | `additional_params` | `Dict[str, Any]` | No | `None` | Additional parameters |
 
@@ -337,7 +336,6 @@ Use `agent.with_interaction_language()` for Agora `asr.language`; it defaults to
 | `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 |
@@ -351,7 +349,6 @@ For `nova-2` and `nova-3`, omit `api_key` to use Agora-managed credentials. For
 | `key` | `str` | Yes | — | Azure subscription key |
 | `region` | `str` | Yes | — | Azure region (e.g., `eastus`) |
 | `language` | `str` | Yes | — | Language code (e.g., `en-US`) |
-| `interaction_language` | `str` | No | `None` | Agora `asr.language` override |
 | `additional_params` | `Dict[str, Any]` | No | `None` | Additional parameters |
 
 ### `OpenAISTT`
@@ -363,7 +360,6 @@ For `nova-2` and `nova-3`, omit `api_key` to use Agora-managed credentials. For
 | `language` | `str` | No | `None` | Language code |
 | `prompt` | `str` | No | `None` | Prompt for OpenAI transcription |
 | `input_audio_transcription` | `Dict[str, Any]` | No | `None` | OpenAI transcription settings |
-| `interaction_language` | `str` | No | `None` | Agora `asr.language` override |
 | `additional_params` | `Dict[str, Any]` | No | `None` | Additional parameters |
 
 ### `GoogleSTT`
@@ -374,7 +370,6 @@ For `nova-2` and `nova-3`, omit `api_key` to use Agora-managed credentials. For
 | `location` | `str` | Yes | — | Google Cloud region |
 | `adc_credentials_string` | `str` | Yes | — | Google service account credentials JSON string |
 | `language` | `str` | Yes | — | Language code (e.g., `en-US`) |
-| `interaction_language` | `str` | No | `None` | Agora `asr.language` override |
 | `model` | `str` | No | `None` | Recognition model |
 | `additional_params` | `Dict[str, Any]` | No | `None` | Additional parameters |
 
@@ -386,7 +381,6 @@ For `nova-2` and `nova-3`, omit `api_key` to use Agora-managed credentials. For
 | `secret_key` | `str` | Yes | — | AWS Secret Access Key |
 | `region` | `str` | Yes | — | AWS region (e.g., `us-east-1`) |
 | `language` | `str` | Yes | — | Amazon `language_code` |
-| `interaction_language` | `str` | No | `None` | Agora `asr.language` override |
 | `additional_params` | `Dict[str, Any]` | No | `None` | Additional parameters |
 
 ### `AssemblyAISTT`
@@ -395,7 +389,6 @@ For `nova-2` and `nova-3`, omit `api_key` to use Agora-managed credentials. For
 |---|---|---|---|---|
 | `api_key` | `str` | Yes | — | AssemblyAI API key |
 | `language` | `str` | Yes | — | Language code |
-| `interaction_language` | `str` | No | `None` | Agora `asr.language` override |
 | `uri` | `str` | No | `None` | AssemblyAI streaming WebSocket URL |
 | `additional_params` | `Dict[str, Any]` | No | `None` | Additional parameters |
 

src/agora_agent/agentkit/__init__.py

@@ -3,7 +3,7 @@
     AgentConfig,
     AgentConfigUpdate,
     AsrConfig,
-    InteractionLanguage,
+    TurnDetectionLanguage,
     ConversationHistory,
     ConversationRole,
     ConversationSessionTurn,
@@ -205,7 +205,7 @@
     "LlmStyle",
     "SttConfig",
     "AsrConfig",
-    "InteractionLanguage",
+    "TurnDetectionLanguage",
     "SttVendor",
     "TtsConfig",
     "MllmConfig",

src/agora_agent/agentkit/agent.py

@@ -210,7 +210,7 @@ class SessionOptions(typing_extensions.TypedDict, total=False):
 
 from .token import generate_convo_ai_token, _parse_numeric_uid, _validate_expires_in
 
-InteractionLanguage = typing_extensions.Literal[
+TurnDetectionLanguage = typing_extensions.Literal[
     "ar-EG",
     "ar-JO",
     "ar-SA",
@@ -245,8 +245,8 @@ class SessionOptions(typing_extensions.TypedDict, total=False):
     "vi-VN",
 ]
 
-DEFAULT_INTERACTION_LANGUAGE: InteractionLanguage = "en-US"
-INTERACTION_LANGUAGE_VALUES: typing.Tuple[InteractionLanguage, ...] = (
+DEFAULT_TURN_DETECTION_LANGUAGE: TurnDetectionLanguage = "en-US"
+TURN_DETECTION_LANGUAGE_VALUES: typing.Tuple[TurnDetectionLanguage, ...] = (
     "ar-EG",
     "ar-JO",
     "ar-SA",
@@ -280,7 +280,7 @@ class SessionOptions(typing_extensions.TypedDict, total=False):
     "tr-TR",
     "vi-VN",
 )
-_INTERACTION_LANGUAGES = set(INTERACTION_LANGUAGE_VALUES)
+_TURN_DETECTION_LANGUAGES = set(TURN_DETECTION_LANGUAGE_VALUES)
 
 
 def _dump_optional_model(value: typing.Any) -> typing.Any:
@@ -291,12 +291,12 @@ def _dump_optional_model(value: typing.Any) -> typing.Any:
     return value
 
 
-def _is_interaction_language(value: typing.Any) -> bool:
-    return isinstance(value, str) and value in _INTERACTION_LANGUAGES
+def _is_turn_detection_language(value: typing.Any) -> bool:
+    return isinstance(value, str) and value in _TURN_DETECTION_LANGUAGES
 
 
-def _validate_interaction_language(value: typing.Any) -> InteractionLanguage:
-    if not _is_interaction_language(value):
+def _validate_turn_detection_language(value: typing.Any) -> TurnDetectionLanguage:
+    if not _is_turn_detection_language(value):
         raise ValueError(f"Invalid interaction language: {value}")
     return value  # type: ignore[return-value]
 
@@ -335,7 +335,6 @@ def __init__(
         sal: typing.Optional[SalConfig] = None,
         advanced_features: typing.Optional[AdvancedFeatures] = None,
         parameters: typing.Optional[typing.Union[SessionParams, SessionParamsInput]] = None,
-        interaction_language: typing.Optional[InteractionLanguage] = None,
         greeting: typing.Optional[str] = None,
         failure_message: typing.Optional[str] = None,
         max_history: typing.Optional[int] = None,
@@ -362,11 +361,6 @@ def __init__(
         self._sal = sal
         self._advanced_features = advanced_features
         self._parameters = parameters
-        self._interaction_language = (
-            _validate_interaction_language(interaction_language)
-            if interaction_language is not None
-            else None
-        )
         self._geofence = geofence
         self._labels = labels
         self._rtc = rtc
@@ -400,16 +394,6 @@ def with_stt(self, vendor: BaseSTT) -> "Agent":
         new_agent._stt = vendor.to_config()
         return new_agent
 
-    def with_interaction_language(self, language: InteractionLanguage) -> "Agent":
-        """Returns a new Agent with the Agora interaction language.
-
-        This serializes to ``asr.language``. Vendor-specific language values
-        remain under ``asr.params``, for example ``asr.params.language``.
-        """
-        new_agent = self._clone()
-        new_agent._interaction_language = _validate_interaction_language(language)
-        return new_agent
-
     def with_mllm(self, vendor: BaseMLLM) -> "Agent":
         # Note: avatars are not supported with MLLM. The combination is rejected
         # at ``to_properties`` / ``AgentSession.start`` so callers can still
@@ -705,10 +689,6 @@ def rtc(self) -> typing.Optional[RtcConfig]:
     def filler_words(self) -> typing.Optional[FillerWordsConfig]:
         return self._filler_words
 
-    @property
-    def interaction_language(self) -> typing.Optional[InteractionLanguage]:
-        return self._interaction_language
-
     @property
     def config(self) -> typing.Dict[str, typing.Any]:
         return {
@@ -727,7 +707,6 @@ def config(self) -> typing.Dict[str, typing.Any]:
             "avatar": self._avatar,
             "advanced_features": self._advanced_features,
             "parameters": self._parameters,
-            "interaction_language": self._interaction_language,
             "geofence": self._geofence,
             "labels": self._labels,
             "rtc": self._rtc,
@@ -909,6 +888,7 @@ def to_properties(
             return StartAgentsRequestProperties(**base_kwargs)
 
         base_kwargs["asr"] = self._resolve_asr_config()
+        base_kwargs["turn_detection"] = self._resolve_turn_detection_config()
 
         if skip_vendor_validation:
             return StartAgentsRequestProperties(**base_kwargs)
@@ -940,13 +920,28 @@ def to_properties(
 
     def _resolve_asr_config(self) -> typing.Dict[str, typing.Any]:
         asr_config = dict(self._stt or {})
-        existing_language = asr_config.get("language")
-        language = self._interaction_language
-        if language is None:
-            language = existing_language if _is_interaction_language(existing_language) else DEFAULT_INTERACTION_LANGUAGE
-        asr_config["language"] = language
+        asr_config.pop("language", None)
+        if not asr_config:
+            asr_config["vendor"] = "ares"
         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)
+        if self._turn_detection is None:
+            return StartAgentsRequestPropertiesTurnDetection(language=language)
+        if isinstance(self._turn_detection, dict):
+            return typing.cast(TurnDetectionConfig, {**self._turn_detection, "language": language})
+        return self._copy_model_update(self._turn_detection, {"language": language})
+
     def _clone(self) -> "Agent":
         new_agent = Agent.__new__(Agent)
         new_agent._name = self._name
@@ -962,7 +957,6 @@ def _clone(self) -> "Agent":
         new_agent._sal = self._sal
         new_agent._advanced_features = self._advanced_features
         new_agent._parameters = self._parameters
-        new_agent._interaction_language = self._interaction_language
         new_agent._instructions = self._instructions
         new_agent._greeting = self._greeting
         new_agent._failure_message = self._failure_message