Add new functionality behind flag

litellm/__init__.py

@@ -224,6 +224,11 @@ use_chat_completions_url_for_anthropic_messages: bool = bool(
 route_all_chat_openai_to_responses: bool = (
     os.getenv("LITELLM_ROUTE_ALL_CHAT_OPENAI_TO_RESPONSES", "false").lower() == "true"
 )  # When True, routes all OpenAI /chat/completions requests through the Responses API bridge
+# When True, Gemini/Vertex Live setup is deferred until client `session.update`.
+# Default False preserves historical behavior (auto-send setup on connect).
+gemini_live_defer_setup: bool = (
+    os.getenv("LITELLM_GEMINI_LIVE_DEFER_SETUP", "false").lower() == "true"
+)
 retry = True
 ### AUTH ###
 api_key: Optional[str] = None

litellm/llms/gemini/realtime/transformation.py

@@ -5,6 +5,7 @@ This file contains the transformation logic for the Gemini realtime API.
 import json
 from typing import Any, Dict, List, Optional, Union, cast
 
+import litellm
 from litellm import verbose_logger
 from litellm._uuid import uuid
 from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
@@ -1136,10 +1137,10 @@ class GeminiRealtimeConfig(BaseRealtimeConfig):
         }
 
     def requires_session_configuration(self) -> bool:
-        # Return False so we DON'T auto-send setup on connection
-        # Instead, setup will be sent when client sends session.update
-        # This allows us to include tools, instructions, etc. in the FIRST setup
-        return False
+        # Default behavior is backwards-compatible: send setup on connect.
+        # Opt-in to deferred setup for tool-injection flow via:
+        #   litellm.gemini_live_defer_setup = True
+        return not litellm.gemini_live_defer_setup
 
     def session_configuration_request(self, model: str) -> str:
         """

tests/test_litellm/llms/gemini/realtime/test_gemini_realtime_transformation.py

@@ -369,6 +369,18 @@ def test_gemini_realtime_session_update_with_tools():
     assert "parameters" in function_decl
 
 
+def test_gemini_requires_session_configuration_feature_flag(monkeypatch):
+    config = GeminiRealtimeConfig()
+
+    # Default behavior remains backwards-compatible (auto setup on connect)
+    monkeypatch.setattr(litellm, "gemini_live_defer_setup", False, raising=False)
+    assert config.requires_session_configuration() is True
+
+    # Opt-in behavior: defer setup until client sends session.update
+    monkeypatch.setattr(litellm, "gemini_live_defer_setup", True, raising=False)
+    assert config.requires_session_configuration() is False
+
+
 def test_gemini_realtime_function_call_output_transformation():
     """Test transformation of OpenAI function_call_output to Gemini toolResponse format."""
     config = GeminiRealtimeConfig()

tests/test_litellm/llms/vertex_ai/realtime/test_vertex_ai_realtime_transformation.py

@@ -19,6 +19,7 @@ import websockets.exceptions  # registers websockets.exceptions on the websocket
 
 sys.path.insert(0, os.path.abspath("../../../../.."))
 
+import litellm
 from litellm.llms.vertex_ai.realtime.transformation import VertexAIRealtimeConfig
 
 # ---------------------------------------------------------------------------
@@ -82,6 +83,20 @@ def test_session_configuration_request_model_format():
     )
 
 
+def test_vertex_requires_session_configuration_feature_flag(monkeypatch):
+    cfg = VertexAIRealtimeConfig(
+        access_token="tok", project="my-proj", location="us-central1"
+    )
+
+    # Default remains backwards-compatible (auto setup on connect)
+    monkeypatch.setattr(litellm, "gemini_live_defer_setup", False, raising=False)
+    assert cfg.requires_session_configuration() is True
+
+    # Opt-in deferred setup for tool-injection flow
+    monkeypatch.setattr(litellm, "gemini_live_defer_setup", True, raising=False)
+    assert cfg.requires_session_configuration() is False
+
+
 # ---------------------------------------------------------------------------
 # Round-trip test: text-in / text-out via RealTimeStreaming
 # ---------------------------------------------------------------------------