Python: Reject candidate_count>1 in the Gemini chat client instead of silently dropping candidates

python/packages/gemini/agent_framework_gemini/_chat_client.py

@@ -892,6 +892,16 @@ def _prepare_config(
             if key == "stop" and isinstance(value, str):
                 # ChatOptions allows a single stop string; stop_sequences takes a list.
                 value = [value]
+            if key == "candidate_count" and value > 1:
+                # Both parsers read candidates[0] only, so more than one candidate
+                # would be billed but silently dropped. Reject explicitly rather
+                # than behave like candidate_count=1 (mirrors the Ollama client's
+                # unsupported-tool_choice rejection).
+                raise ChatClientInvalidRequestException(
+                    "Gemini chat client supports a single candidate. "
+                    f"candidate_count={value} would silently drop every candidate but the first; "
+                    "request one candidate (the default) instead."
+                )
             kwargs[_OPTION_TRANSLATIONS.get(key, key)] = value
 
         response_format = options.get("response_format")

python/packages/gemini/tests/test_gemini_client.py

@@ -3173,3 +3173,25 @@ async def sdk_stream():
             break
 
     assert closed
+
+
+def test_candidate_count_above_one_is_rejected(monkeypatch: pytest.MonkeyPatch) -> None:
+    """``candidate_count > 1`` is rejected instead of silently dropping candidates.
+
+    Both the streaming and non-streaming parsers read ``candidates[0]`` only, so a
+    multi-candidate request would bill for every candidate while silently
+    discarding all but the first. Mirrors the explicit-rejection precedent for
+    unsupported provider options (e.g. Ollama's ``tool_choice`` handling).
+    """
+    monkeypatch.setenv("GOOGLE_API_KEY", "test-key")
+    client = GeminiChatClient(model="gemini-2.5-flash")
+
+    with pytest.raises(ChatClientInvalidRequestException, match="candidate_count"):
+        client._prepare_config({"candidate_count": 2}, None)
+
+    # A single candidate (the default) flows through unchanged.
+    config = client._prepare_config({"candidate_count": 1}, None)
+    assert config.candidate_count == 1
+
+    config = client._prepare_config({}, None)
+    assert config.candidate_count is None