Python: Add Google AI package scaffolding (#1938)

Jeyaramjj · Jeyaram Jeyaraj · web-flow · commit 851534cc6087 · 2025-11-07T11:26:16.000+01:00
* feat(python): Add Google AI/Vertex AI package scaffolding (1/6) This is the first PR in a series to port Google service connectors from Semantic Kernel to Agent Framework. Changes: - Created agent_framework_google package structure - Added GoogleAISettings class for Gemini API - Added VertexAISettings class for Vertex AI - Comprehensive test coverage (17 test cases) - Documentation with usage examples and roadmap - Updated .gitignore for internal dev docs Following azure-ai connector pattern as reference (with py.typed). Future PRs will add: - PR #2: GoogleAIChatClient implementation - PR #3: GoogleAI integration tests & samples - PR #4: VertexAIChatClient implementation - PR #5: VertexAI integration tests & samples - PR #6: Advanced features & polish Dependencies verified against Semantic Kernel: - google-generativeai>=0.8,<1 (SK uses ~=0.8) - google-cloud-aiplatform>=1.60,<2 (SK uses ~=1.114.0) * refactor: align with Anthropic pattern - use location, chat_model_id, and version fields for Google settings * Address PR #1938 review comments: migrate to google-genai SDK, add Python 3.14, simplify to Google AI only - Migrate from google-generativeai to google-genai SDK (>=0.2,<1) - Add Python 3.14 classifier support - Simplify to Google AI only (remove VertexAI settings and tests) - Remove google-cloud-aiplatform dependency - Update README to reflect Google AI focus and google-genai SDK - Add comprehensive GAP_ANALYSIS.md with 4-phase implementation plan - Add PR1938_CHECKLIST.md tracking review feedback and next steps - Verify implementation against official Google migration guide - All tests passing (5 tests, 100% coverage) Addresses feedback from @eavanvalkenburg: 1. Added Python 3.14 support 2. Switched to google-genai (GA release, Google-recommended) 3. Removed VertexAI to simplify first iteration * fix: Address pre-commit hooks failures - Export GoogleAISettings in __init__.py for public API - Update README.md example to use SecretStr for type safety - Comment out future code example to avoid pyright validation errors - Auto-format code with ruff Addresses CI feedback from PR reviewer. --------- Co-authored-by: Jeyaram Jeyaraj <jejeyara@microsoft.com>
diff --git a/.gitignore b/.gitignore
@@ -211,4 +211,8 @@ WARP.md
 **/frontend/dist/
 
 # Database files
-*.db
+*.db
+
+# Package development docs (internal use only)
+**/GAP_ANALYSIS.md
+**/PR*_CHECKLIST.md
diff --git a/python/packages/google/LICENSE b/python/packages/google/LICENSE
@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE
diff --git a/python/packages/google/README.md b/python/packages/google/README.md
@@ -0,0 +1,117 @@
+# Get Started with Microsoft Agent Framework Google
+
+> **Note**: This package is currently under active development. The chat client implementation for Google AI is coming soon. This initial release provides the foundational settings and configuration classes.
+
+Please install this package via pip:
+
+```bash
+pip install agent-framework-google --pre
+```
+
+## Google AI (Gemini API) Integration
+
+This package provides integration with Google's Gemini API for Agent Framework:
+
+- **Google AI (Gemini API)**: Direct access to Google's Gemini models with API key authentication
+
+> **Note**: This package uses the new `google-genai` SDK as recommended by Google. See the [migration guide](https://ai.google.dev/gemini-api/docs/migrate) for more information.
+
+### Current Status
+
+**Available Now:**
+- `GoogleAISettings`: Configuration class for Google AI (Gemini API) authentication and settings
+
+**Coming Soon:**
+- `GoogleAIChatClient`: Chat client for Google AI with streaming, function calling, and multi-modal support
+- Integration tests and usage samples
+
+### Configuration
+
+You can configure the settings class now, which will be used by the chat client in the next release:
+
+#### Google AI Settings
+
+```python
+from agent_framework_google import GoogleAISettings
+
+# Configure via environment variables
+# GOOGLE_AI_API_KEY=your_api_key
+# GOOGLE_AI_CHAT_MODEL_ID=gemini-1.5-pro
+
+settings = GoogleAISettings()
+
+# Or pass parameters directly (pass SecretStr for type safety)
+from pydantic import SecretStr
+
+settings = GoogleAISettings(
+    api_key=SecretStr("your_api_key"),
+    chat_model_id="gemini-1.5-pro"
+)
+```
+
+### Future Usage (Coming Soon)
+
+Once the chat client is released, usage will look like this:
+
+```python
+# from agent_framework.google import GoogleAIChatClient
+#
+# # Configure via environment variables
+# # GOOGLE_AI_API_KEY=your_api_key
+# # GOOGLE_AI_CHAT_MODEL_ID=gemini-1.5-pro
+#
+# client = GoogleAIChatClient()
+# agent = client.create_agent(
+#     name="Assistant",
+#     instructions="You are a helpful assistant"
+# )
+#
+# response = await agent.run("Hello!")
+# print(response.text)
+```
+
+## Configuration
+
+### Environment Variables
+
+**Google AI:**
+- `GOOGLE_AI_API_KEY`: Your Google AI API key ([Get one here](https://ai.google.dev/))
+- `GOOGLE_AI_CHAT_MODEL_ID`: Model to use (e.g., `gemini-1.5-pro`, `gemini-1.5-flash`)
+
+### Supported Models
+
+- `gemini-1.5-pro`: Most capable model
+- `gemini-1.5-flash`: Faster, cost-effective model
+- `gemini-2.0-flash-exp`: Experimental latest model
+
+## Features
+
+### Planned Features
+- ✅ Chat completion (streaming and non-streaming)
+- ✅ Function/tool calling
+- ✅ Multi-modal support (text, images, video, audio)
+- ✅ System instructions
+- ✅ Conversation history management
+
+## Development Roadmap
+
+This package is being developed incrementally:
+
+- ✅ **Phase 1 (Current)**: Package structure and settings classes
+- 🚧 **Phase 2 (Next)**: Google AI chat client with streaming and function calling
+- 🚧 **Phase 3**: Google AI integration tests and samples
+- 🚧 **Phase 4**: Advanced features (context caching, safety settings, structured output)
+
+> **Note**: Vertex AI support may be added in a future iteration based on user demand.
+
+## Examples
+
+Examples will be available once the chat client is implemented. Check back soon or watch the [repository](https://github.com/microsoft/agent-framework) for updates.
+
+## Documentation
+
+For more information:
+- [Google AI Documentation](https://ai.google.dev/docs)
+- [Google Gemini API Migration Guide](https://ai.google.dev/gemini-api/docs/migrate)
+- [Agent Framework Documentation](https://aka.ms/agent-framework)
+- [Agent Framework Repository](https://github.com/microsoft/agent-framework)
diff --git a/python/packages/google/agent_framework_google/__init__.py b/python/packages/google/agent_framework_google/__init__.py
@@ -0,0 +1,17 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import importlib.metadata
+
+from ._chat_client import GoogleAISettings
+
+# NOTE: Client class will be imported here in a future PR
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+
+__all__ = [
+    "GoogleAISettings",
+    "__version__",
+]
diff --git a/python/packages/google/agent_framework_google/_chat_client.py b/python/packages/google/agent_framework_google/_chat_client.py
@@ -0,0 +1,48 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from typing import ClassVar
+
+from agent_framework._pydantic import AFBaseSettings
+from pydantic import SecretStr
+
+
+class GoogleAISettings(AFBaseSettings):
+    """Google AI settings for Gemini API access.
+
+    The settings are first loaded from environment variables with the prefix 'GOOGLE_AI_'.
+    If the environment variables are not found, the settings can be loaded from a .env file
+    with the encoding 'utf-8'. If the settings are not found in the .env file, the settings
+    are ignored; however, validation will fail alerting that the settings are missing.
+
+    Keyword Args:
+        api_key: The Google AI API key.
+        chat_model_id: The Google AI chat model ID (e.g., gemini-1.5-pro).
+        env_file_path: If provided, the .env settings are read from this file path location.
+        env_file_encoding: The encoding of the .env file, defaults to 'utf-8'.
+
+    Examples:
+        .. code-block:: python
+
+            from agent_framework.google import GoogleAISettings
+
+            # Using environment variables
+            # Set GOOGLE_AI_API_KEY=your_api_key
+            # GOOGLE_AI_CHAT_MODEL_ID=gemini-1.5-pro
+
+            settings = GoogleAISettings()
+
+            # Or passing parameters directly
+            settings = GoogleAISettings(api_key="your_api_key", chat_model_id="gemini-1.5-pro")
+
+            # Or loading from a .env file
+            settings = GoogleAISettings(env_file_path="path/to/.env")
+    """
+
+    env_prefix: ClassVar[str] = "GOOGLE_AI_"
+
+    api_key: SecretStr | None = None
+    chat_model_id: str | None = None
+
+
+# NOTE: Client implementations will be added in a future PR
+# For now, we're only setting up the package structure and settings
diff --git a/python/packages/google/agent_framework_google/py.typed b/python/packages/google/agent_framework_google/py.typed
diff --git a/python/packages/google/pyproject.toml b/python/packages/google/pyproject.toml
@@ -0,0 +1,90 @@
+[project]
+name = "agent-framework-google"
+description = "Google AI (Gemini API) integration for Microsoft Agent Framework."
+authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+version = "1.0.0b251104"
+license-files = ["LICENSE"]
+urls.homepage = "https://aka.ms/agent-framework"
+urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
+urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true"
+urls.issues = "https://github.com/microsoft/agent-framework/issues"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+    "agent-framework-core",
+    "google-genai>=0.2,<1",
+]
+
+[tool.uv]
+prerelease = "if-necessary-or-explicit"
+environments = [
+    "sys_platform == 'darwin'",
+    "sys_platform == 'linux'",
+    "sys_platform == 'win32'"
+]
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.0"
+
+[tool.pytest.ini_options]
+testpaths = 'tests'
+addopts = "-ra -q -r fEX"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = [
+    "ignore:Support for class-based `config` is deprecated:DeprecationWarning:pydantic.*"
+]
+timeout = 120
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.coverage.run]
+omit = [
+    "**/__init__.py"
+]
+
+[tool.pyright]
+extends = "../../pyproject.toml"
+exclude = ['tests']
+
+[tool.mypy]
+plugins = ['pydantic.mypy']
+strict = true
+python_version = "3.10"
+ignore_missing_imports = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+check_untyped_defs = true
+warn_return_any = true
+show_error_codes = true
+warn_unused_ignores = false
+disallow_incomplete_defs = true
+disallow_untyped_decorators = true
+
+[tool.bandit]
+targets = ["agent_framework_google"]
+exclude_dirs = ["tests"]
+
+[tool.poe]
+executor.type = "uv"
+include = "../../shared_tasks.toml"
+[tool.poe.tasks]
+mypy = "mypy --config-file $POE_ROOT/pyproject.toml agent_framework_google"
+test = "pytest --cov=agent_framework_google --cov-report=term-missing:skip-covered tests"
+
+[build-system]
+requires = ["flit-core >= 3.11,<4.0"]
+build-backend = "flit_core.buildapi"
diff --git a/python/packages/google/tests/conftest.py b/python/packages/google/tests/conftest.py
@@ -0,0 +1,41 @@
+# Copyright (c) Microsoft. All rights reserved.
+from typing import Any
+
+from pytest import fixture
+
+
+@fixture
+def exclude_list(request: Any) -> list[str]:
+    """Fixture that returns a list of environment variables to exclude."""
+    return request.param if hasattr(request, "param") else []
+
+
+@fixture
+def override_env_param_dict(request: Any) -> dict[str, str]:
+    """Fixture that returns a dict of environment variables to override."""
+    return request.param if hasattr(request, "param") else {}
+
+
+@fixture
+def google_ai_unit_test_env(monkeypatch, exclude_list, override_env_param_dict):  # type: ignore
+    """Fixture to set environment variables for GoogleAISettings."""
+    if exclude_list is None:
+        exclude_list = []
+
+    if override_env_param_dict is None:
+        override_env_param_dict = {}
+
+    env_vars = {
+        "GOOGLE_AI_API_KEY": "test-api-key-12345",
+        "GOOGLE_AI_CHAT_MODEL_ID": "gemini-1.5-pro",
+    }
+
+    env_vars.update(override_env_param_dict)  # type: ignore
+
+    for key, value in env_vars.items():
+        if key in exclude_list:
+            monkeypatch.delenv(key, raising=False)  # type: ignore
+            continue
+        monkeypatch.setenv(key, value)  # type: ignore
+
+    return env_vars
diff --git a/python/packages/google/tests/test_settings.py b/python/packages/google/tests/test_settings.py
diff --git a/python/uv.lock b/python/uv.lock
