google-adk v2.1.0 ships unguarded import vertexai without declaring vertexai as a dependency

[kriscon-db]

🔴 Required Information

Please ensure all items in this section are completed to allow for efficient
triaging. Requests without complete information may be rejected / deprioritized.
If an item is not applicable to you - please mark it as N/A

Describe the Bug:
google.adk.dependencies.vertexai does an unguarded top-level import vertexai, but vertexai is not in [project.dependencies]. It only ships via the [all] extra (transitively through google-cloud-aiplatform). A default install of google-adk crashes with ModuleNotFoundError: No module named 'vertexai' as soon as any consumer touches the shim, e.g. SafetyEvaluatorV1.evaluate_invocations (which does from ..dependencies.vertexai import vertexai at safety_evaluator.py:54).

Steps to Reproduce:

1. Create a clean Python 3.10+ venv.
2. pip install 'git+https://github.com/google/adk-python@v2.1.0'
3. python -c "from google.adk.dependencies import vertexai"

Expected Behavior:
A stock pip install google-adk should not ship modules that fail to import. Either declare vertexai in [project.dependencies], or guard the import and raise a clear "install google-adk[vertexai]" error.

Observed Behavior:

Traceback (most recent call last):  
    File "<string>", line 1, in <module>
    File ".venv/lib/python3.11/site-packages/google/adk/dependencies/vertexai.py", line 17, in <module>
      import vertexai                                                                                                                                                                                                                               
  ModuleNotFoundError: No module named 'vertexai'

Confirmed at tag v2.1.0 (commit 6d15e19). Workaround: pip install vertexai alongside google-adk.

Environment Details:

• ADK Library Version (pip show google-adk): 2.0.0 and 2.1.0
• Desktop OS:** MacOS
• Python Version (python -V): 3.11

Model Information:

N/A

---

🟡 Optional Information

Providing this information greatly speeds up the resolution process.

Regression:
Did this work in a previous version of ADK? If so, which one?

Versions before 2.0.0 did not have this issue.

Logs:
Please attach relevant logs. Wrap them in code blocks (```) or attach a
text file.

Attaching the output of a repro script I ran.

MacBook-Air:scripts kjc9$ ./repro.sh 
=== Installing uv (one-time, ~10MB) ===
downloading uv 0.11.16 aarch64-apple-darwin
installing to /Users/kjc9/.local/bin
  uv
  uvx
everything's installed!

To add $HOME/.local/bin to your PATH, either restart your shell or run:

    source $HOME/.local/bin/env (sh, bash, zsh)
    source $HOME/.local/bin/env.fish (fish)

=== Creating isolated venv in /var/folders/4_/dwr5wxxd3fndccmdtvhx1d600000gn/T/tmp.rN6SlNPWom (Python 3.11 via uv) ===
Using CPython 3.11.15
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

=== Installing google-adk @ v2.1.0 from GitHub (no extras) ===

=== Resolved versions ===
Name: google-adk
Version: 2.1.0

vertexai installed?
warning: Package(s) not found for: vertexai

=== Attempting import: google.adk.dependencies.vertexai ===
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/private/var/folders/4_/dwr5wxxd3fndccmdtvhx1d600000gn/T/tmp.rN6SlNPWom/.venv/lib/python3.11/site-packages/google/adk/dependencies/vertexai.py", line 17, in <module>
    import vertexai
ModuleNotFoundError: No module named 'vertexai'
(expected failure above — this is the bug)

=== Workaround: uv pip install vertexai ===

=== Re-attempting import after vertexai install ===
Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/private/var/folders/4_/dwr5wxxd3fndccmdtvhx1d600000gn/T/tmp.rN6SlNPWom/.venv/lib/python3.11/site-packages/google/adk/dependencies/vertexai.py", line 18, in <module>
    from vertexai.preview import example_stores
ImportError: cannot import name 'example_stores' from 'vertexai.preview' (/private/var/folders/4_/dwr5wxxd3fndccmdtvhx1d600000gn/T/tmp.rN6SlNPWom/.venv/lib/python3.11/site-packages/vertexai/preview/__init__.py)

=== Done. The import only succeeds after manually adding vertexai. ===
    Suggested fix on the google-adk side, in order of preference:
      1. Declare vertexai in [project.dependencies] (or move into [optional-dependencies.vertexai])
      2. If optional: guard the import in dependencies/vertexai.py:
           try:
               import vertexai
           except ImportError as e:
               raise ImportError("Install google-adk[vertexai] to use this feature") from e
      3. Document the [all] extra as required for any code path that
         touches the vertexai shim (least preferred — still crashes for
         users who don't read the docs).

Screenshots / Video:

Additional Context:

Minimal Reproduction Code:
Please provide a code snippet or a link to a Gist/repo that isolates the issue.

  python3 -m venv .venv
  source .venv/bin/activate                                                                                                                                                                                                                         
  pip install 'git+https://github.com/google/adk-python@v2.1.0'                                
                                      
  python -c "from google.adk.dependencies import vertexai"                                                                                                                                                                                          
  # ModuleNotFoundError: No module named 'vertexai'

How often has this issue occurred?:

• Always (100%)

[surajksharma07]

@kriscon-db A workaround worth trying: wrap the three imports in google/adk/dependencies/vertexai.py inside a try/except ImportError that re-raises with a clearer message like "Install google-adk[gcp] or google-adk[all] to use Vertex AI features".

Could you validate this works for your setup and run a full test pass?

[serejaris]

I can send a narrow PR for the maintainer-suggested guard if that helps: wrap the three imports in google/adk/dependencies/vertexai.py, re-raise a clear Install google-adk[gcp] or google-adk[all] to use Vertex AI features error, and add a regression test for importing the dependency shim without the GCP extra.

I reproduced the current failure by loading src/google/adk/dependencies/vertexai.py directly from current main in an environment without vertexai installed; it fails with ModuleNotFoundError: No module named 'vertexai'. I will wait for maintainer/reporter direction before opening a PR so this does not race the requested validation.