fix(features): honor ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS

Closes #5114

Made-with: Cursor

Author: jinnigu

src/google/adk/a2a/experimental.py

@@ -27,7 +27,10 @@
         "themselves not experimental. Once it's stable enough the experimental "
         "mode will be removed. Your feedback is welcome."
     ),
-    bypass_env_var="ADK_SUPPRESS_A2A_EXPERIMENTAL_FEATURE_WARNINGS",
+    bypass_env_var=(
+        "ADK_SUPPRESS_A2A_EXPERIMENTAL_FEATURE_WARNINGS",
+        "ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS",
+    ),
 )
 """Mark a class or function as experimental A2A feature.
 

src/google/adk/features/_feature_registry.py

@@ -20,6 +20,7 @@
 from typing import Generator
 import warnings
 
+from ..utils.env_utils import is_experimental_warning_suppressed
 from ..utils.env_utils import is_env_enabled
 
 
@@ -300,6 +301,12 @@ def _emit_non_stable_warning_once(
     feature_name: The feature name.
     feature_stage: The feature stage.
   """
+  if (
+      feature_stage == FeatureStage.EXPERIMENTAL
+      and is_experimental_warning_suppressed()
+  ):
+    return
+
   if feature_name not in _WARNED_FEATURES:
     _WARNED_FEATURES.add(feature_name)
     full_message = (

src/google/adk/utils/env_utils.py

@@ -22,6 +22,11 @@
 
 import os
 
+_EXTENDED_TRUTHY_ENV_VALUES = frozenset({'1', 'true', 'yes', 'on'})
+_EXPERIMENTAL_WARNING_SUPPRESSION_ENV_VAR = (
+    'ADK_SUPPRESS_EXPERIMENTAL_FEATURE_WARNINGS'
+)
+
 
 def is_env_enabled(env_var_name: str, default: str = '0') -> bool:
   """Check if an environment variable is enabled.
@@ -57,3 +62,41 @@ def is_env_enabled(env_var_name: str, default: str = '0') -> bool:
     True
   """
   return os.environ.get(env_var_name, default).lower() in ['true', '1']
+
+
+def is_env_truthy(env_var_name: str) -> bool:
+  """Check if an environment variable uses ADK's permissive truthy values.
+
+  This helper preserves the historical parsing used for experimental warning
+  suppression and accepts ``1``, ``true``, ``yes``, and ``on``.
+
+  Args:
+    env_var_name: The name of the environment variable to check.
+
+  Returns:
+    True if the environment variable is set to a truthy value, False otherwise.
+  """
+  value = os.environ.get(env_var_name)
+  if value is None:
+    return False
+  return value.strip().lower() in _EXTENDED_TRUTHY_ENV_VALUES
+
+
+def is_experimental_warning_suppressed(
+    *additional_env_var_names: str,
+) -> bool:
+  """Check whether experimental warnings should be suppressed.
+
+  Args:
+    *additional_env_var_names: Optional warning-specific env vars that should
+      also suppress experimental warnings.
+
+  Returns:
+    True if the general experimental warning suppression env var, or any
+    provided additional env var, is truthy.
+  """
+  env_var_names = (
+      _EXPERIMENTAL_WARNING_SUPPRESSION_ENV_VAR,
+      *additional_env_var_names,
+  )
+  return any(is_env_truthy(env_var_name) for env_var_name in env_var_names)

src/google/adk/utils/feature_decorator.py

@@ -16,29 +16,34 @@
 
 from collections.abc import Callable
 import functools
-import os
 from typing import Any
 from typing import cast
-from typing import Optional
 from typing import TypeVar
 import warnings
 
+from .env_utils import is_env_truthy
+
 T = TypeVar("T")
 
 
-def _is_truthy_env(var_name: str) -> bool:
-  value = os.environ.get(var_name)
-  if value is None:
+def _should_bypass_warning(
+    bypass_env_var: str | tuple[str, ...] | None,
+) -> bool:
+  if bypass_env_var is None:
     return False
-  return value.strip().lower() in ("1", "true", "yes", "on")
+
+  env_var_names = (
+      (bypass_env_var,) if isinstance(bypass_env_var, str) else bypass_env_var
+  )
+  return any(is_env_truthy(env_var_name) for env_var_name in env_var_names)
 
 
 def _make_feature_decorator(
     *,
     label: str,
     default_message: str,
     block_usage: bool = False,
-    bypass_env_var: Optional[str] = None,
+    bypass_env_var: str | tuple[str, ...] | None = None,
 ) -> Callable[..., Any]:
   def decorator_factory(message_or_obj: Any = None) -> Any:
     # Case 1: Used as @decorator without parentheses
@@ -61,7 +66,10 @@ def decorator_factory(message_or_obj: Any = None) -> Any:
 
 
 def _create_decorator(
-    message: str, label: str, block_usage: bool, bypass_env_var: Optional[str]
+    message: str,
+    label: str,
+    block_usage: bool,
+    bypass_env_var: str | tuple[str, ...] | None,
 ) -> Callable[[T], T]:
   def decorator(obj: T) -> T:
     obj_name = getattr(obj, "__name__", type(obj).__name__)
@@ -74,9 +82,7 @@ def decorator(obj: T) -> T:
       @functools.wraps(orig_init)
       def new_init(self: Any, *args: Any, **kwargs: Any) -> Any:
         # Check if usage should be bypassed via environment variable at call time
-        should_bypass = bypass_env_var is not None and _is_truthy_env(
-            bypass_env_var
-        )
+        should_bypass = _should_bypass_warning(bypass_env_var)
 
         if should_bypass:
           # Bypass completely - no warning, no error
@@ -96,9 +102,7 @@ def new_init(self: Any, *args: Any, **kwargs: Any) -> Any:
       @functools.wraps(func)
       def wrapper(*args: Any, **kwargs: Any) -> Any:
         # Check if usage should be bypassed via environment variable at call time
-        should_bypass = bypass_env_var is not None and _is_truthy_env(
-            bypass_env_var
-        )
+        should_bypass = _should_bypass_warning(bypass_env_var)
 
         if should_bypass:
           # Bypass completely - no warning, no error