agent-starter-pack 0.17.5__py3-none-any.whl → 0.18.1__py3-none-any.whl

agent_starter_pack/base_template/Makefile

@@ -127,6 +127,8 @@ playground-remote: build-frontend-if-needed
 	@echo "==============================================================================="
 	uv run python -m {{cookiecutter.agent_directory}}.utils.expose_app --mode remote
 {%- endif %}
+{%- endif %}
+{%- if cookiecutter.is_adk_live and cookiecutter.deployment_target == 'agent_engine' %}
 
 # Start the frontend UI separately for development (requires backend running separately)
 ui:
@@ -154,9 +156,9 @@ playground-dev:
 
 # Deploy the agent remotely
 {%- if cookiecutter.deployment_target == 'cloud_run' %}
-# Usage: make backend [IAP=true] [PORT=8080] - Set IAP=true to enable Identity-Aware Proxy, PORT to specify container port
+# Usage: make deploy [IAP=true] [PORT=8080] - Set IAP=true to enable Identity-Aware Proxy, PORT to specify container port
 {%- endif %}
-backend:
+deploy:
 {%- if cookiecutter.deployment_target == 'cloud_run' %}
 	PROJECT_ID=$$(gcloud config get-value project) && \
 	gcloud beta run deploy {{cookiecutter.project_name}} \
@@ -177,6 +179,9 @@ backend:
 	uv export --no-hashes --no-header --no-dev --no-emit-project > .requirements.txt && uv run {{cookiecutter.agent_directory}}/agent_engine_app.py
 {%- endif %}
 
+# Alias for 'make deploy' for backward compatibility
+backend: deploy
+
 
 # ==============================================================================
 # Infrastructure Setup
@@ -226,3 +231,20 @@ lint:
 	uv run ruff check . --diff
 	uv run ruff format . --check --diff
 	uv run mypy .
+{%- if cookiecutter.is_adk and cookiecutter.deployment_target == 'agent_engine' %}
+
+# ==============================================================================
+# Gemini Enterprise Integration
+# ==============================================================================
+
+# Register the deployed agent to Gemini Enterprise
+# Usage: make register-gemini-enterprise GEMINI_ENTERPRISE_APP_ID=projects/{project_number}/locations/{location}/collections/{collection}/engines/{engine_id} [AGENT_ENGINE_ID=<id>]  # Defaults to deployment_metadata.json
+register-gemini-enterprise:
+	uvx --from agent-starter-pack agent-starter-pack-register-gemini-enterprise \
+		$(if $(GEMINI_ENTERPRISE_APP_ID),--gemini-enterprise-app-id="$(GEMINI_ENTERPRISE_APP_ID)",) \
+		$(if $(AGENT_ENGINE_ID),--agent-engine-id="$(AGENT_ENGINE_ID)",) \
+		$(if $(GEMINI_DISPLAY_NAME),--display-name="$(GEMINI_DISPLAY_NAME)",) \
+		$(if $(GEMINI_DESCRIPTION),--description="$(GEMINI_DESCRIPTION)",) \
+		$(if $(GEMINI_TOOL_DESCRIPTION),--tool-description="$(GEMINI_TOOL_DESCRIPTION)",) \
+		$(if $(GEMINI_AUTHORIZATION_ID),--authorization-id="$(GEMINI_AUTHORIZATION_ID)",)
+{%- endif %}

agent_starter_pack/base_template/README.md

@@ -59,16 +59,21 @@ make install && make playground
 {%- endif %}
 {%- if cookiecutter.deployment_target == 'cloud_run' %}
 | `make playground`    | Launch local development environment with backend and frontend{%- if cookiecutter.is_adk %} - leveraging `adk web` command. {%- endif %}|
-| `make backend`       | Deploy agent to Cloud Run (use `IAP=true` to enable Identity-Aware Proxy) |
-| `make local-backend` | Launch local development server |
-{%- if cookiecutter.deployment_target == 'cloud_run' %}
+| `make deploy`        | Deploy agent to Cloud Run (use `IAP=true` to enable Identity-Aware Proxy, `PORT=8080` to specify container port) |
+| `make local-backend` | Launch local development server with hot-reload |
+{%- elif cookiecutter.deployment_target == 'agent_engine' %}
+| `make playground`    | Launch Streamlit interface for testing agent locally and remotely |
+| `make deploy`        | Deploy agent to Agent Engine |
 {%- if cookiecutter.is_adk_live %}
-| `make ui`       | Launch Agent Playground front-end only |
+| `make local-backend` | Launch local development server with hot-reload |
+| `make ui`            | Start the frontend UI separately for development (requires backend running separately) |
+| `make playground-dev` | Launch dev playground with both frontend and backend hot-reload |
+| `make playground-remote` | Connect to remote deployed agent with local frontend |
+| `make build-frontend` | Build the frontend for production |
 {%- endif %}
+{%- if cookiecutter.is_adk %}
+| `make register-gemini-enterprise` | Register deployed agent to Gemini Enterprise (see Makefile for parameters) |
 {%- endif %}
-{%- elif cookiecutter.deployment_target == 'agent_engine' %}
-| `make playground`    | Launch Streamlit interface for testing agent locally and remotely |
-| `make backend`       | Deploy agent to Agent Engine |
 {%- endif %}
 | `make test`          | Run unit and integration tests                                                              |
 | `make lint`          | Run code quality checks (codespell, ruff, mypy)                                             |
@@ -76,7 +81,6 @@ make install && make playground
 {%- if cookiecutter.data_ingestion %}
 | `make data-ingestion`| Run data ingestion pipeline in the Dev environment                                           |
 {%- endif %}
-| `uv run jupyter lab` | Launch Jupyter notebook                                                                     |
 
 For full command options and usage, refer to the [Makefile](Makefile).
 
@@ -156,10 +160,10 @@ You can test deployment towards a Dev Environment using the following command:
 
 ```bash
 gcloud config set project <your-dev-project-id>
-make backend
+make deploy
 ```
 {% if cookiecutter.is_adk_live %}
-**Note:** For secure access to your deployed backend, consider using Identity-Aware Proxy (IAP) by running `make backend IAP=true`.
+**Note:** For secure access to your deployed backend, consider using Identity-Aware Proxy (IAP) by running `make deploy IAP=true`.
 {%- endif %}
 
 The repository includes a Terraform configuration for the setup of the Dev Google Cloud project.

agent_starter_pack/base_template/deployment/terraform/github.tf

@@ -276,6 +276,20 @@ data "google_secret_manager_secret" "github_pat" {
   secret_id = var.github_pat_secret_id
 }
 
+# Get CICD project data for Cloud Build service account
+data "google_project" "cicd_project" {
+  project_id = var.cicd_runner_project_id
+}
+
+# Grant Cloud Build service account access to GitHub PAT secret
+resource "google_secret_manager_secret_iam_member" "cloudbuild_secret_accessor" {
+  project   = var.cicd_runner_project_id
+  secret_id = data.google_secret_manager_secret.github_pat.secret_id
+  role      = "roles/secretmanager.secretAccessor"
+  member    = "serviceAccount:service-${data.google_project.cicd_project.number}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
+  depends_on = [resource.google_project_service.cicd_services]
+}
+
 # Create the GitHub connection (fallback for manual Terraform usage)
 resource "google_cloudbuildv2_connection" "github_connection" {
   count      = var.create_cb_connection ? 0 : 1
@@ -289,7 +303,11 @@ resource "google_cloudbuildv2_connection" "github_connection" {
       oauth_token_secret_version = "${data.google_secret_manager_secret.github_pat.id}/versions/latest"
     }
   }
-  depends_on = [resource.google_project_service.cicd_services, resource.google_project_service.deploy_project_services]
+  depends_on = [
+    resource.google_project_service.cicd_services,
+    resource.google_project_service.deploy_project_services,
+    resource.google_secret_manager_secret_iam_member.cloudbuild_secret_accessor
+  ]
 }
 
 

agent_starter_pack/cli/utils/register_gemini_enterprise.py

@@ -0,0 +1,406 @@
+#!/usr/bin/env python3
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+
+"""Utility to register an Agent Engine to Gemini Enterprise."""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+import requests
+import vertexai
+from google.auth import default
+from google.auth.transport.requests import Request as GoogleAuthRequest
+
+
+def get_agent_engine_id(
+    agent_engine_id: str | None, metadata_file: str = "deployment_metadata.json"
+) -> str:
+    """Get the agent engine ID from parameter or deployment metadata.
+
+    Args:
+        agent_engine_id: Optional agent engine resource name
+        metadata_file: Path to deployment metadata JSON file
+
+    Returns:
+        The agent engine resource name
+
+    Raises:
+        ValueError: If agent_engine_id is not provided and metadata file doesn't exist
+    """
+    if agent_engine_id:
+        return agent_engine_id
+
+    # Try to read from deployment_metadata.json
+    metadata_path = Path(metadata_file)
+    if not metadata_path.exists():
+        raise ValueError(
+            f"No agent engine ID provided and {metadata_file} not found. "
+            "Please provide --agent-engine-id or deploy your agent first."
+        )
+
+    with open(metadata_path) as f:
+        metadata = json.load(f)
+        return metadata["remote_agent_engine_id"]
+
+
+def get_access_token() -> str:
+    """Get Google Cloud access token.
+
+    Returns:
+        Access token string
+
+    Raises:
+        SystemExit: If authentication fails
+    """
+    try:
+        credentials, _ = default()
+        auth_req = GoogleAuthRequest()
+        credentials.refresh(auth_req)
+        return credentials.token
+    except Exception as e:
+        print(f"Error getting access token: {e}", file=sys.stderr)
+        print(
+            "Please ensure you are authenticated with 'gcloud auth application-default login'",
+            file=sys.stderr,
+        )
+        raise RuntimeError("Failed to get access token") from e
+
+
+def get_agent_engine_metadata(agent_engine_id: str) -> tuple[str | None, str | None]:
+    """Fetch display_name and description from deployed Agent Engine.
+
+    Args:
+        agent_engine_id: Agent Engine resource name
+
+    Returns:
+        Tuple of (display_name, description) - either can be None if not found
+    """
+    parts = agent_engine_id.split("/")
+    if len(parts) < 6:
+        return None, None
+
+    project_id = parts[1]
+    location = parts[3]
+
+    try:
+        client = vertexai.Client(project=project_id, location=location)
+        agent_engine = client.agent_engines.get(name=agent_engine_id)
+
+        display_name = getattr(agent_engine.api_resource, "display_name", None)
+        description = getattr(agent_engine.api_resource, "description", None)
+
+        return display_name, description
+    except Exception as e:
+        print(
+            f"Warning: Could not fetch metadata from Agent Engine: {e}", file=sys.stderr
+        )
+        return None, None
+
+
+def register_agent(
+    agent_engine_id: str,
+    gemini_enterprise_app_id: str,
+    display_name: str,
+    description: str,
+    tool_description: str,
+    project_id: str | None = None,
+    authorization_id: str | None = None,
+) -> dict:
+    """Register an agent engine to Gemini Enterprise.
+
+    This function attempts to create a new agent registration. If the agent is already
+    registered (same reasoning engine), it will automatically update the existing
+    registration instead.
+
+    Args:
+        agent_engine_id: Agent engine resource name (e.g., projects/.../reasoningEngines/...)
+        gemini_enterprise_app_id: Full Gemini Enterprise app resource name
+            (e.g., projects/{project_number}/locations/{location}/collections/{collection}/engines/{engine_id})
+        display_name: Display name for the agent in Gemini Enterprise
+        description: Description of the agent
+        tool_description: Description of what the tool does
+        project_id: Optional GCP project ID for billing (extracted from agent_engine_id if not provided)
+        authorization_id: Optional OAuth authorization ID
+            (e.g., projects/{project_number}/locations/global/authorizations/{auth_id})
+
+    Returns:
+        API response as dictionary
+
+    Raises:
+        requests.HTTPError: If the API request fails
+        ValueError: If gemini_enterprise_app_id format is invalid
+    """
+    # Parse Gemini Enterprise app resource name
+    # Format: projects/{project_number}/locations/{location}/collections/{collection}/engines/{engine_id}
+    parts = gemini_enterprise_app_id.split("/")
+    if (
+        len(parts) != 8
+        or parts[0] != "projects"
+        or parts[2] != "locations"
+        or parts[4] != "collections"
+        or parts[6] != "engines"
+    ):
+        raise ValueError(
+            f"Invalid GEMINI_ENTERPRISE_APP_ID format. Expected: "
+            f"projects/{{project_number}}/locations/{{location}}/collections/{{collection}}/engines/{{engine_id}}, "
+            f"got: {gemini_enterprise_app_id}"
+        )
+
+    project_number = parts[1]
+    as_location = parts[3]
+    collection = parts[5]
+    engine_id = parts[7]
+
+    # Use project from agent engine if not explicitly provided (for billing header)
+    if not project_id:
+        # Extract from agent_engine_id: projects/{project}/locations/{location}/reasoningEngines/{id}
+        agent_parts = agent_engine_id.split("/")
+        if len(agent_parts) > 1 and agent_parts[0] == "projects":
+            project_id = agent_parts[1]
+        else:
+            # Fallback to the project number from the Gemini Enterprise App ID.
+            project_id = project_number
+
+    # Get access token
+    access_token = get_access_token()
+
+    # Build API endpoint
+    url = (
+        f"https://discoveryengine.googleapis.com/v1alpha/projects/{project_number}/"
+        f"locations/{as_location}/collections/{collection}/engines/{engine_id}/"
+        "assistants/default_assistant/agents"
+    )
+
+    # Request headers
+    headers = {
+        "Authorization": f"Bearer {access_token}",
+        "Content-Type": "application/json",
+        "x-goog-user-project": project_id,
+    }
+
+    # Request body
+    adk_agent_definition: dict = {
+        "tool_settings": {"tool_description": tool_description},
+        "provisioned_reasoning_engine": {"reasoningEngine": agent_engine_id},
+    }
+
+    # Add OAuth authorization if provided
+    if authorization_id:
+        adk_agent_definition["authorizations"] = [authorization_id]
+
+    payload = {
+        "displayName": display_name,
+        "description": description,
+        "icon": {
+            "uri": "https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/smart_toy/default/24px.svg"
+        },
+        "adk_agent_definition": adk_agent_definition,
+    }
+
+    print("Registering agent to Gemini Enterprise...")
+    print(f"  Agent Engine: {agent_engine_id}")
+    print(f"  Gemini Enterprise App: {gemini_enterprise_app_id}")
+    print(f"  Display Name: {display_name}")
+    print(f"  API Endpoint: {url}")
+
+    try:
+        # Try to create a new registration first
+        response = requests.post(url, headers=headers, json=payload, timeout=30)
+        response.raise_for_status()
+
+        result = response.json()
+        print("\n✅ Successfully registered agent to Gemini Enterprise!")
+        print(f"   Agent Name: {result.get('name', 'N/A')}")
+        return result
+
+    except requests.exceptions.HTTPError as http_err:
+        # Check if the error is because the agent already exists
+        if response.status_code in (400, 409):
+            try:
+                error_data = response.json()
+                error_message = error_data.get("error", {}).get("message", "")
+
+                # Check if error indicates the agent already exists
+                if (
+                    "already exists" in error_message.lower()
+                    or "duplicate" in error_message.lower()
+                ):
+                    print(
+                        "\n⚠️  Agent already registered. Updating existing registration..."
+                    )
+
+                    # For update, we need to use the specific agent resource name
+                    # The agent name should be in the error or we can construct it
+                    # Format: {url}/{agent_id} but we need to find existing agent first
+
+                    # List existing agents to find the one for this reasoning engine
+                    list_response = requests.get(url, headers=headers, timeout=30)
+                    list_response.raise_for_status()
+                    agents_list = list_response.json().get("agents", [])
+
+                    # Find the agent that matches our reasoning engine
+                    existing_agent = None
+                    for agent in agents_list:
+                        re_name = (
+                            agent.get("adk_agent_definition", {})
+                            .get("provisioned_reasoning_engine", {})
+                            .get("reasoningEngine", "")
+                        )
+                        if re_name == agent_engine_id:
+                            existing_agent = agent
+                            break
+
+                    if existing_agent:
+                        agent_name = existing_agent.get("name")
+                        update_url = f"https://discoveryengine.googleapis.com/v1alpha/{agent_name}"
+
+                        print(f"  Updating agent: {agent_name}")
+
+                        # PATCH request to update
+                        update_response = requests.patch(
+                            update_url, headers=headers, json=payload, timeout=30
+                        )
+                        update_response.raise_for_status()
+
+                        result = update_response.json()
+                        print(
+                            "\n✅ Successfully updated agent registration in Gemini Enterprise!"
+                        )
+                        print(f"   Agent Name: {result.get('name', 'N/A')}")
+                        return result
+                    else:
+                        print(
+                            "\n❌ Could not find existing agent to update",
+                            file=sys.stderr,
+                        )
+                        raise
+            except (ValueError, KeyError):
+                # Failed to parse error response, raise original error
+                pass
+
+        # If not an "already exists" error, or update failed, raise the original error
+        print(f"\n❌ HTTP error occurred: {http_err}", file=sys.stderr)
+        print(f"   Response: {response.text}", file=sys.stderr)
+        raise
+    except requests.exceptions.RequestException as req_err:
+        print(f"\n❌ Request error occurred: {req_err}", file=sys.stderr)
+        raise
+
+
+def main() -> None:
+    """Main entry point for CLI."""
+    parser = argparse.ArgumentParser(
+        description="Register an Agent Engine to Gemini Enterprise"
+    )
+    parser.add_argument(
+        "--agent-engine-id",
+        help="Agent Engine resource name (e.g., projects/.../reasoningEngines/...). "
+        "If not provided, reads from deployment_metadata.json",
+    )
+    parser.add_argument(
+        "--metadata-file",
+        default="deployment_metadata.json",
+        help="Path to deployment metadata file (default: deployment_metadata.json)",
+    )
+    parser.add_argument(
+        "--gemini-enterprise-app-id",
+        help="Gemini Enterprise app full resource name "
+        "(e.g., projects/{project_number}/locations/{location}/collections/{collection}/engines/{engine_id}). "
+        "Can also be set via GEMINI_ENTERPRISE_APP_ID env var",
+    )
+    parser.add_argument(
+        "--display-name",
+        help="Display name for the agent. Can also be set via GEMINI_DISPLAY_NAME env var",
+    )
+    parser.add_argument(
+        "--description",
+        help="Description of the agent. Can also be set via GEMINI_DESCRIPTION env var",
+    )
+    parser.add_argument(
+        "--tool-description",
+        help="Description of what the tool does. Can also be set via GEMINI_TOOL_DESCRIPTION env var",
+    )
+    parser.add_argument(
+        "--project-id",
+        help="GCP project ID (extracted from agent-engine-id if not provided). "
+        "Can also be set via GOOGLE_CLOUD_PROJECT env var",
+    )
+    parser.add_argument(
+        "--authorization-id",
+        help="OAuth authorization resource name "
+        "(e.g., projects/{project_number}/locations/global/authorizations/{auth_id}). "
+        "Can also be set via GEMINI_AUTHORIZATION_ID env var",
+    )
+
+    args = parser.parse_args()
+
+    # Get agent engine ID
+    try:
+        agent_engine_id = get_agent_engine_id(args.agent_engine_id, args.metadata_file)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Auto-detect display_name and description from Agent Engine
+    auto_display_name, auto_description = get_agent_engine_metadata(agent_engine_id)
+
+    gemini_enterprise_app_id = args.gemini_enterprise_app_id or os.getenv(
+        "GEMINI_ENTERPRISE_APP_ID"
+    )
+    if not gemini_enterprise_app_id:
+        print(
+            "Error: --gemini-enterprise-app-id or GEMINI_ENTERPRISE_APP_ID env var required",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    display_name = (
+        args.display_name
+        or os.getenv("GEMINI_DISPLAY_NAME")
+        or auto_display_name
+        or "My Agent"
+    )
+    description = (
+        args.description
+        or os.getenv("GEMINI_DESCRIPTION")
+        or auto_description
+        or "AI Agent"
+    )
+    tool_description = (
+        args.tool_description or os.getenv("GEMINI_TOOL_DESCRIPTION") or description
+    )
+    project_id = args.project_id or os.getenv("GOOGLE_CLOUD_PROJECT")
+    authorization_id = args.authorization_id or os.getenv("GEMINI_AUTHORIZATION_ID")
+
+    try:
+        register_agent(
+            agent_engine_id=agent_engine_id,
+            gemini_enterprise_app_id=gemini_enterprise_app_id,
+            display_name=display_name,
+            description=description,
+            tool_description=tool_description,
+            project_id=project_id,
+            authorization_id=authorization_id,
+        )
+    except Exception as e:
+        print(f"Error during registration: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

agent_starter_pack/data_ingestion/data_ingestion_pipeline/submit_pipeline.py

@@ -17,6 +17,7 @@ import logging
 import os
 import sys
 
+import backoff
 from data_ingestion_pipeline.pipeline import pipeline
 from google.cloud import aiplatform
 from kfp import compiler
@@ -136,6 +137,22 @@ def parse_args() -> argparse.Namespace:
     return parsed_args
 
 
+@backoff.on_exception(
+    backoff.expo,
+    Exception,
+    max_tries=3,
+    max_time=3600,
+    on_backoff=lambda details: logging.warning(
+        f"Pipeline attempt {details['tries']} failed, retrying in {details['wait']:.1f}s..."
+    ),
+)
+def submit_and_wait_pipeline(pipeline_job_params: dict, service_account: str) -> None:
+    """Submit pipeline job and wait for completion with retry logic."""
+    job = aiplatform.PipelineJob(**pipeline_job_params)
+    job.submit(service_account=service_account)
+    job.wait()
+
+
 if __name__ == "__main__":
     args = parse_args()
 
@@ -182,17 +199,14 @@ if __name__ == "__main__":
     )
 {%- endif %}
 
-    # Create pipeline job instance
-    job = aiplatform.PipelineJob(**pipeline_job_params)
-
     if not args.schedule_only:
         logging.info("Running pipeline and waiting for completion...")
-        job.submit(service_account=args.service_account)
-        job.wait()
+        submit_and_wait_pipeline(pipeline_job_params, args.service_account)
         logging.info("Pipeline completed!")
 
     if args.cron_schedule and args.schedule_only:
-        # No need to create new job instance since we already have one with the same params
+        # Create pipeline job instance for scheduling
+        job = aiplatform.PipelineJob(**pipeline_job_params)
         pipeline_job_schedule = aiplatform.PipelineJobSchedule(
             pipeline_job=job,
             display_name=f"{args.pipeline_name} Weekly Ingestion Job",

agent_starter_pack/data_ingestion/pyproject.toml

@@ -5,6 +5,7 @@ description = "Data ingestion pipeline for RAG retriever"
 readme = "README.md"
 requires-python = ">=3.9, <=3.13"
 dependencies = [
+    "backoff>=2.2.0",
     "google-cloud-aiplatform>=1.80.0",
     "google-cloud-pipeline-components>=2.19.0",
     "kfp>=1.4.0",