Merge pull request AgoraIO#48 from seymourtang/remove-default-asr-vendor

fix:fix default ASR vendor fallback for global and CN profiles

Author: plutoless

docs/concepts/agent.md

@@ -46,7 +46,7 @@ agent = Agent(client=client).with_llm(
 | `rtc` | `RtcConfig` | No | RTC media encryption |
 | `filler_words` | `FillerWordsConfig` | No | Filler words while waiting for LLM |
 
-When `client` is provided, `Agent(client=...)` returns `CNAgent` for `Area.CN` and `GlobalAgent` for global areas.
+When `client` is provided, `Agent(client=...)` returns `CNAgent` for `Area.CN` and `GlobalAgent` for global areas. If `with_stt()` is omitted, the bound client also determines the default ASR vendor: `Fengming` for `Area.CN`, otherwise `Ares`.
 
 ## Builder Methods
 

docs/concepts/vendors.md

@@ -24,7 +24,7 @@ Used with `agent.with_llm()` for the cascading flow (ASR → LLM → TTS).
 | `OpenAI` | OpenAI | `model` for Agora-managed global models; `api_key`, `base_url`, `model` for BYOK |
 | `AzureOpenAI` | Azure OpenAI | `api_key`, `model`, `endpoint`, `deployment_name` |
 | `Anthropic` | Anthropic | `api_key`, `model`, `url`, `headers`, `max_tokens` |
-| `Gemini` | Google Gemini | `api_key`, `model` |
+| `Gemini` | Google Gemini | `api_key`, `model`; optional `url` |
 | `Groq` | Groq | `api_key`, `model`, `base_url` |
 | `VertexAILLM` | Google Vertex AI | `api_key`, `model`, `project_id`, `location` |
 | `AmazonBedrock` | Amazon Bedrock | `access_key`, `secret_key`, `region`, `model` |
@@ -103,7 +103,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. Ares does not take a provider language option; AgentKit uses `turn_detection.language` for REST `asr.language`.
+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. If `with_stt()` is omitted, AgentKit defaults to `AresSTT` for global clients and `FengmingSTT` for `Area.CN` clients. Ares does not take a provider language option; AgentKit uses `turn_detection.language` for REST `asr.language`.
 
 | Class | Provider | Required Parameters |
 |---|---|---|

docs/guides/regional-routing.md

@@ -36,6 +36,7 @@ client = Agora(
 ## Recommended vendors by area
 
 Bind `client` into `Agent(client=client, ...)` and construct vendors directly with SDK classes. The bound client selects `CNAgent` or `GlobalAgent` for IDE hints based on `area`, but does not restrict which vendor classes you can configure.
+If you omit `with_stt()`, AgentKit uses `FengmingSTT` by default for `Area.CN` clients and `AresSTT` for global clients.
 
 | Client area | STT classes | LLM classes | TTS classes | Avatar classes |
 |---|---|---|---|---|
@@ -125,6 +126,7 @@ agent = Agent(client=client, turn_detection={"language": "zh-CN"})
 ```
 
 `Agent(client=...)` returns `CNAgent` for `Area.CN` and `GlobalAgent` for global areas. A bound `client` is required. The SDK does not reject mismatched vendor classes at build time or session start.
+The same bound client also controls the default ASR vendor when `with_stt()` is omitted.
 
 ## How the domain pool works
 

docs/reference/agent.md

@@ -9,6 +9,7 @@ description: Full API reference for the Python Agent builder class.
 **Import:** `from agora_agent import Agent, CNAgent, GlobalAgent`
 
 Bind the client on every `Agent` builder via `Agent(client=client, ...)`, then pass vendor classes directly. The bound client sets the API routing region and provides area-specific IDE hints via `CNAgent` / `GlobalAgent`:
+it also selects the default ASR vendor when `with_stt()` is omitted (`Fengming` for `Area.CN`, otherwise `Ares`).
 
 > **`client` is required.** `create_session()` and `create_async_session()` raise `ValueError` if no client was bound on the agent.
 

docs/reference/vendors.md

@@ -176,6 +176,7 @@ llm = Anthropic(
 |---|---|---|---|---|
 | `api_key` | `str` | Yes | — | Google AI API key |
 | `model` | `str` | Yes | — | Model name |
+| `url` | `str` | No | `None` | Custom Gemini `streamGenerateContent` URL. When omitted, the SDK constructs one from `model` and `api_key`. |
 | `temperature` | `float` | No | `None` | Sampling temperature (0.0–2.0) |
 | `top_p` | `float` | No | `None` | Nucleus sampling (0.0–1.0) |
 | `top_k` | `int` | No | `None` | Top-k sampling |
@@ -194,7 +195,10 @@ llm = Anthropic(
 ```python
 from agora_agent import Gemini
 
-llm = Gemini(api_key='your-google-key', model='gemini-2.0-flash-exp')
+llm = Gemini(
+    api_key='your-google-key',
+    model='gemini-2.0-flash-exp',
+)
 ```
 
 ### Other LLM vendors
@@ -412,7 +416,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. AgentKit populates REST `asr.language` from `turn_detection.language`.
+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. If `with_stt()` is omitted, AgentKit defaults to `AresSTT` for global clients and `FengmingSTT` for `Area.CN` clients. AgentKit populates REST `asr.language` from `turn_detection.language`.
 
 ### `SpeechmaticsSTT`
 

src/agora_agent/agentkit/agent.py

@@ -1078,7 +1078,8 @@ def _resolve_llm_config(self) -> typing.Dict[str, typing.Any]:
     def _resolve_asr_config(self, turn_detection_config: TurnDetectionInput) -> typing.Dict[str, typing.Any]:
         asr_config = dict(self._stt or {})
         if not asr_config:
-            asr_config["vendor"] = "ares"
+            area_scope = getattr(self._client, "area_scope", None)
+            asr_config["vendor"] = "fengming" if area_scope == "cn" else "ares"
         asr_config["language"] = self._field_value(turn_detection_config, "language")
         return asr_config
 

src/agora_agent/agentkit/vendors/llm.py

@@ -304,8 +304,10 @@ def to_config(self) -> Dict[str, Any]:
             params["max_output_tokens"] = self.options.max_output_tokens
 
         config: Dict[str, Any] = {
-            "url": self.options.url or "https://generativelanguage.googleapis.com/v1beta/models",
-            "api_key": self.options.api_key,
+            "url": self.options.url or (
+                f"https://generativelanguage.googleapis.com/v1beta/models/"
+                f"{self.options.model}:streamGenerateContent?alt=sse&key={self.options.api_key}"
+            ),
             "params": params,
             "style": "gemini",
             "input_modalities": self.options.input_modalities or ["text"],
@@ -394,7 +396,9 @@ def to_config(self) -> Dict[str, Any]:
                 f"{self.options.project_id}/locations/{self.options.location}/"
                 f"publishers/google/models/{self.options.model}:streamGenerateContent?alt=sse"
             )
-        return Gemini(**options).to_config()
+        config = Gemini(**options).to_config()
+        config["api_key"] = self.options.api_key
+        return config
 
 
 class AmazonBedrockOptions(BaseModel):

tests/custom/test_llm_vendors.py

@@ -69,6 +69,32 @@ def test_vertex_ai_llm_includes_project_routing() -> None:
     assert "location" not in config.get("params", {})
 
 
+def test_vertex_ai_llm_preserves_explicit_url() -> None:
+    config = VertexAILLM(
+        api_key="vertex-token",
+        model="gemini-2.0-flash",
+        project_id="project",
+        location="us-central1",
+        url="https://vertex.example.com/custom-endpoint",
+    ).to_config()
+
+    assert config["url"] == "https://vertex.example.com/custom-endpoint"
+    assert config["api_key"] == "vertex-token"
+    assert config["params"]["model"] == "gemini-2.0-flash"
+
+
+def test_gemini_constructs_url_from_api_key_and_model() -> None:
+    config = Gemini(
+        api_key="google-key",
+        model="gemini-2.0-flash",
+    ).to_config()
+
+    assert config["url"] == "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse&key=google-key"
+    assert "api_key" not in config
+    assert config["style"] == "gemini"
+    assert config["params"]["model"] == "gemini-2.0-flash"
+
+
 def test_amazon_bedrock_serializes_as_bedrock_style() -> None:
     config = AmazonBedrock(
         access_key="aws-access",

tests/custom/test_regional_vendors.py

@@ -66,6 +66,28 @@ def test_agent_constructor_auto_selects_area_aware_subclass() -> None:
     assert global_agent.__class__.__name__ == "GlobalAgent"
 
 
+def test_default_asr_vendor_is_area_aware_when_with_stt_is_omitted() -> None:
+    cn_properties = Agent(client=_client(Area.CN)).to_properties(
+        channel="room",
+        agent_uid="1",
+        remote_uids=["100"],
+        token="rtc-token",
+        allow_missing_vendor_categories={"llm", "tts"},
+    )
+    global_properties = Agent(client=_client(Area.US)).to_properties(
+        channel="room",
+        agent_uid="1",
+        remote_uids=["100"],
+        token="rtc-token",
+        allow_missing_vendor_categories={"llm", "tts"},
+    )
+
+    assert cn_properties.asr is not None
+    assert cn_properties.asr.vendor == "fengming"
+    assert global_properties.asr is not None
+    assert global_properties.asr.vendor == "ares"
+
+
 def test_cn_client_allows_global_only_vendor() -> None:
     client = _client(Area.CN)
     agent = Agent(client=client).with_stt(

tests/custom/test_request_body.py

@@ -898,9 +898,15 @@ def test_byok_anthropic_llm_params() -> None:
 
 
 def test_byok_gemini_llm_params() -> None:
-    agent = Agent(test_client()).with_llm(Gemini(api_key="gemini-key", model="gemini-2.0-flash"))
+    agent = Agent(test_client()).with_llm(
+        Gemini(
+            api_key="gemini-key",
+            model="gemini-2.0-flash",
+        )
+    )
     props = build_properties(agent, allow_missing={"asr", "tts"})
-    assert props["llm"]["api_key"] == "gemini-key"
+    assert "api_key" not in props["llm"]
+    assert props["llm"]["url"] == "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:streamGenerateContent?alt=sse&key=gemini-key"
     assert props["llm"]["style"] == "gemini"
     assert props["llm"]["params"]["model"] == "gemini-2.0-flash"