### Automated CI/CD Setup Example

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/llm.txt

This example demonstrates an automated CI/CD setup using `agent-starter-pack setup-cicd` with the `--auto-approve` flag. It requires specifying staging and production project IDs, repository name, and owner. For coding agents, it's recommended to prompt the user for these details before using `--auto-approve`.

```bash
uvx agent-starter-pack setup-cicd \
  --staging-project your-staging-project \
  --prod-project your-prod-project \
  --repository-name your-repo-name \
  --repository-owner your-username \
  --auto-approve
```

--------------------------------

### Quick Start with `pip`

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/setup_cicd.md

Use this command for a traditional setup of CI/CD infrastructure. Run from the root of your agent project.

```bash
agent-starter-pack setup-cicd
```

--------------------------------

### Install and Setup agents-cli

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/README.md

Use this command to set up the agents-cli, the next evolution of Agent Starter Pack. It is recommended for all future development.

```bash
uvx google-agents-cli setup
```

--------------------------------

### Install Dependencies and Launch Playground

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/development-guide.md

Install project dependencies and start the local interactive playground for testing.

```bash
# Install dependencies and launch the local playground
make install && make playground
```

--------------------------------

### Install dependencies and launch local playground

Source: https://context7.com/googlecloudplatform/agent-starter-pack/llms.txt

After creating a project, navigate to the project directory, install dependencies using `make install`, and launch the local playground with `make playground`.

```bash
cd my-agent && make install && make playground
```

--------------------------------

### Setup with Project IDs and Repository Name

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/setup_cicd.md

Provide staging and production project IDs, along with the repository name, directly as flags for automated CI/CD setup. This command can be executed using `uvx` or directly if installed.

```bash
uvx agent-starter-pack setup-cicd \
  --staging-project your-staging-project-id \
  --prod-project your-prod-project-id \
  --repository-name my-awesome-agent
```

--------------------------------

### Install agent-starter-pack CLI with uvx

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/llm.txt

Use uvx to run the agent-starter-pack command directly without prior installation, recommended for automation.

```bash
uvx agent-starter-pack create ...
```

--------------------------------

### Create Project After Installation

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Run this command after installing the agent-starter-pack via pipx, uv tool, or within a virtual environment.

```bash
agent-starter-pack create
```

--------------------------------

### Example Upgrade Workflow

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/upgrade.md

A step-by-step example of performing an upgrade, including checking the current version, previewing changes, applying the upgrade, and verifying the new version.

```bash
# Check current version in pyproject.toml
grep asp_version pyproject.toml
# asp_version = "0.30.0"

# Preview what would change
uvx agent-starter-pack upgrade --dry-run

# Output shows:
# Auto-updating (unchanged by you):
#   ✓ deployment/terraform/main.tf
#   ✓ .github/workflows/ci.yaml
#
# Preserving (you modified, ASP unchanged):
#   ✓ Makefile
#
# Conflicts (both changed):
#   ⚠ deployment/terraform/variables.tf

# Apply the upgrade
uvx agent-starter-pack upgrade

# Resolve any conflicts interactively
# ...

# Verify upgrade
grep asp_version pyproject.toml
# asp_version = "0.31.0"
```

--------------------------------

### Install agent-starter-pack CLI with pip

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/llm.txt

Install the agent-starter-pack command-line tool into a virtual environment using pip.

```bash
pip install agent-starter-pack
```

--------------------------------

### Setup CI/CD Pipeline and Infrastructure

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/base_templates/go/README.md

Automates the setup of the entire CI/CD pipeline and underlying infrastructure.

```bash
uvx agent-starter-pack setup-cicd
```

--------------------------------

### Install Dependencies and Run Playground

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/base_templates/go/README.md

Commands to install Go dependencies and launch the local development environment for the agent.

```bash
make install && make playground
```

--------------------------------

### Basic Upgrade Examples

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/upgrade.md

Demonstrates how to upgrade the current project or a specific project path.

```bash
# Upgrade current project
uvx agent-starter-pack upgrade

# Upgrade a specific project
uvx agent-starter-pack upgrade /path/to/project
```

--------------------------------

### Verify Installation with Version Command

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Checks the installed version of the agent-starter-pack to confirm a successful installation.

```bash
agent-starter-pack --version
```

--------------------------------

### Create Project with pip

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/development-guide.md

Use pip to create a virtual environment, install the starter pack, and then create your project.

```bash
# 1. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate

# 2. Install the package
pip install agent-starter-pack

# 3. Run the create command
agent-starter-pack create
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/CONTRIBUTING.md

Run this command once to install all necessary project dependencies.

```bash
make install
```

--------------------------------

### Virtual Environment Installation

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Installs the agent-starter-pack into an isolated Python virtual environment using pip or uv. Ensure the virtual environment is activated before installation.

```bash
# Create and activate venv
python -m venv .venv && source .venv/bin/activate # source .venv/Scripts/activate for Windows Git Bash

# Install using pip or uv
pip install agent-starter-pack
```

--------------------------------

### Check agent-starter-pack Installation

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/troubleshooting.md

Verify if the agent-starter-pack is installed and check your system's PATH environment variable.

```bash
pip list | grep agent-starter-pack
```

```bash
echo $PATH
```

--------------------------------

### Create Agent Project with uvx

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/README.md

Quickly create a new agent project using the uvx command. This is the fastest way to get started with a production-ready agent.

```bash
uvx agent-starter-pack create
```

--------------------------------

### Verify Installation with Help Command

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Runs the help command for agent-starter-pack to ensure the CLI is accessible and functioning.

```bash
agent-starter-pack --help
```

--------------------------------

### Create Go Project Instance

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/CONTRIBUTING.md

Example command to create a Go project instance using Agent Starter Pack, specifying the agent and deployment target.

```bash
uv run agent-starter-pack create mytest -a adk_go -d cloud_run -p -s -y --output-dir target
```

--------------------------------

### Install with Verbose Output

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Installs the agent-starter-pack with verbose output enabled. This can provide more detailed information to help diagnose dependency conflicts.

```bash
pip install -v agent-starter-pack
```

--------------------------------

### Explore and Run Locally

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/getting-started.md

Navigate into your new project directory and execute these commands to install dependencies and launch the local playground.

```bash
cd <your-project> && make install && make playground
```

--------------------------------

### Start Local Java Server

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/base_templates/java/src/test/java/{{cookiecutter.java_package_path}}/e2e/load_test/README.md

Execute this command to start the Java server for local load testing.

```bash
make local-backend
```

--------------------------------

### Persistent CLI Installation with uv tool

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Installs the agent-starter-pack command globally as an isolated tool using uv tool. Requires uv to be installed.

```bash
uv tool install agent-starter-pack
```

--------------------------------

### Environment File Setup

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/base_templates/typescript/README.md

Demonstrates how to create and configure the environment file for local testing, specifying either Vertex AI or Gemini API credentials.

```bash
cp .env.example .env

```

```bash
# For Vertex AI (recommended):
GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT=your-gcp-project-id
GOOGLE_CLOUD_LOCATION=global

# Or for Gemini API:
# GEMINI_API_KEY=your-api-key

```

--------------------------------

### Verify Package Installation Location

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Shows details about the installed agent-starter-pack, including its location, to help diagnose installation issues.

```bash
pip show agent-starter-pack
```

--------------------------------

### Persistent CLI Installation with pipx

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Installs the agent-starter-pack command globally as an isolated tool using pipx. Ensure pipx is installed and its bin directory is in your PATH.

```bash
# Install pipx (if needed)
python3 -m pip install --user pipx && python3 -m pipx ensurepath

# Install Agent Starter Pack
pipx install agent-starter-pack
```

--------------------------------

### Automated agent project creation example

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/llm.txt

Example of creating an agent project non-interactively using uvx, specifying the agent template, deployment target, region, and enabling auto-approval for automation.

```bash
uvx agent-starter-pack create my-automated-agent \
  -a adk \
  -d cloud_run \
  --region us-east1 \
  --auto-approve
```

--------------------------------

### Install uv with curl

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/upgrade.md

Install the uv package manager if it is not already installed. This is required for some agent-starter-pack operations.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Install and Launch Local Development

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/base_templates/typescript/README.md

Commands to install project dependencies and launch the local development environment, including the backend and frontend with ADK devtools.

```bash
make install && make playground

```

--------------------------------

### Create Python Project Instance

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/CONTRIBUTING.md

Example command to create a Python project instance using Agent Starter Pack, specifying the agent and deployment target.

```bash
uv run agent-starter-pack create mytest -a adk -d cloud_run -p -s -y --output-dir target
```

--------------------------------

### Create Project with uvx

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/development-guide.md

Use uvx to create a project in a single command without a permanent install.

```bash
# This single command downloads and runs the latest version
uvx agent-starter-pack create
```

--------------------------------

### Setup CI/CD Pipeline

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/base_templates/typescript/README.md

A CLI command to streamline the setup of the CI/CD pipeline and infrastructure. Currently supports GitHub with Google Cloud Build or GitHub Actions.

```bash
npx agent-starter-pack setup-cicd
```

--------------------------------

### Start Go Server for Local Load Testing

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/base_templates/go/e2e/load_test/README.md

Launch the Go server locally to serve traffic for load testing. Ensure the .env file is sourced.

```bash
source .env
go run . web --port 8000 api
```

--------------------------------

### Launch Local Development Playground

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/base_templates/go/README.md

Command to start the local development server, accessible via a web browser.

```bash
make playground
```

--------------------------------

### Advanced Enhancement Options

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/enhance.md

These examples demonstrate using advanced options for custom agent directories, deployment targets, and datastore configurations.

```bash
uvx agent-starter-pack enhance . --agent-directory chatbot
```

```bash
uvx agent-starter-pack enhance adk@data-science --deployment-target cloud_run
```

```bash
uvx agent-starter-pack enhance --datastore cloud_sql
```

```bash
uvx agent-starter-pack enhance --session-type cloud_sql
```

--------------------------------

### Set Up Local Agent Engine App

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/agents/adk/notebooks/adk_app_testing.ipynb

Initializes the local AgentEngineApp. Ensure all required packages are installed and the correct kernel is selected.

```python
from app.agent_engine_app import agent_engine

agent_engine.set_up()
```

--------------------------------

### Launch Playground (Bash)

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/resources/docs/adk-deploy-guide.md

Starts the local playground environment for testing agents. Access it via http://localhost:8000.

```bash
make playground
# Open http://localhost:8000 in your browser
```

--------------------------------

### Create an ADK agent using a quickstart shortcut

Source: https://context7.com/googlecloudplatform/agent-starter-pack/llms.txt

Uses a shortcut to create an ADK agent with default settings for agent_engine deployment and prototype mode, automatically approving the process.

```bash
agent-starter-pack create my-agent --adk
```

--------------------------------

### Example Workflow: Create, Develop, Extract, Share, Enhance

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/extract.md

This workflow demonstrates the complete cycle from creating a full project, developing the agent, extracting it for sharing, and then having recipients enhance it.

```bash
# 1. Create a full project
uvx agent-starter-pack create my-agent -a adk -d cloud_run

# 2. Develop your agent...
cd my-agent
# ... edit app/agent.py ...

# 3. Extract for sharing
uvx agent-starter-pack extract ../my-agent-share

# 4. Share the extracted agent (e.g., push to GitHub)
cd ../my-agent-share
git init && git add . && git commit -m "Initial agent"

# 5. Recipients can enhance with their own preferences
uvx agent-starter-pack enhance --deployment-target agent_engine
```

--------------------------------

### Set up Locust Virtual Environment

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/deployment_targets/cloud_run/python/tests/load_test/README.md

Create and activate a virtual environment for Locust and install the necessary dependencies. This ensures a clean environment for testing.

```bash
python3 -m venv .locust_env && source .locust_env/bin/activate && pip install locust==2.31.1 websockets
```

--------------------------------

### Example User Experience with Version Locking

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/remote-templates/creating-remote-templates.md

Demonstrates the user experience when creating a project from a remote template that uses version locking.

```bash
uvx agent-starter-pack create my-project -a github.com/you/your-template

# Output:
# 🔒 Remote template specifies agent-starter-pack version 0.14.1 in uv.lock
# 📦 Executing nested command: uvx agent-starter-pack==0.14.1
# [continues with locked version]
```

--------------------------------

### Upgrade Agent Starter Pack with pipx

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Upgrades the agent-starter-pack when installed via pipx.

```bash
pipx upgrade agent-starter-pack
```

--------------------------------

### Vertex AI Search Agent Setup

Source: https://context7.com/googlecloudplatform/agent-starter-pack/llms.txt

Initializes Vertex AI and sets up a search tool for an agent. Requires DATA_STORE_REGION and DATA_STORE_ID environment variables.

```python
import os
import google
import vertexai
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types
from app.retrievers import create_search_tool  # generated by agentic_rag template

credentials, 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"
vertexai.init(project=project_id, location="us-east1")

data_store_region = os.getenv("DATA_STORE_REGION", "global")
data_store_id = os.getenv("DATA_STORE_ID", "my-project-collection_documents")
data_store_path =
    f"projects/{project_id}/locations/{data_store_region}"
    f"/collections/default_collection/dataStores/{data_store_id}"

vertex_search_tool = create_search_tool(data_store_path)

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-2.0-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=(
        "You are an AI assistant. Answer questions using the provided tools. "
        "If you already know the answer you can respond directly."
    ),
    tools=[vertex_search_tool],
)

app = App(root_agent=root_agent, name="app")
```

--------------------------------

### Set up Locust Virtual Environment (Conditional SDK)

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/deployment_targets/cloud_run/python/tests/load_test/README.md

Create and activate a virtual environment for Locust, installing the core Locust package and optionally the 'a2a-sdk' if required by the project configuration.

```bash
python3 -m venv .locust_env && source .locust_env/bin/activate && pip install locust==2.31.1{%- if cookiecutter.is_a2a %} a2a-sdk~=0.3.22{%- endif %}
```

--------------------------------

### Launch Interactive Template Browser

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/remote-templates/using-remote-templates.md

Execute this command to start an interactive session for creating an agent, which includes an option to browse ADK samples.

```bash
# Launch interactive browser for ADK samples
uvx agent-starter-pack create my-agent
# (Choose to browse ADK samples when prompted)
```

--------------------------------

### Create Agent Project with uvx

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/getting-started.md

Use this command for a single-step project creation without needing to install the package globally.

```bash
# Single command - no install needed
uvx agent-starter-pack create
```

--------------------------------

### Start FastAPI Server for Local Testing

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/deployment_targets/cloud_run/python/tests/load_test/README.md

Launch the FastAPI server to serve your application locally. This is a prerequisite for running local load tests.

```bash
uv run uvicorn {{cookiecutter.agent_directory}}.fast_api_app:app --host 0.0.0.0 --port 8000 --reload
```

--------------------------------

### Run Load Tests (Bash)

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/base_templates/java/README.md

Execute load tests against the running server. Ensure the server is started first with `make local-backend`.

```bash
make load-test
```

--------------------------------

### Dockerfile for Combined Backend and Frontend

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/deploy-ui.md

This Dockerfile installs Node.js and npm, copies backend and frontend files, installs dependencies for both, and configures the container to start both the backend API and the frontend development server concurrently. Intended for development and testing only.

```dockerfile
FROM python:3.11-slim

# Install Node.js and npm
RUN apt-get update && apt-get install -y \
    nodejs \
    npm \
    curl \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir uv==0.8.13

WORKDIR /code

# Copy backend files
COPY ./pyproject.toml ./README.md ./uv.lock* ./
COPY ./app ./app

# Copy frontend files
COPY ./frontend ./frontend

# Install dependencies
RUN uv sync --frozen && npm --prefix frontend install

EXPOSE 8000 5173

# Start both backend and frontend in parallel
CMD ["sh", "-c", "ALLOW_ORIGINS='*' uv run uvicorn app.server:app --host 0.0.0.0 --port 8000 & npm --prefix frontend run dev -- --host 0.0.0.0 & wait"]
```

--------------------------------

### Setup Vertex AI Vector Search Datastore

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/agents/agentic_rag/data_ingestion/README.md

Provision the Vector Search 2.0 Collection, GCS bucket, and service account using Terraform. Requires Terraform to be installed and configured.

```bash
make setup-datastore
```

--------------------------------

### Create Agent Project with Specific Templates and Deployments

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/getting-started.md

Examples demonstrating how to create agents with specific templates (e.g., Python, Go, TypeScript) and deployment targets (e.g., Agent Engine, Cloud Run).

```bash
# Python agent with Agent Engine
agent-starter-pack create my-adk-agent -a adk -d agent_engine
```

```bash
# Go agent with Cloud Run
agent-starter-pack create my-go-agent -a adk_go -d cloud_run
```

```bash
# TypeScript agent with Cloud Run
agent-starter-pack create my-ts-agent -a adk_ts -d cloud_run
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/development-guide.md

Change into your new project directory to begin development.

```bash
cd <your-project>
```

--------------------------------

### Run agent-starter-pack setup-cicd

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/llm.txt

Use this command to automate the complete CI/CD infrastructure setup for GitHub-based deployments. It intelligently detects your CI/CD runner and configures it automatically. Ensure you meet the prerequisites, including authenticated `gh` and `gcloud` CLIs, and the `Owner` role on GCP projects.

```bash
uvx agent-starter-pack setup-cicd [OPTIONS]
```

--------------------------------

### Run agent-starter-pack setup-cicd Command

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/setup_cicd.md

Use this command to set up the CI/CD pipeline. Provide your Google Cloud project IDs and optionally specify the region, repository details, and state management preferences. The command will prompt for missing required information.

```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]
```

--------------------------------

### Project Structure Overview

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/base_templates/go/README.md

Illustrates the directory and file organization of a typical Go agent project generated by the starter pack.

```bash
agent-starter-pack/
├── main.go              # Application entry point
├── agent/
│   └── agent.go         # Agent implementation
├── e2e/
│   ├── integration/     # Integration tests
│   └── load_test/       # Load testing
├── deployment/
│   └── terraform/       # Infrastructure as Code
│   ├── k8s/             # Kubernetes manifests for GKE deployment
├── go.mod               # Go module definition
├── Dockerfile           # Container build
├── GEMINI.md            # AI-assisted development guide
└── Makefile             # Common commands
```

--------------------------------

### Install Dependencies for ADK Testing

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/agents/adk/notebooks/adk_app_testing.ipynb

Installs necessary packages for ADK testing. Uncomment lines if not using a virtual environment created by uv.

```python
# Uncomment the following lines if you're not using the virtual environment created by uv
# import sys

# sys.path.append("../")
# !pip install google-cloud-aiplatform a2a-sdk --upgrade
```

--------------------------------

### Restart Jupyter Runtime

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/agents/langgraph/notebooks/evaluating_langgraph_agent.ipynb

Restarts the current Jupyter kernel to apply newly installed packages. This is a standard procedure after installing new libraries in a Jupyter environment.

```python
import IPython

app = IPython.Application.instance()
app.kernel.do_shutdown(True)
```

--------------------------------

### PR Structure Example

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/GEMINI.md

This example shows the expected structure for a Pull Request, including a brief title and a detailed description covering summary, problem, and solution.

```markdown
Fix Cloud Build service account permission for GitHub PAT secret access
```

```markdown
## Summary
- Key change 1 (what was added/modified)
- Key change 2
- Key change 3

## Problem
Clear description of the issue, including:
- Error messages or symptoms
- Why it was failing
- Context about when/where it occurs

## Solution
Explanation of how the changes fix the problem:
- What resources/files were modified
- Why this approach was chosen
- Any dependencies or sequencing requirements
```

--------------------------------

### Project Structure Overview

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/base_templates/typescript/README.md

Illustrates the directory layout for the Agent Starter Pack project, highlighting core application code, CI/CD configurations, deployment scripts, and testing directories.

```bash
agent-starter-pack/
├── agent-directory/                 # Core application code
│   └── agent.ts         # Main agent logic with tools
├── .cloudbuild/         # CI/CD pipeline configurations for Google Cloud Build
├── deployment/          # Infrastructure and deployment scripts
{%- if cookiecutter.deployment_target == 'gke' %}
│   ├── k8s/             # Kubernetes manifests for GKE deployment
{%- endif %}
├── tests/               # Unit, integration, and load tests
│   ├── unit/            # Unit tests
│   ├── integration/     # Integration tests
│   └── load_test/       # Load tests
├── Makefile             # Makefile for common commands
├── GEMINI.md            # AI-assisted development guide
├── package.json         # Project dependencies and configuration
├── tsconfig.json        # TypeScript configuration
└── vitest.config.ts     # Vitest test configuration

```

--------------------------------

### Install Langchain Google Vertex AI and LangGraph

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/agents/langgraph/notebooks/evaluating_langgraph_agent.ipynb

Installs the necessary Python packages for using Langchain with Google Vertex AI and for building graph-based agents with LangGraph.

```python
%pip install "langchain_google_vertexai" "langgraph"
%pip install --upgrade --user --quiet "google-cloud-aiplatform[evaluation]"
```

--------------------------------

### Create an agent using an ADK samples shortcut

Source: https://context7.com/googlecloudplatform/agent-starter-pack/llms.txt

Creates an agent project using a predefined ADK sample template, such as 'data-science', fetched from the google/adk-samples repository.

```bash
agent-starter-pack create data-agent \
  --agent adk@data-science
```

--------------------------------

### Register Gemini Enterprise Agent via uvx

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/register_gemini_enterprise.md

Use `uvx` to run the `register-gemini-enterprise` command without installation. This is useful for quick execution or in environments where installation is not desired.

```bash
uvx agent-starter-pack@latest register-gemini-enterprise [OPTIONS]
```

--------------------------------

### PR Description Example

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/GEMINI.md

This example PR description provides a concise summary, outlines the problem encountered, and details the solution implemented, aiding reviewers in understanding the changes.

```markdown
## Summary
- Grant Cloud Build service account `secretmanager.secretAccessor` role
- Add proper dependency to Cloud Build v2 connection resource

## Problem
E2E tests failed when Terraform attempted to create Cloud Build v2 connections:
```
Error: could not access secret with service account:
generic::permission_denied
```

The CLI setup grants this permission via gcloud, but Terraform
configuration lacked the IAM binding.

## Solution
Added `google_secret_manager_secret_iam_member` resource to grant the
Cloud Build service account permission to access the GitHub PAT secret
before creating the connection.
```

--------------------------------

### Commit Message Example

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/GEMINI.md

An example commit message detailing the changes made, the problem it solves, and the reasoning behind the solution. It's useful for understanding the impact of a change.

```markdown
Fix Cloud Build service account permission for GitHub PAT secret access

Add IAM binding to grant Cloud Build service account the secretAccessor
role for the GitHub PAT secret. This resolves permission errors when
Terraform creates Cloud Build v2 connections in E2E tests.

The CLI setup already grants this permission via gcloud, but the
Terraform configuration was missing this binding, causing failures when
Terraform runs independently.
```

--------------------------------

### Interactive Dependency Management Prompt

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/remote-templates/using-remote-templates.md

When overriding a base template, the CLI lists required dependencies and prompts for automatic installation. Choose 'n' to skip installation and add them manually later.

```bash
? Add these dependencies automatically? [Y/n] n
```

--------------------------------

### Install ADK and Vertex AI SDKs

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/agents/adk/notebooks/evaluating_adk_agent.ipynb

Installs the necessary Python packages for Agent Development Kit (ADK) and Vertex AI's Gen AI Evaluation capabilities. Use this to set up your environment for agent evaluation.

```python
%pip install --upgrade --quiet 'google-adk'
%pip install --upgrade --quiet 'google-cloud-aiplatform[evaluation]'
```

--------------------------------

### Uninstall Agent Starter Pack with pipx

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Uninstalls the agent-starter-pack when installed via pipx.

```bash
pipx uninstall agent-starter-pack
```

--------------------------------

### Import Tutorial Libraries

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/agents/adk/notebooks/evaluating_adk_agent.ipynb

Imports essential libraries for agent development, event handling, running agents, session management, and Vertex AI evaluation.

```python
import json
import asyncio

# General
import random
import string
from typing import Any

from IPython.display import HTML, Markdown, display
from google.adk.agents import Agent

# Build agent with adk
from google.adk.events import Event
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService

# Evaluate agent
from google.cloud import aiplatform
from google.genai import types
import pandas as pd
import plotly.graph_objects as go
from vertexai.preview.evaluation import EvalTask
from vertexai.preview.evaluation.metrics import (
    PointwiseMetric,
    PointwiseMetricPromptTemplate,
    TrajectorySingleToolUse,
)
```

--------------------------------

### Create Agent Project from GitHub URL

Source: https://context7.com/googlecloudplatform/agent-starter-pack/llms.txt

Use the `agent-starter-pack create` command with the `-a` flag to specify a GitHub URL for the template. Supports full URLs, shorthand URLs, specific branches/tags, and overriding the base template.

```bash
agent-starter-pack create my-support-agent \
  -a https://github.com/my-org/customer-support-agent
```

```bash
agent-starter-pack create my-support-agent \
  -a github.com/my-org/customer-support-agent
```

```bash
agent-starter-pack create my-support-agent \
  -a "github.com/my-org/customer-support-agent@v1.0.0"
```

```bash
agent-starter-pack create my-support-agent \
  -a github.com/my-org/customer-support-agent \
  --base-template agentic_rag
```

```bash
agent-starter-pack create test-agent -a local@./customer-support-agent
```

--------------------------------

### Check Directory Permissions

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Lists the permissions of the .local/bin directory to help diagnose permission errors during installation.

```bash
ls -la ~/.local/bin
```

--------------------------------

### Create a new agent project with agent-starter-pack

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/llm.txt

Generates a new agent project directory using a specified template and configuration. Use --auto-approve to skip interactive prompts for automation.

```bash
agent-starter-pack create PROJECT_NAME [OPTIONS]
```

--------------------------------

### Uninstall Agent Starter Pack with uv tool

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Uninstalls the agent-starter-pack when installed via uv tool.

```bash
uv tool uninstall agent-starter-pack
```

--------------------------------

### Create Agent from Local Project

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/create.md

Use an existing local project directory as a template for your new agent project.

```bash
# Use your existing project
uvx agent-starter-pack create my-agent -a local@./my-project
```

--------------------------------

### Authenticate GitHub CLI

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/resources/docs/adk-deploy-guide.md

Ensure you are logged into the GitHub CLI before proceeding with CI/CD setup. Skip this if already authenticated.

```bash
gh auth login  # (skip if already authenticated)
```

--------------------------------

### Upgrade Agent Starter Pack Command Usage

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/upgrade.md

The basic usage of the upgrade command. Specify the project path if it's not the current directory.

```bash
uvx agent-starter-pack upgrade [PROJECT_PATH] [OPTIONS]
```

--------------------------------

### Create Agent Project with Data Ingestion

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/data-ingestion.md

Use the agent-starter-pack CLI to create a new agent project and enable data ingestion by specifying the datastore. This command sets up the necessary infrastructure for either Vertex AI Search or Vertex AI Vector Search.

```bash
agent-starter-pack create my-agent-project -ds vertex_ai_search
```

```bash
agent-starter-pack create my-agent-project -ds vertex_ai_vector_search
```

--------------------------------

### Set up CI/CD infrastructure for an agent project

Source: https://context7.com/googlecloudplatform/agent-starter-pack/llms.txt

The `setup-cicd` command provisions Terraform-managed environments, creates/connects a GitHub repository, and configures CI/CD triggers. It handles GitHub authentication and writes necessary Terraform configuration files. Must be run from the project root.

```bash
cd my-agent-project
uvx agent-starter-pack setup-cicd
```

```bash
agent-starter-pack setup-cicd \
  --staging-project my-staging-project \
  --prod-project    my-prod-project \
  --cicd-runner     google_cloud_build \
  --repository-name my-agent-repo \
  --github-pat      $GITHUB_PAT \
  --github-app-installation-id $GITHUB_APP_ID \
  --auto-approve
```

```bash
agent-starter-pack setup-cicd \
  --staging-project staging-proj \
  --prod-project    prod-proj \
  --cicd-runner     github_actions \
  --create-repository \
  --region          us-central1
```

```bash
agent-starter-pack setup-cicd \
  --staging-project staging-proj \
  --prod-project    prod-proj \
  --repository-owner my-github-org \
  --repository-name  existing-repo \
  --use-existing-repository
```

```bash
agent-starter-pack setup-cicd \
  --staging-project staging-proj \
  --prod-project    prod-proj \
  --local-state \
  --auto-approve
```

--------------------------------

### Register Gemini Enterprise Agent via Direct Command

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/register_gemini_enterprise.md

Execute the `register-gemini-enterprise` command directly after installation. This allows for non-interactive usage with options.

```bash
agent-starter-pack register-gemini-enterprise [OPTIONS]
```

--------------------------------

### Preview and Apply Agent Project Upgrades

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/development-guide.md

Use the `uvx agent-starter-pack upgrade` command to update your existing projects. The `--dry-run` flag previews changes without applying them. The upgrade process uses a 3-way merge to preserve customizations.

```bash
# Preview what would change
uvx agent-starter-pack upgrade --dry-run

# Apply the upgrade
uvx agent-starter-pack upgrade
```

--------------------------------

### Enhance existing project with agent-starter-pack

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/llm.txt

Adds agent-starter-pack features to an existing project in-place. It uses the same options as 'create' but modifies the current directory.

```bash
agent-starter-pack enhance [TEMPLATE_PATH] [OPTIONS]
```

--------------------------------

### EvalSet Schema Example

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/agent_starter_pack/resources/docs/adk-eval-guide.md

Structure for defining evaluation cases, including conversation history, expected final responses, and intermediate tool usage.

```json
{
  "eval_set_id": "my_eval_set",
  "eval_cases": [
    {
      "eval_id": "search_test",
      "conversation": [
        {
          "user_content": { "parts": [{ "text": "Find a flight to NYC" }] },
          "final_response": {
            "role": "model",
            "parts": [{ "text": "I found a flight for $500. Want to book?" }]
          },
          "intermediate_data": {
            "tool_uses": [
              { "name": "search_flights", "args": { "destination": "NYC" } }
            ]
          }
        }
      ],
      "session_input": { "app_name": "<your-agent-directory>", "user_id": "user_1", "state": {} }
    }
  ]
}
```

--------------------------------

### Go Package Management

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/development-guide.md

Manage Go package dependencies using go get to add packages and go mod tidy to clean up.

```bash
go get <package>      # Add dependency
go mod tidy           # Clean up dependencies
```

--------------------------------

### Prototype to Production Enhancement

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/cli/enhance.md

Use this command to transition a prototype project to a production-ready state by adding CI/CD capabilities or a specific production-ready template.

```bash
# Created with --prototype, now ready to add CI/CD
uvx agent-starter-pack enhance --cicd-runner google_cloud_build

# Or add a specific template
uvx agent-starter-pack enhance adk@production-ready
```

--------------------------------

### Manually Add Scripts Directory to PATH

Source: https://github.com/googlecloudplatform/agent-starter-pack/blob/main/docs/guide/installation.md

Adds the user's local bin directory to the PATH for persistence. This is useful if the command is not found after installation.

```bash
export PATH="$HOME/.local/bin:$PATH"
# For user installations
```