feat: add --google-api-key option for AI Studio support (#577)

Add CLI option to use Google AI Studio API key instead of Vertex AI:
- Generate .env file with GOOGLE_API_KEY when flag is passed
- Skip GCP credential checks when using API key
- Conditionally include/exclude Vertex AI initialization in agent templates

Author: eliasecchig

agent_starter_pack/agents/adk_a2a_base/app/agent.py

@@ -1,3 +1,4 @@
+# ruff: noqa
 # Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,17 +14,20 @@
 # limitations under the License.
 
 import datetime
-import os
 from zoneinfo import ZoneInfo
 
-import google.auth
 from google.adk.agents import Agent
 from google.adk.apps.app import App
+{%- if not cookiecutter.use_google_api_key %}
+
+import os
+import google.auth
 
 _, project_id = google.auth.default()
 os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
 os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
 os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
+{%- endif %}
 
 
 def get_weather(query: str) -> str:

agent_starter_pack/agents/adk_base/app/agent.py

@@ -1,3 +1,4 @@
+# ruff: noqa
 # Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,17 +14,20 @@
 # limitations under the License.
 
 import datetime
-import os
 from zoneinfo import ZoneInfo
 
-import google.auth
 from google.adk.agents import Agent
 from google.adk.apps.app import App
+{%- if not cookiecutter.use_google_api_key %}
+
+import os
+import google.auth
 
 _, project_id = google.auth.default()
 os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
 os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
 os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
+{%- endif %}
 
 
 def get_weather(query: str) -> str:

agent_starter_pack/agents/adk_live/app/agent.py

@@ -1,3 +1,4 @@
+# ruff: noqa
 # Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,19 +13,21 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import os
+from google.adk.agents import Agent
+from google.adk.apps.app import App
+{%- if not cookiecutter.use_google_api_key %}
 
+import os
 import google.auth
 import vertexai
-from google.adk.agents import Agent
-from google.adk.apps.app import App
 
 _, project_id = google.auth.default()
 os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
 os.environ["GOOGLE_CLOUD_LOCATION"] = "us-central1"
 os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
 
 vertexai.init(project=project_id, location="us-central1")
+{%- endif %}
 
 
 def get_weather(query: str) -> str:

agent_starter_pack/cli/commands/create.py

@@ -58,6 +58,12 @@
 def shared_template_options(f: Callable) -> Callable:
     """Decorator to add shared options for template-based commands."""
     # Apply options in reverse order since decorators are applied bottom-up
+    f = click.option(
+        "--google-api-key",
+        type=str,
+        help="Use Google AI Studio API key instead of Vertex AI. Generates a .env file with the provided API key.",
+        default=None,
+    )(f)
     f = click.option(
         "-ag",
         "--agent-garden",
@@ -274,6 +280,7 @@ def create(
     skip_welcome: bool = False,
     locked: bool = False,
     cli_overrides: dict | None = None,
+    google_api_key: str | None = None,
 ) -> None:
     """Create GCP-based AI agent projects from templates."""
     try:
@@ -715,11 +722,19 @@ def create(
         if debug:
             logging.debug(f"Selected region: {region}")
 
+        # Validate google_api_key is not used with langgraph agents
+        if google_api_key and "langgraph" in final_agent.lower():
+            raise click.ClickException(
+                "--google-api-key is not supported for LangGraph agents. "
+                "You can modify the generated template to use ChatGoogleGenerativeAI class instead. "
+                "See https://docs.langchain.com/oss/python/integrations/chat/google_generative_ai"
+            )
+
         # GCP Setup
         logging.debug("Setting up GCP...")
 
         creds_info = {}
-        if not skip_checks:
+        if not skip_checks and not google_api_key:
             # Set up GCP environment
             try:
                 creds_info = setup_gcp_environment(
@@ -778,6 +793,7 @@ def create(
                 cli_overrides=final_cli_overrides,
                 agent_garden=agent_garden,
                 remote_spec=remote_spec,
+                google_api_key=google_api_key,
             )
 
             # Replace region in all files if a different region was specified

agent_starter_pack/cli/commands/enhance.py

@@ -266,6 +266,7 @@ def enhance(
     base_template: str | None,
     adk: bool,
     agent_directory: str | None,
+    google_api_key: str | None = None,
 ) -> None:
     """Enhance your existing project with AI agent capabilities.
 
@@ -642,4 +643,5 @@ def enhance(
         base_template=base_template,
         skip_welcome=True,  # Skip welcome message since enhance shows its own
         cli_overrides=final_cli_overrides if final_cli_overrides else None,
+        google_api_key=google_api_key,
     )

agent_starter_pack/cli/utils/template.py

@@ -750,6 +750,7 @@ def process_template(
     cli_overrides: dict[str, Any] | None = None,
     agent_garden: bool = False,
     remote_spec: Any | None = None,
+    google_api_key: str | None = None,
 ) -> None:
     """Process the template directory and create a new project.
 
@@ -768,6 +769,7 @@ def process_template(
         in_folder: Whether to template directly into the output directory instead of creating a subdirectory
         cli_overrides: Optional CLI override values that should take precedence over template config
         agent_garden: Whether this deployment is from Agent Garden
+        google_api_key: Optional Google AI Studio API key to generate .env file
     """
     logging.debug(f"Processing template from {template_dir}")
     logging.debug(f"Project name: {project_name}")
@@ -1040,6 +1042,7 @@ def get_agent_directory(
                 "agent_garden": agent_garden,
                 "agent_sample_id": agent_sample_id or "",
                 "agent_sample_publisher": agent_sample_publisher or "",
+                "use_google_api_key": bool(google_api_key),
                 "adk_cheatsheet": adk_cheatsheet_content,
                 "llm_txt": llm_txt_content,
                 "_copy_without_render": [
@@ -1422,6 +1425,19 @@ def get_agent_directory(
                     lock_file.truncate()
                 logging.debug(f"Updated project name in lock file at {lock_file_path}")
 
+            # Generate .env file for Google API Key if provided
+            if google_api_key:
+                env_file_path = final_destination / agent_directory / ".env"
+                env_content = f"""# AI Studio Configuration
+GOOGLE_API_KEY={google_api_key}
+"""
+                env_file_path.write_text(env_content)
+                logging.debug(f"Generated .env file at {env_file_path}")
+                console.print(
+                    f"📝 Generated .env file at [cyan]{agent_directory}/.env[/cyan] "
+                    "for Google AI Studio"
+                )
+
         except Exception as e:
             logging.error(f"Failed to process template: {e!s}")
             raise

tests/cli/commands/test_create_local.py

@@ -278,6 +278,51 @@ def test_readme_and_pyproject_conflict_handling_in_folder_mode(
     assert other_file.read_text() == "# Other file content"
 
 
+@patch("agent_starter_pack.cli.commands.create.setup_gcp_environment")
+@patch("agent_starter_pack.cli.commands.create.replace_region_in_files")
+def test_create_with_google_api_key(
+    mock_replace_region: Mock,
+    mock_setup_gcp: Mock,
+    tmp_path: pathlib.Path,
+) -> None:
+    """Test the create command with --google-api-key generates .env and skips GCP init."""
+    runner = CliRunner()
+
+    result = runner.invoke(
+        create,
+        [
+            "my-test-project",
+            "--google-api-key",
+            "test-api-key-12345",
+            "--auto-approve",
+            "--deployment-target",
+            "agent_engine",
+            "--output-dir",
+            str(tmp_path),
+        ],
+        catch_exceptions=False,
+    )
+
+    assert result.exit_code == 0, result.output
+
+    # GCP setup should NOT be called when using google-api-key
+    mock_setup_gcp.assert_not_called()
+
+    # Verify .env file was created with the API key
+    env_file = tmp_path / "my-test-project" / "app" / ".env"
+    assert env_file.exists(), ".env file should be created"
+    env_content = env_file.read_text()
+    assert "GOOGLE_API_KEY=test-api-key-12345" in env_content
+
+    # Verify agent.py does NOT contain GCP initialization code
+    agent_file = tmp_path / "my-test-project" / "app" / "agent.py"
+    assert agent_file.exists(), "agent.py should exist"
+    agent_content = agent_file.read_text()
+    assert "google.auth.default" not in agent_content
+    assert "GOOGLE_GENAI_USE_VERTEXAI" not in agent_content
+    assert "GOOGLE_CLOUD_PROJECT" not in agent_content
+
+
 def test_readme_and_pyproject_conflict_handling_remote_template_mode(
     tmp_path: pathlib.Path,
 ) -> None: