perf: improve adk import loading

Importing google.adk eagerly pulled in Agent, Runner, Workflow, and the server
and CLI runtimes even for callers that used none of them, and google-genai
imported the MCP client and FastMCP server stack whenever MCP happened to be
installed. The package, agents, workflow, cli, and cli.utils namespaces now
resolve their exports lazily on first use (PEP 562) through a shared
google.adk.utils._lazy helper. Importing google.adk drops from roughly 2.1s to
a few ms.

Public APIs and object identities are unchanged, with two things to note when
upgrading:

* The google-genai floor moves from 2.9 to 2.12.1, the release that defers MCP
  itself. Environments pinned below 2.12.1 will fail to resolve.
* google.adk.cli.utils no longer re-exports BaseAgent and LlmAgent. They were
  unused eager imports, never part of that module's __all__; import them from
  google.adk.agents instead.

Lazy resolution moves failures from import time to first use, so a missing or
broken optional dependency now surfaces on the first request rather than at
process start. Long-running servers pay the one-time resolution cost on their
first request; a warmup hook is deliberately left to a follow-up so this change
adds no public API.

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

Author: GWeale

pyproject.toml

@@ -37,7 +37,7 @@ dependencies = [
   "click>=8.1.8,<9",
   "fastapi>=0.133,<1",
   "google-auth[pyopenssl]>=2.47",
-  "google-genai>=2.9,<3",
+  "google-genai>=2.12.1,<3",
   "graphviz>=0.20.2,<1",
   "httpx>=0.27,<1",
   "jsonschema>=4.23,<5",

src/google/adk/__init__.py

@@ -14,12 +14,26 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from . import version
-from .agents.context import Context
-from .agents.llm_agent import Agent
-from .events.event import Event
-from .runners import Runner
-from .workflow import Workflow
+from .utils import _lazy
+
+if TYPE_CHECKING:
+  from .agents.context import Context
+  from .agents.llm_agent import Agent
+  from .events.event import Event
+  from .runners import Runner
+  from .workflow import Workflow
 
 __version__ = version.__version__
-__all__ = ["Agent", "Context", "Event", "Runner", "Workflow"]
+_LAZY_MEMBERS: dict[str, str] = {
+    'Agent': '.agents.llm_agent',
+    'Context': '.agents.context',
+    'Event': '.events.event',
+    'Runner': '.runners',
+    'Workflow': '.workflow',
+}
+__all__ = ['Agent', 'Context', 'Event', 'Runner', 'Workflow']
+
+__getattr__, __dir__ = _lazy.accessors(globals(), _LAZY_MEMBERS)

src/google/adk/agents/__init__.py

@@ -12,31 +12,52 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import importlib
-from typing import Any
+from __future__ import annotations
+
 from typing import TYPE_CHECKING
 
-from .base_agent import BaseAgent
-from .base_agent_config import BaseAgentConfig
-from .context import Context
-from .invocation_context import InvocationContext
-from .live_request_queue import LiveRequest
-from .live_request_queue import LiveRequestQueue
-from .llm_agent import Agent
-from .llm_agent import LlmAgent
-from .llm_agent_config import LlmAgentConfig
-from .loop_agent import LoopAgent
-from .loop_agent_config import LoopAgentConfig
-from .parallel_agent import ParallelAgent
-from .parallel_agent_config import ParallelAgentConfig
-from .run_config import RunConfig
-from .sequential_agent import SequentialAgent
-from .sequential_agent_config import SequentialAgentConfig
+from ..utils import _lazy
 
 if TYPE_CHECKING:
   from ._managed_agent import ManagedAgent
+  from .base_agent import BaseAgent
+  from .base_agent_config import BaseAgentConfig
+  from .context import Context
+  from .invocation_context import InvocationContext
+  from .live_request_queue import LiveRequest
+  from .live_request_queue import LiveRequestQueue
+  from .llm_agent import Agent
+  from .llm_agent import LlmAgent
+  from .llm_agent_config import LlmAgentConfig
+  from .loop_agent import LoopAgent
+  from .loop_agent_config import LoopAgentConfig
   from .mcp_instruction_provider import McpInstructionProvider
+  from .parallel_agent import ParallelAgent
+  from .parallel_agent_config import ParallelAgentConfig
+  from .run_config import RunConfig
+  from .sequential_agent import SequentialAgent
+  from .sequential_agent_config import SequentialAgentConfig
 
+_LAZY_MEMBERS: dict[str, str] = {
+    'Agent': '.llm_agent',
+    'BaseAgent': '.base_agent',
+    'BaseAgentConfig': '.base_agent_config',
+    'Context': '.context',
+    'InvocationContext': '.invocation_context',
+    'LiveRequest': '.live_request_queue',
+    'LiveRequestQueue': '.live_request_queue',
+    'LlmAgent': '.llm_agent',
+    'LlmAgentConfig': '.llm_agent_config',
+    'LoopAgent': '.loop_agent',
+    'LoopAgentConfig': '.loop_agent_config',
+    'ManagedAgent': '._managed_agent',
+    'McpInstructionProvider': '.mcp_instruction_provider',
+    'ParallelAgent': '.parallel_agent',
+    'ParallelAgentConfig': '.parallel_agent_config',
+    'RunConfig': '.run_config',
+    'SequentialAgent': '.sequential_agent',
+    'SequentialAgentConfig': '.sequential_agent_config',
+}
 __all__ = [
     'Agent',
     'BaseAgent',
@@ -58,21 +79,4 @@
     'SequentialAgentConfig',
 ]
 
-
-_LAZY_ATTRS = {
-    'ManagedAgent': '._managed_agent',
-    'McpInstructionProvider': '.mcp_instruction_provider',
-}
-
-
-def __getattr__(name: str) -> Any:
-  if name in _LAZY_ATTRS:
-    module = importlib.import_module(_LAZY_ATTRS[name], __name__)
-    attr = getattr(module, name)
-    globals()[name] = attr
-    return attr
-  raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
-
-
-def __dir__() -> list[str]:
-  return list(globals().keys()) + __all__
+__getattr__, __dir__ = _lazy.accessors(globals(), _LAZY_MEMBERS)

src/google/adk/cli/__init__.py

@@ -12,4 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .cli_tools_click import main
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..utils import _lazy
+
+if TYPE_CHECKING:
+  from .cli_tools_click import main
+
+_LAZY_MEMBERS: dict[str, str] = {
+    'main': '.cli_tools_click',
+}
+__all__ = ['main']
+
+__getattr__, __dir__ = _lazy.accessors(globals(), _LAZY_MEMBERS)

src/google/adk/cli/cli_tools_click.py

@@ -35,29 +35,56 @@
 
 import click
 from click.core import ParameterSource
-from fastapi import FastAPI
-import uvicorn
 
 from .. import version
-from ..agents.run_config import StreamingMode
-from ..evaluation.constants import MISSING_EVAL_DEPENDENCIES_MESSAGE
 from ..features import FeatureName
 from ..features import override_feature_enabled
 from ..utils._telemetry_config import read_telemetry_consent
 from ..utils._telemetry_config import write_telemetry_consent
 from ._telemetry._metrics_collector import MetricsCollector
-from .cli import run_cli
 from .utils import envs
 from .utils import logs
 
 if TYPE_CHECKING:
+  from fastapi import FastAPI
+
   from ..agents.llm_agent import LlmAgent
+  from ..agents.run_config import StreamingMode
+
 
 LOG_LEVELS = click.Choice(
     ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
     case_sensitive=False,
 )
 
+_STREAMING_MODE_CHOICES = ("None", "sse", "bidi")
+
+
+def _missing_eval_dependencies_message() -> str:
+  # Imported lazily so loading the CLI does not pull in the evaluation stack.
+  from ..evaluation.constants import MISSING_EVAL_DEPENDENCIES_MESSAGE
+
+  return MISSING_EVAL_DEPENDENCIES_MESSAGE
+
+
+def _parse_streaming_mode(
+    _ctx: click.Context,
+    param: click.Parameter,
+    value: str | None,
+) -> StreamingMode | None:
+  """Converts a validated CLI value without importing the runtime for help."""
+  if value is None:
+    return None
+
+  from ..agents.run_config import StreamingMode
+
+  mode = next(
+      (m for m in StreamingMode if str(m.value).lower() == value.lower()), None
+  )
+  if mode is None:
+    raise click.BadParameter(f"unknown streaming mode {value!r}", param=param)
+  return mode
+
 
 def _logging_options():
   """Decorator to add logging options to click commands."""
@@ -426,13 +453,8 @@ def conformance():
 )
 @click.argument(
     "streaming-mode",
-    type=click.Choice(
-        [str(m.value) for m in StreamingMode], case_sensitive=False
-    ),
-    callback=lambda ctx, param, value: next(
-        (m for m in StreamingMode if str(m.value).lower() == value.lower()),
-        value,
-    ),
+    type=click.Choice(_STREAMING_MODE_CHOICES, case_sensitive=False),
+    callback=_parse_streaming_mode,
 )
 @click.pass_context
 def cli_conformance_record(
@@ -516,15 +538,8 @@ def cli_conformance_record(
 )
 @click.option(
     "--streaming-mode",
-    type=click.Choice(
-        [str(m.value) for m in StreamingMode], case_sensitive=False
-    ),
-    callback=lambda ctx, param, value: next(
-        (m for m in StreamingMode if str(m.value).lower() == value.lower()),
-        value,
-    )
-    if value is not None
-    else None,
+    type=click.Choice(_STREAMING_MODE_CHOICES, case_sensitive=False),
+    callback=_parse_streaming_mode,
     required=False,
     default=None,
 )
@@ -940,6 +955,8 @@ def cli_run(
     sys.exit(exit_code)
   else:
     # Legacy interactive mode
+    from .cli import run_cli
+
     asyncio.run(
         run_cli(
             agent_parent_dir=agent_parent_folder,
@@ -1182,7 +1199,7 @@ def cli_eval(
     from .cli_eval import parse_and_get_evals_to_run
     from .cli_eval import pretty_print_eval_result
   except ModuleNotFoundError as mnf:
-    raise click.ClickException(MISSING_EVAL_DEPENDENCIES_MESSAGE) from mnf
+    raise click.ClickException(_missing_eval_dependencies_message()) from mnf
 
   eval_config = get_evaluation_criteria_or_default(config_file_path)
   print(f"Using evaluation criteria: {eval_config}")
@@ -1305,7 +1322,7 @@ def cli_eval(
         )
     )
   except ModuleNotFoundError as mnf:
-    raise click.ClickException(MISSING_EVAL_DEPENDENCIES_MESSAGE) from mnf
+    raise click.ClickException(_missing_eval_dependencies_message()) from mnf
 
   click.echo(
       "*********************************************************************"
@@ -1413,7 +1430,7 @@ def cli_optimize(
     from .cli_eval import get_root_agent
 
   except ModuleNotFoundError as mnf:
-    raise click.ClickException(MISSING_EVAL_DEPENDENCIES_MESSAGE) from mnf
+    raise click.ClickException(_missing_eval_dependencies_message()) from mnf
 
   with open(sampler_config_file_path, "r", encoding="utf-8") as f:
     content = f.read()
@@ -1551,7 +1568,7 @@ def cli_add_eval_case(
     from .cli_eval import get_eval_sets_manager
 
   except ModuleNotFoundError as mnf:
-    raise click.ClickException(MISSING_EVAL_DEPENDENCIES_MESSAGE) from mnf
+    raise click.ClickException(_missing_eval_dependencies_message()) from mnf
 
   app_name = os.path.basename(agent_module_file_path)
   agents_dir = os.path.dirname(agent_module_file_path)
@@ -1649,7 +1666,7 @@ def cli_generate_eval_cases(
     from .utils.state import create_empty_state
 
   except ModuleNotFoundError as mnf:
-    raise click.ClickException(MISSING_EVAL_DEPENDENCIES_MESSAGE) from mnf
+    raise click.ClickException(_missing_eval_dependencies_message()) from mnf
 
   app_name = os.path.basename(agent_module_file_path)
   agents_dir = os.path.dirname(agent_module_file_path)
@@ -1994,6 +2011,8 @@ async def _lifespan(app: FastAPI):
         fg="green",
     )
 
+  import uvicorn
+
   from .fast_api import get_fast_api_app
 
   app = get_fast_api_app(
@@ -2123,6 +2142,8 @@ def cli_api_server(
 
   logs.setup_adk_logger(getattr(logging, log_level.upper()))
 
+  import uvicorn
+
   from .fast_api import get_fast_api_app
 
   config = uvicorn.Config(

src/google/adk/cli/utils/__init__.py

@@ -12,16 +12,23 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import re
-from typing import Any
-from typing import Optional
+from __future__ import annotations
 
-from ...agents.base_agent import BaseAgent
-from ...agents.llm_agent import LlmAgent
-from .dot_adk_folder import DotAdkFolder
-from .state import create_empty_state
+from typing import TYPE_CHECKING
 
+from ...utils import _lazy
+
+if TYPE_CHECKING:
+  from .dot_adk_folder import DotAdkFolder
+  from .state import create_empty_state
+
+_LAZY_MEMBERS: dict[str, str] = {
+    'create_empty_state': '.state',
+    'DotAdkFolder': '.dot_adk_folder',
+}
 __all__ = [
     'create_empty_state',
     'DotAdkFolder',
 ]
+
+__getattr__, __dir__ = _lazy.accessors(globals(), _LAZY_MEMBERS)