test(deps): allowlist what importing Agent and Runner loads

Co-authored-by: George Weale <gweale@google.com>
PiperOrigin-RevId: 965334785

Author: GWeale

tests/unittests/isolated_import_utils.py

@@ -20,6 +20,7 @@
 
 from __future__ import annotations
 
+import json
 import os
 from pathlib import Path
 import subprocess
@@ -54,6 +55,33 @@ def run_isolated(source: str) -> subprocess.CompletedProcess[str]:
     )
 
 
+def loaded_top_level_packages(source: str) -> frozenset[str]:
+  """Returns the third-party top-level packages source leaves imported.
+
+  Standard-library modules, private modules and the pseudo-modules the
+  interpreter injects carry no install or startup cost of their own, so they
+  are dropped and only the distributions a caller pays for remain.
+  """
+  result = run_isolated(f"""
+import json
+import sys
+{source}
+
+names = {{
+    name.partition('.')[0]
+    for name, module in sys.modules.items()
+    if getattr(module, '__spec__', None) is not None
+}}
+print(json.dumps(sorted(
+    name
+    for name in names - sys.stdlib_module_names
+    if not name.startswith('_')
+)))
+""")
+  assert result.returncode == 0, result.stderr
+  return frozenset(json.loads(result.stdout.splitlines()[-1]))
+
+
 def assert_modules_unloaded(source: str, forbidden: tuple[str, ...]) -> None:
   """Asserts source leaves every forbidden module (and submodule) unimported."""
   result = run_isolated(f"""

tests/unittests/test_import_loading.py

@@ -26,6 +26,7 @@
 
 from . import isolated_import_utils
 from .isolated_import_utils import assert_modules_unloaded
+from .isolated_import_utils import loaded_top_level_packages
 from .isolated_import_utils import run_isolated
 
 pytestmark = pytest.mark.skipif(
@@ -42,6 +43,59 @@
     'google.adk.workflow',
 )
 
+# The statements almost every ADK program starts with, and therefore the two
+# import graphs whose cost every user pays.
+_ENTRY_POINTS = (
+    'from google.adk.agents import Agent',
+    'from google.adk.runners import Runner',
+)
+
+# Third-party top-level packages an entry point may load. The forbidden lists
+# above pin individual deferrals on the lazy package inits; this one bounds the
+# whole graph, because the cost that reaches users arrives as a package nobody
+# noticed rather than as one somebody predicted.
+_ENTRY_POINT_PACKAGE_ALLOWLIST = frozenset({
+    # Declared requirements that ADK imports at module scope.
+    'click',
+    'fastapi',
+    'google',
+    'httpx',
+    'opentelemetry',
+    'packaging',
+    'pydantic',
+    'python_multipart',
+    'starlette',
+    'tenacity',
+    'websockets',
+    # Reached through pydantic and httpx rather than through ADK.
+    'annotated_doc',
+    'annotated_types',
+    'anyio',
+    'certifi',
+    'idna',
+    'orjson',
+    'pydantic_core',
+    'pygments',
+    'rich',
+    'sniffio',
+    'typing_extensions',
+    'typing_inspection',
+    'zstandard',
+    # google.genai.types annotates optional fields with aiohttp and Pillow
+    # types and imports whichever of the two the environment happens to have.
+    # No ADK module imports either one, so these are absent in some installs.
+    'PIL',
+    'aiohappyeyeballs',
+    'aiohttp',
+    'aiosignal',
+    'attr',
+    'defusedxml',
+    'frozenlist',
+    'multidict',
+    'propcache',
+    'yarl',
+})
+
 
 @pytest.mark.parametrize(
     ('module_name', 'forbidden'),
@@ -104,6 +158,29 @@ def test_package_import_defers_unrelated_runtime(
   )
 
 
+@pytest.mark.parametrize('statement', _ENTRY_POINTS, ids=('agent', 'runner'))
+def test_entry_point_loads_only_allowlisted_packages(statement: str) -> None:
+  """The two entry points every program uses load a reviewed set of packages.
+
+  The lazy package inits are already cheap, so a new eager dependency shows up
+  here first: as a package nobody agreed to pay for on every ADK start.
+
+  The unit is the top-level import name, so a new eager dependency arriving
+  under the `google` namespace, which ADK loads either way, does not show up
+  here.
+  """
+  unexpected = sorted(
+      loaded_top_level_packages(statement) - _ENTRY_POINT_PACKAGE_ALLOWLIST
+  )
+
+  assert not unexpected, (
+      f'{statement!r} now loads {", ".join(unexpected)}, which every ADK'
+      ' process would pay for at startup. Move the import into the function'
+      ' that needs it, or add the package to the allowlist together with the'
+      ' reason it has to be eager.'
+  )
+
+
 def test_constructing_agent_defers_optional_mcp_server_stack():
   """A normal Agent does not import MCP just because its extra is installed."""
   if importlib.util.find_spec('mcp') is None: