feat: Add env var to suppress experimental warnings

This CL adds ADK_DISABLE_EXPERIMENTAL_WARNING to let the users to suppress warning messages from features decorated with @experimental.

Previously, using experimental features would always trigger a UserWarning. This change creates a way to disable these warnings, which can be good to stop flooding logs.

The warning is suppressed if ADK_DISABLE_EXPERIMENTAL_WARNING is set to a truthy value such as "true", "1", "yes", or "on" (case-insensitive).

Added unit tests to make sure:
Warning suppression for functions and classes when the env var is set.
Case-insensitivity and various truthy values for the env var.
Loading the env var from a .env file.

PiperOrigin-RevId: 794740730

Author: George Weale

src/google/adk/utils/feature_decorator.py

@@ -70,10 +70,18 @@ def new_init(self, *args, **kwargs):
             bypass_env_var is not None
             and os.environ.get(bypass_env_var, "").lower() == "true"
         )
+        # Suppress experimental warnings if env is set
+        suppress_experimental = (
+            label.upper() == "EXPERIMENTAL"
+            and os.environ.get("ADK_DISABLE_EXPERIMENTAL_WARNING", "").lower()
+            in ("1", "true", "yes", "on")
+        )
 
         if should_bypass:
           # Bypass completely - no warning, no error
           pass
+        elif suppress_experimental:
+          pass
         elif block_usage:
           raise RuntimeError(msg)
         else:
@@ -92,10 +100,18 @@ def wrapper(*args, **kwargs):
             bypass_env_var is not None
             and os.environ.get(bypass_env_var, "").lower() == "true"
         )
+        # Suppress experimental warnings if env is set
+        suppress_experimental = (
+            label.upper() == "EXPERIMENTAL"
+            and os.environ.get("ADK_DISABLE_EXPERIMENTAL_WARNING", "").lower()
+            in ("1", "true", "yes", "on")
+        )
 
         if should_bypass:
           # Bypass completely - no warning, no error
           pass
+        elif suppress_experimental:
+          pass
         elif block_usage:
           raise RuntimeError(msg)
         else:

tests/unittests/utils/test_feature_decorator.py

@@ -1,9 +1,11 @@
+import importlib
 import os
 import tempfile
 import warnings
+from unittest import mock
 
-from google.adk.utils.feature_decorator import experimental
-from google.adk.utils.feature_decorator import working_in_progress
+from google.adk.utils import feature_decorator
+from google.adk.utils.feature_decorator import experimental, working_in_progress
 
 
 @working_in_progress("in complete feature, don't use yet")
@@ -299,3 +301,93 @@ def test_experimental_function_empty_parens_warns():
     assert "This feature is experimental and may change or be removed" in str(
         w[0].message
     )
+
+
+def test_experimental_function_warning_suppressed_with_env_var():
+  """Test experimental function warning suppressed by env var."""
+  with mock.patch.dict(os.environ, {"ADK_DISABLE_EXPERIMENTAL_WARNING": "true"}):
+    importlib.reload(feature_decorator)
+    from google.adk.utils.feature_decorator import experimental
+
+    @experimental
+    def test_fn():
+      return "executing"
+
+    with warnings.catch_warnings(record=True) as w:
+      warnings.simplefilter("always")
+      result = test_fn()
+      assert result == "executing"
+      assert len(w) == 0
+  importlib.reload(feature_decorator)  # Reload to clean up
+
+
+def test_experimental_class_warning_suppressed_with_env_var():
+  """Test experimental class warning suppressed by env var."""
+  with mock.patch.dict(os.environ, {"ADK_DISABLE_EXPERIMENTAL_WARNING": "1"}):
+    importlib.reload(feature_decorator)
+    from google.adk.utils.feature_decorator import experimental
+
+    @experimental
+    class TestClass:
+      def run(self):
+        return "running experimental"
+
+    with warnings.catch_warnings(record=True) as w:
+      warnings.simplefilter("always")
+      result = TestClass().run()
+      assert result == "running experimental"
+      assert len(w) == 0
+  importlib.reload(feature_decorator)  # Reload to clean up
+
+
+def test_experimental_env_var_case_insensitive_and_truthy_values():
+  """Test experimental warning suppression with various truthy values."""
+  for val in ["true", "TRUE", "Yes", "on", "1"]:
+    with mock.patch.dict(os.environ, {"ADK_DISABLE_EXPERIMENTAL_WARNING": val}):
+      importlib.reload(feature_decorator)
+      from google.adk.utils.feature_decorator import experimental
+
+      @experimental
+      def test_fn():
+        return "executing"
+
+      with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        _ = test_fn()
+        assert len(w) == 0
+    importlib.reload(feature_decorator)  # Reload to clean up
+
+
+def test_experimental_suppression_loads_from_dotenv_file(tmp_path):
+  """Test experimental warning suppression loading from .env file."""
+  try:
+    from dotenv import load_dotenv
+  except ImportError:
+    import pytest
+    pytest.skip("python-dotenv not available")
+
+  env_file = tmp_path / ".env"
+  env_file.write_text("ADK_DISABLE_EXPERIMENTAL_WARNING=true\n")
+
+  # Clear the env var from os.environ if present
+  with mock.patch.dict(os.environ, {}):
+    os.environ.pop("ADK_DISABLE_EXPERIMENTAL_WARNING", None)
+    importlib.reload(feature_decorator)
+
+    load_dotenv(env_file.as_posix())
+    # We need to reload again *after* load_dotenv has modified os.environ
+    importlib.reload(feature_decorator)
+    from google.adk.utils.feature_decorator import experimental
+
+    @experimental
+    def test_fn():
+      return "executing"
+
+    try:
+      with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        _ = test_fn()
+        assert len(w) == 0
+    finally:
+      os.environ.pop("ADK_DISABLE_EXPERIMENTAL_WARNING", None)
+      importlib.reload(feature_decorator)  # Reload to clean up