agent-starter-pack 0.9.1__tar.gz → 0.10.0__tar.gz

agent_starter_pack-0.10.0/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(uv run:*)",
+      "Bash(git add:*)",
+      "Bash(gh run view:*)",
+      "Bash(GOOGLE_CLOUD_PROJECT=asp-starter-dev uv run pytest tests/cicd/test_pipeline_parity.py -v -s --tb=short)",
+      "Bash(set -a)",
+      "Bash(. tests/cicd/.env)",
+      "Bash(set +a)",
+      "Bash(bash:*)"
+    ],
+    "deny": []
+  }
+}

agent_starter_pack-0.10.0/.cloudbuild/ci/test_makefile.yaml

@@ -0,0 +1,36 @@
+# 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.
+
+steps:
+  # Sync dependencies
+  - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"
+    id: install-dependencies
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        uv sync --locked
+
+  # Run unit tests using pytest
+  - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"
+    id: test-templated-agents
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        uv run pytest tests/integration/test_makefile_usability.py
+
+logsBucket: gs://${PROJECT_ID}-logs-data/build-logs
+options:
+  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

agent_starter_pack-0.10.0/.cloudbuild/ci/test_pipeline_parity.yaml

@@ -0,0 +1,37 @@
+# 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.
+
+steps:
+  # Sync dependencies
+  - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"
+    id: install-dependencies
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        uv sync --dev --locked
+
+  # Run pipeline parity tests
+  - name: "europe-west4-docker.pkg.dev/production-ai-template/starter-pack/e2e-tests"
+    id: pipeline-parity-tests
+    entrypoint: /bin/bash
+    args:
+      - "-c"
+      - |
+        uv run pytest tests/integration/test_pipeline_parity.py -v
+
+
+logsBucket: gs://${PROJECT_ID}-logs-data/build-logs
+options:
+  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

{agent_starter_pack-0.9.1 → agent_starter_pack-0.10.0}/.cloudbuild/terraform/build_triggers.tf

@@ -46,6 +46,16 @@ locals {
     ".cloudbuild/**",
   ]
 
+  makefile_usability_included_files = [
+    "src/cli/**",
+    "src/base_template/**",
+    "src/deployment_targets/**",
+    "tests/integration/test_makefile_usability.py",
+    "pyproject.toml",
+    "uv.lock",
+    ".cloudbuild/**",
+  ]
+
   # Define a local variable for agent/deployment combinations
   agent_testing_combinations = [
     {
@@ -88,6 +98,10 @@ locals {
       name  = "adk_base-cloud_run-alloydb"
       value = "adk_base,cloud_run,--session-type,alloydb"
     },
+    {
+      name  = "adk_base-cloud_run-agent_engine"
+      value = "adk_base,cloud_run,--session-type,agent_engine"
+    },
   ]
 
 agent_testing_included_files = { for combo in local.agent_testing_combinations :
@@ -106,6 +120,18 @@ agent_testing_included_files = { for combo in local.agent_testing_combinations :
     ]
   }
   e2e_agent_deployment_combinations = [
+    {
+      name  = "adk_base-agent_engine-github"
+      value = "adk_base,agent_engine,--cicd-runner,github_actions"
+    },
+    {
+      name  = "adk_base-cloud_run-github"
+      value = "adk_base,cloud_run,--cicd-runner,github_actions"
+    },
+    {
+      name = "agentic_rag-agent_engine-vertex_ai_search-github"
+      value = "agentic_rag,agent_engine,--include-data-ingestion,--datastore,vertex_ai_search,--cicd-runner,github_actions"
+    },
     {
       name  = "adk_base-agent_engine"
       value = "adk_base,agent_engine"
@@ -141,7 +167,12 @@ agent_testing_included_files = { for combo in local.agent_testing_combinations :
       combo.name => replace(replace(combo.name, "_", "-"), ".", "-")
     }
 
-  e2e_agent_deployment_included_files = { for combo in local.agent_testing_combinations :
+  # Create safe trigger names for e2e deployment combinations
+  e2e_trigger_name_safe = { for combo in local.e2e_agent_deployment_combinations :
+      combo.name => replace(replace(combo.name, "_", "-"), ".", "-")
+    }
+
+  e2e_agent_deployment_included_files = { for combo in local.e2e_agent_deployment_combinations :
     combo.name => combo.name == "adk_base-cloud_run-alloydb" ? [
       "src/deployment_targets/cloud_run/**",
       "pyproject.toml",
@@ -294,7 +325,7 @@ resource "google_cloudbuild_trigger" "pr_templated_agents_test" {
 resource "google_cloudbuild_trigger" "main_e2e_deployment_test" {
   for_each = { for combo in local.e2e_agent_deployment_combinations : combo.name => combo }
 
-  name            = "e2e-deploy-${local.trigger_name_safe[each.key]}"
+  name            = "e2e-deploy-${local.e2e_trigger_name_safe[each.key]}"
   project         = var.cicd_runner_project_id
   location        = var.region
   description     = "Trigger for E2E deployment tests on main branch: ${each.value.name}"
@@ -341,3 +372,55 @@ resource "google_cloudbuild_trigger" "pr_test_remote_template" {
   ignored_files      = local.common_ignored_files
   include_build_logs = "INCLUDE_BUILD_LOGS_WITH_STATUS"
 }
+
+# g. Create Makefile usability Test trigger for PR requests
+resource "google_cloudbuild_trigger" "pr_test_makefile" {
+  name            = "pr-test-makefile"
+  project         = var.cicd_runner_project_id
+  location        = var.region
+  description     = "Trigger for PR checks on Makefile usability"
+  service_account = resource.google_service_account.cicd_runner_sa.id
+
+  repository_event_config {
+    repository = local.repository_path
+    pull_request {
+      branch          = "main"
+      comment_control = "COMMENTS_ENABLED_FOR_EXTERNAL_CONTRIBUTORS_ONLY"
+    }
+  }
+
+  filename           = ".cloudbuild/ci/test_makefile.yaml"
+  included_files     = local.makefile_usability_included_files
+  ignored_files      = local.common_ignored_files
+  include_build_logs = "INCLUDE_BUILD_LOGS_WITH_STATUS"
+}
+
+# h. Create Pipeline Parity Test trigger for PR requests
+resource "google_cloudbuild_trigger" "pr_test_pipeline_parity" {
+  name            = "pr-test-pipeline-parity"
+  project         = var.cicd_runner_project_id
+  location        = var.region
+  description     = "Trigger for PR checks on pipeline parity between GitHub Actions and Cloud Build"
+  service_account = resource.google_service_account.cicd_runner_sa.id
+
+  repository_event_config {
+    repository = local.repository_path
+    pull_request {
+      branch          = "main"
+      comment_control = "COMMENTS_ENABLED_FOR_EXTERNAL_CONTRIBUTORS_ONLY"
+    }
+  }
+
+  filename       = ".cloudbuild/ci/test_pipeline_parity.yaml"
+  included_files = [
+    "tests/integration/test_pipeline_parity.py",
+    "src/cli/**",
+    ".cloudbuild/**",
+    "src/base_template/**/.github/**",
+    "src/base_template/**/.cloudbuild/**",
+    "pyproject.toml",
+    "uv.lock",
+  ]
+  ignored_files      = local.common_ignored_files
+  include_build_logs = "INCLUDE_BUILD_LOGS_WITH_STATUS"
+}

{agent_starter_pack-0.9.1 → agent_starter_pack-0.10.0}/.gitignore

@@ -199,3 +199,4 @@ cleanup_e2e_projects.sh
 .cloudbuild/terraform/vars/env.tfvars
 docs/.vitepress/cache
 tests/cicd/delete_gcp_resources.sh
+tests/cicd/delete_agent_engines.py

{agent_starter_pack-0.9.1 → agent_starter_pack-0.10.0}/Makefile

@@ -5,7 +5,7 @@ test-templated-agents:
 	uv run pytest tests/integration/test_templated_patterns.py
 
 test-e2e:
-	set -a && . tests/cicd/.env && set +a && uv run pytest tests/cicd/test_e2e_deployment.py
+	set -a && . tests/cicd/.env && set +a && uv run pytest tests/cicd/test_e2e_deployment.py -v
 
 generate-lock:
 	uv run src/utils/generate_locks.py

{agent_starter_pack-0.9.1 → agent_starter_pack-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-starter-pack
-Version: 0.9.1
+Version: 0.10.0
 Summary: CLI to bootstrap production-ready Google Cloud GenAI agent projects from templates.
 Author-email: Google LLC <agent-starter-pack@google.com>
 License: Apache-2.0
@@ -16,11 +16,9 @@ Provides-Extra: jupyter
 Requires-Dist: ipykernel>=6.29.5; extra == 'jupyter'
 Requires-Dist: jupyter; extra == 'jupyter'
 Provides-Extra: lint
-Requires-Dist: codespell~=2.2.0; extra == 'lint'
-Requires-Dist: mypy~=1.15.0; extra == 'lint'
-Requires-Dist: ruff>=0.4.6; extra == 'lint'
-Requires-Dist: types-pyyaml~=6.0.12.20240917; extra == 'lint'
-Requires-Dist: types-requests~=2.32.0.20240914; extra == 'lint'
+Requires-Dist: codespell; extra == 'lint'
+Requires-Dist: mypy; extra == 'lint'
+Requires-Dist: ruff; extra == 'lint'
 Description-Content-Type: text/markdown
 
 # 🚀 Agent Starter Pack
@@ -101,7 +99,7 @@ Looking to explore more ADK examples? Check out the [ADK Samples Repository](htt
 #### Extra Features
 
 The `agent-starter-pack` offers two key features to accelerate and simplify the development of your agent:
-- **🔄 [CI/CD Automation (Experimental)](https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd)** - One command to set up a complete GitHub + Cloud Build pipeline for all environments
+- **🔄 [CI/CD Automation](https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd)** - A single command to set up a complete CI/CD pipeline for all environments, supporting both **Google Cloud Build** and **GitHub Actions**.
 - **📥 [Data Pipeline for RAG with Terraform/CI-CD](https://googlecloudplatform.github.io/agent-starter-pack/guide/data-ingestion)** - Seamlessly integrate a data pipeline to process embeddings for RAG into your agent system. Supporting [Vertex AI Search](https://cloud.google.com/generative-ai-app-builder/docs/enterprise-search-introduction) and [Vector Search](https://cloud.google.com/vertex-ai/docs/vector-search/overview).
 - **[Remote Templates](docs/guide/remote-templating.md)**: Create and share your own agent starter packs templates from any Git repository.
 - **🤖 Gemini CLI Integration** - Use the [Gemini CLI](https://github.com/google-gemini/gemini-cli) and the included `GEMINI.md` context file to ask questions about your template, agent architecture, and the path to production. Get instant guidance and code examples directly in your terminal.

{agent_starter_pack-0.9.1 → agent_starter_pack-0.10.0}/README.md

@@ -76,7 +76,7 @@ Looking to explore more ADK examples? Check out the [ADK Samples Repository](htt
 #### Extra Features
 
 The `agent-starter-pack` offers two key features to accelerate and simplify the development of your agent:
-- **🔄 [CI/CD Automation (Experimental)](https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd)** - One command to set up a complete GitHub + Cloud Build pipeline for all environments
+- **🔄 [CI/CD Automation](https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd)** - A single command to set up a complete CI/CD pipeline for all environments, supporting both **Google Cloud Build** and **GitHub Actions**.
 - **📥 [Data Pipeline for RAG with Terraform/CI-CD](https://googlecloudplatform.github.io/agent-starter-pack/guide/data-ingestion)** - Seamlessly integrate a data pipeline to process embeddings for RAG into your agent system. Supporting [Vertex AI Search](https://cloud.google.com/generative-ai-app-builder/docs/enterprise-search-introduction) and [Vector Search](https://cloud.google.com/vertex-ai/docs/vector-search/overview).
 - **[Remote Templates](docs/guide/remote-templating.md)**: Create and share your own agent starter packs templates from any Git repository.
 - **🤖 Gemini CLI Integration** - Use the [Gemini CLI](https://github.com/google-gemini/gemini-cli) and the included `GEMINI.md` context file to ask questions about your template, agent architecture, and the path to production. Get instant guidance and code examples directly in your terminal.

{agent_starter_pack-0.9.1 → agent_starter_pack-0.10.0}/agents/adk_base/.template/templateconfig.yaml

@@ -18,7 +18,7 @@ settings:
   requires_data_ingestion: false
   requires_session: true
   deployment_targets: ["agent_engine", "cloud_run"]
-  extra_dependencies: ["google-adk~=1.6.0"]
+  extra_dependencies: ["google-adk~=1.8.0"]
   tags: ["adk"]
   frontend_type: "None"
     

{agent_starter_pack-0.9.1 → agent_starter_pack-0.10.0}/agents/adk_gemini_fullstack/.template/templateconfig.yaml

@@ -18,7 +18,7 @@ settings:
   requires_data_ingestion: false
   requires_session: true
   deployment_targets: ["agent_engine", "cloud_run"]
-  extra_dependencies: ["google-adk~=1.6.0"]
+  extra_dependencies: ["google-adk~=1.8.0"]
   tags: ["adk"]
   frontend_type: "adk_gemini_fullstack"
   commands:

{agent_starter_pack-0.9.1 → agent_starter_pack-0.10.0}/agents/agentic_rag/.template/templateconfig.yaml

@@ -19,7 +19,7 @@ settings:
   requires_session: true
   deployment_targets: ["agent_engine", "cloud_run"]
   extra_dependencies: [
-    "google-adk~=1.6.0",
+    "google-adk~=1.8.0",
     "langchain-google-vertexai~=2.0.7",
     "langchain~=0.3.24",
     "langchain-core~=0.3.55",

{agent_starter_pack-0.9.1 → agent_starter_pack-0.10.0}/agents/agentic_rag/README.md

@@ -19,5 +19,5 @@ The agent implements the following architecture:
 - **Automated Data Ingestion Pipeline:** Automates the process of ingesting data from input sources.
 - **Custom Embeddings:** Generates embeddings using Vertex AI Embeddings and incorporates them into your data for enhanced semantic search.
 - **Terraform Deployment:** Ingestion pipeline is instantiated with Terraform alongside the rest of the infrastructure of the starter pack.
-- **Cloud Build Integration:** Deployment of ingestion pipelines is added to the CD pipelines of the starter pack.
+- **CI/CD Integration:** Deployment of ingestion pipelines is added to the CD pipelines of the starter pack.
 - **Customizable Code:** Easily adapt and customize the code to fit your specific application needs and data sources.

{agent_starter_pack-0.9.1 → agent_starter_pack-0.10.0}/agents/live_api/tests/integration/test_server_e2e.py

@@ -66,6 +66,7 @@ def start_server() -> subprocess.Popen[str]:
         text=True,
         bufsize=1,
         env=env,
+        encoding="utf-8",
     )
 
     # Start threads to log stdout and stderr in real-time
@@ -107,7 +108,12 @@ def server_fixture(request: Any) -> Iterator[subprocess.Popen[str]]:
     def stop_server() -> None:
         logger.info("Stopping server process")
         server_process.terminate()
-        server_process.wait()
+        try:
+            server_process.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            logger.warning("Server process did not terminate, killing it")
+            server_process.kill()
+            server_process.wait()
         logger.info("Server process stopped")
 
     request.addfinalizer(stop_server)

{agent_starter_pack-0.9.1 → agent_starter_pack-0.10.0}/docs/agents/overview.md

@@ -52,7 +52,7 @@ Built on the ADK, this template implements [Retrieval-Augmented Generation (RAG)
 *   Flexible datastore options: [Vertex AI Search](https://cloud.google.com/vertex-ai-search-and-conversation) and [Vertex AI Vector Search](https://cloud.google.com/vertex-ai/docs/vector-search/overview).
 *   Generation of custom embeddings for enhanced semantic search.
 *   Answer synthesis from retrieved context.
-*   Infrastructure deployment via Terraform and Cloud Build.
+*   Infrastructure deployment via Terraform and a choice of CI/CD runners (Google Cloud Build or GitHub Actions).
 
 ### LangGraph Base ReAct (`langgraph_base_react`)
 

{agent_starter_pack-0.9.1 → agent_starter_pack-0.10.0}/docs/cli/create.md

@@ -22,7 +22,7 @@ The following options will be prompted interactively if not provided via the com
 - `--deployment-target`, `-d`: Deployment target (`agent_engine` or `cloud_run`). Prompts if omitted.
 - `--datastore`, `-ds`: Datastore for RAG agents (`vertex_ai_search` or `vertex_ai_vector_search`). Prompted if `--include-data-ingestion` is specified, or if the selected agent (e.g., `agentic_rag`) requires data ingestion, and this option is omitted.
 - `--region`: GCP region for deployment (default: `us-central1`). Prompts for confirmation if not specified and `--auto-approve` is not used.
-- `--session-type`: Type of session storage to use (`in_memory` or `alloydb`). This is only applicable for agents that require session management and when the deployment target is `cloud_run`.
+- `--session-type`: Type of session storage to use (`in_memory`, `alloydb`, or `agent_engine`). This is only applicable for agents that require session management and when the deployment target is `cloud_run`.
 
 GCP account and project ID are detected automatically (using your active `gcloud config` settings). You will be prompted to confirm or change them unless `--auto-approve` is used.
 

agent_starter_pack-0.10.0/docs/cli/setup_cicd.md

@@ -0,0 +1,105 @@
+# `setup-cicd`
+
+The `setup-cicd` command is a powerful utility that automates the deployment of your complete CI/CD infrastructure, configuring your Google Cloud projects and GitHub repository in a single operation. It intelligently adapts to your project's configuration, supporting both **Google Cloud Build** and **GitHub Actions** as CI/CD runners.
+
+**⚡️ Quick Start Example:**
+
+Getting started is straightforward. From the root of your generated agent project, run the following command. The tool will guide you through the process.
+
+You can use the `pip` workflow for a traditional setup, or `uvx` to create a project in a single command without a permanent install.
+
+```bash [uvx]
+uvx agent-starter-pack setup-cicd
+```
+
+```bash [pip]
+agent-starter-pack setup-cicd
+```
+
+*(You will be prompted for Staging and Production project IDs)*
+
+Alternatively, you can provide the project IDs and other details directly as flags:
+
+```bash
+uvx agent-starter-pack setup-cicd \
+  --staging-project your-staging-project-id \
+  --prod-project your-prod-project-id \
+  --repository-name my-awesome-agent
+```
+
+
+**⚠️ Important Considerations:**
+
+*   **Run from Project Root:** This command must be executed from the root directory of your generated agent project (the directory containing `pyproject.toml`).
+*   **Production Use:** This command is designed to set up a production-ready CI/CD pipeline. However, for highly customized or complex production environments, you may want to review the generated Terraform configuration in `deployment/terraform` before applying.
+
+## Prerequisites
+
+1.  **Required Tools:**
+    *   **`uvx` or `agent-starter-pack`:** The command is part of the starter pack CLI.
+    *   **Terraform:** Required for infrastructure provisioning.
+    *   **`gh` CLI (GitHub CLI):** The tool uses the GitHub CLI to interact with your repository.
+        *   **Authentication:** You must be authenticated. Run `gh auth login`.
+        *   **Required Scopes:** Your GitHub token needs the **`repo`** and **`workflow`** scopes to create repositories and set up CI/CD. The tool will check for these scopes and guide you if they are missing.
+    *   **`gcloud` CLI (Google Cloud SDK):** Required for interacting with Google Cloud.
+        *   **Authentication:** You must be authenticated. Run `gcloud auth application-default login`.
+
+2.  **Google Cloud Projects:** You need at least two Google Cloud projects: one for `staging` and one for `production`. You also need a project to host the CI/CD resources (e.g., Cloud Build, Artifact Registry, Terraform state). You can specify this using `--cicd-project`. If omitted, the production project will be used for CI/CD resources.
+
+3.  **Permissions:** The user or service account running this command must have the `Owner` role on the specified Google Cloud projects. This is necessary for creating resources and assigning IAM roles.
+
+## How it Works
+
+The `setup-cicd` command performs the following steps automatically:
+
+1.  **CI/CD Runner Detection:** It inspects your project's structure to automatically detect whether you are using **Google Cloud Build** or **GitHub Actions**.
+2.  **GitHub Integration:** It prompts you to create a new private GitHub repository or connect to an existing one.
+3.  **Project ID Confirmation:** It prompts for Staging and Production project IDs if they are not provided as flags.
+4.  **Infrastructure Setup (Terraform):**
+    *   It configures and applies the Terraform scripts located in `deployment/terraform`.
+    *   **For Google Cloud Build:** It sets up a Cloud Build connection to your GitHub repository, either interactively or programmatically (if a GitHub PAT is provided).
+    *   **For GitHub Actions:** It configures Workload Identity Federation (WIF) to allow GitHub Actions to securely authenticate with Google Cloud without service account keys. It also creates the necessary secrets and variables in your GitHub repository.
+    *   By default, it sets up remote Terraform state management using a Google Cloud Storage (GCS) bucket. Use `--local-state` to opt-out.
+5.  **Resource Deployment:** It runs `terraform apply` to create all the necessary resources in your Google Cloud projects.
+6.  **Local Git Setup:** It initializes a Git repository locally (if needed) and adds your GitHub repository as the `origin` remote.
+
+## Running the Command
+
+```bash
+uvx agent-starter-pack setup-cicd \
+    [--staging-project <YOUR_STAGING_PROJECT_ID>] \
+    [--prod-project <YOUR_PROD_PROJECT_ID>] \
+    [--cicd-project <YOUR_CICD_PROJECT_ID>] \
+    [--dev-project <YOUR_DEV_PROJECT_ID>] \
+    [--region <GCP_REGION>] \
+    [--repository-name <GITHUB_REPO_NAME>] \
+    [--repository-owner <GITHUB_USERNAME_OR_ORG>] \
+    [--local-state] \
+    [--auto-approve] \
+    [--debug]
+```
+
+**Key Options:**
+
+*   `--staging-project`, `--prod-project`: **Required Information.** Your Google Cloud project IDs for staging and production environments. The command will prompt for these if the flags are omitted.
+*   `--cicd-project`: (Optional) Project ID for hosting CI/CD resources. If omitted, defaults to the production project ID.
+*   `--dev-project`: (Optional) Project ID for a dedicated development environment.
+*   `--region`: (Optional) GCP region for resources (default: `us-central1`).
+*   `--repository-name`, `--repository-owner`: (Optional) Details for your GitHub repository. If omitted, you'll be prompted.
+*   `--local-state`: (Optional) Use local files for Terraform state instead of the default GCS backend.
+*   `--auto-approve`: (Optional) Skip all interactive prompts.
+*   `--debug`: (Optional) Enable verbose logging for troubleshooting.
+
+*(For advanced programmatic use with Google Cloud Build, see options like `--github-pat`, `--github-app-installation-id`, and `--host-connection-name` by running `uvx agent-starter-pack setup-cicd --help`)*
+
+## After Running the Command
+
+To trigger your new CI/CD pipeline, you need to commit and push your code:
+
+```bash
+git add .
+git commit -m "Initial commit of agent starter pack"
+git push -u origin main
+```
+
+After pushing, you can verify the created resources and running pipelines in your GitHub repository and Google Cloud projects.

agent_starter_pack-0.10.0/docs/guide/deployment.md

@@ -0,0 +1,117 @@
+# Deployment
+
+This starter pack uses a robust, production-ready deployment strategy that combines **Terraform** for infrastructure as code and a CI/CD pipeline for automated builds, tests, and deployments. You can choose between **Google Cloud Build** and **GitHub Actions** as your CI/CD runner.
+
+The recommended way to deploy your agent is with the `agent-starter-pack setup-cicd` command, which automates the entire process.
+
+## Deployment Workflow
+
+The CI/CD pipeline is designed with best practices for deploying applications safely and reliably.
+
+![Deployment Workflow](https://storage.googleapis.com/github-repo/generative-ai/sample-apps/e2e-gen-ai-app-starter-pack/deployment_workflow.png)
+
+**Description:**
+
+1. **CI Pipeline** (e.g., `.github/workflows/pr_checks.yaml` or `.cloudbuild/pr_checks.yaml`):
+   - Triggered on pull request creation/update.
+   - Runs unit and integration tests to ensure code quality.
+
+2. **Staging CD Pipeline** (e.g., `.github/workflows/staging.yaml` or `.cloudbuild/staging.yaml`):
+   - Triggered on merge to the `main` branch.
+   - Builds and pushes the application container to Artifact Registry.
+   - Deploys the new version to the **staging environment**.
+   - Performs automated load testing against the staging environment.
+
+3. **Production Deployment** (e.g., `.github/workflows/deploy-to-prod.yaml` or `.cloudbuild/deploy-to-prod.yaml`):
+   - Triggered after a successful staging deployment.
+   - Requires **manual approval** before proceeding to production.
+   - Deploys the same container image that was tested in staging to the **production environment**.
+
+## Development Environment Deployment
+
+If you want to deploy a standalone development environment without setting up the full CI/CD pipeline, you can use the `make setup-dev-env` command.
+
+1. **Set your Dev Project:**
+   ```bash
+   gcloud config set project <your-dev-project-id>
+   ```
+
+2. **Deploy Dev Infrastructure:**
+   This command runs the Terraform configuration in `deployment/terraform/dev` to provision a development environment.
+   ```bash
+   make setup-dev-env
+   ```
+
+3. **Deploy the Application:**
+   Once the infrastructure is ready, deploy your agent to the dev environment.
+   ```bash
+   make backend
+   ```
+   
+## Automated Deployment with `setup-cicd`
+
+For a streamlined, one-command deployment of the entire CI/CD pipeline and infrastructure, use the `setup-cicd` command from the root of your generated project.
+
+```bash
+uvx agent-starter-pack setup-cicd
+```
+
+This command handles all the necessary steps:
+- **Infrastructure Provisioning:** Uses Terraform to create and configure the necessary resources in your staging and production Google Cloud projects.
+- **CI/CD Configuration:** Sets up a complete CI/CD pipeline with your chosen runner (Google Cloud Build or GitHub Actions), including triggers for pull requests and merges to the main branch.
+- **Repository Connection:** Connects your GitHub repository to the CI/CD provider.
+
+For a complete guide on the command and its options, see the [**`setup-cicd` CLI Reference**](../cli/setup_cicd.html).
+
+## Required Variables
+
+The deployment uses Terraform variables that need to be configured for your environment. These are defined in `src/base_template/deployment/terraform/variables.tf`:
+
+### Core Configuration
+- **`project_name`**: Base name for resource naming (default: auto-generated from cookiecutter)
+- **`prod_project_id`**: Google Cloud Project ID for production deployment
+- **`staging_project_id`**: Google Cloud Project ID for staging deployment
+- **`cicd_runner_project_id`**: Google Cloud Project ID where CI/CD pipelines execute
+- **`region`**: Google Cloud region for resources (default: `us-central1`)
+
+### Repository Connection
+- **`repository_name`**: Name of your GitHub repository
+- **`repository_owner`**: GitHub username or organization name
+- **`host_connection_name`**: Name for Cloud Build connection (default: auto-generated)
+
+### Service Account Permissions
+- **`cloud_run_app_roles`** / **`agentengine_sa_roles`**: Roles for the application service account
+- **`cicd_roles`**: Roles for CI/CD runner service account
+- **`cicd_sa_deployment_required_roles`**: Deployment roles for staging/prod projects
+
+### CI/CD Provider Specific
+For **Cloud Build**:
+- **`github_app_installation_id`**: GitHub App Installation ID
+- **`github_pat`** / **`github_pat_secret_id`**: GitHub Personal Access Token
+- **`create_cb_connection`**: Whether to create new Cloud Build connection
+
+For **GitHub Actions**:
+- **`create_repository`**: Whether the repository already exists
+
+### Data Ingestion (Optional)
+If data ingestion is enabled:
+- **`pipeline_cron_schedule`**: Cron schedule for automated ingestion (default: weekly)
+- **`pipelines_roles`**: Roles for Vertex AI Pipelines service account
+
+### Vector Search Configuration (Optional)
+If using Vertex AI Vector Search:
+- **`vector_search_embedding_size`**: Embedding dimensions (default: 768)
+- **`vector_search_approximate_neighbors_count`**: Neighbors to return (default: 150)
+- **`vector_search_min/max_replica_count`**: Scaling configuration
+- **`vector_search_shard_size`**: Shard size (default: SHARD_SIZE_SMALL)
+- **`vector_search_machine_type`**: Instance type (default: e2-standard-2)
+
+### Logging Configuration
+- **`telemetry_logs_filter`**: Log filter for telemetry data
+- **`feedback_logs_filter`**: Log filter for feedback data
+
+### End-to-end Demo video
+
+<a href="https://storage.googleapis.com/github-repo/generative-ai/sample-apps/e2e-gen-ai-app-starter-pack/template_deployment_demo.mp4">
+  <img src="https://storage.googleapis.com/github-repo/generative-ai/sample-apps/e2e-gen-ai-app-starter-pack/preview_video.png" alt="Watch the video" width="300"/>
+</a>