fix(dependencies): clarify missing Vertex AI extra

src/google/adk/dependencies/vertexai.py

@@ -11,9 +11,18 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Lazy import shim for Vertex AI optional dependencies."""
 
 from __future__ import annotations
 
-import vertexai
-from vertexai.preview import example_stores
-from vertexai.preview import rag
+try:
+  import vertexai
+  from vertexai.preview import example_stores
+  from vertexai.preview import rag
+except ImportError as e:
+  raise ImportError(
+      "Vertex AI features require google-adk[gcp] or google-adk[all]. "
+      "Install one of those extras to use google.adk.dependencies.vertexai."
+  ) from e
+
+__all__ = ["example_stores", "rag", "vertexai"]

tests/unittests/test_optional_dependencies.py

@@ -20,6 +20,7 @@
 
 from __future__ import annotations
 
+import importlib.util
 import os
 from pathlib import Path
 import subprocess
@@ -167,6 +168,25 @@ def test_vertex_ai_session_service_fails_on_creation():
     assert "google-cloud-aiplatform" in str(exc_info.value)
 
 
+def test_vertexai_dependency_shim_raises_clear_importerror():
+  """Verify that the Vertex AI dependency shim points users to the gcp extra."""
+  with mock.patch.dict("sys.modules", {"vertexai": None}):
+    module_path = _REPO_ROOT / "src/google/adk/dependencies/vertexai.py"
+    spec = importlib.util.spec_from_file_location(
+        "_test_google_adk_dependencies_vertexai", module_path
+    )
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+
+    with pytest.raises(ImportError) as exc_info:
+      spec.loader.exec_module(module)
+
+    message = str(exc_info.value)
+    assert "google-adk[gcp]" in message
+    assert "google-adk[all]" in message
+
+
 # =============================================================================
 # Approach 2: High-Fidelity Integration Tests (Clean Venv, Skipped by Default)
 # =============================================================================