Agent Starter Pack

https://googlecloudplatform.github.io/agent-starter-pack
Admin
The Agent Starter Pack helps developers build, deploy, and manage production-ready AI agents on...
Tokens:16,804
Snippets:165
Trust Score:8.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Create Agent Project with uvx

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/getting-started

This snippet demonstrates a streamlined approach using 'uvx' to create an agent project in a single command without requiring a permanent installation. It's a quick way to get started.

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

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

### Create Agent Project with Flags (pip/uvx)

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/getting-started

This example shows how to bypass interactive prompts when creating an agent project by using command-line flags to specify the agent template and deployment target. Useful for automation or quick setups.

```bash
# You can also pass flags to skip the prompts
agent-starter-pack create my-adk-agent -a adk_base -d agent_engine
```

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

### Displaying Agent Starter Pack Help Information

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Access the help documentation for the Agent Starter Pack command-line tool. This command provides information on available subcommands, options, and usage examples, confirming the tool is functional.

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

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

### Create Agent Project with pip

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/getting-started

This snippet shows the traditional setup using pip to create a virtual environment, install the agent starter pack, and then run the create command to generate a new agent project. It's a standard Python workflow.

```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 my-awesome-agent
```

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

### Explore and Run Agent Locally

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/getting-started

This snippet covers the steps to navigate into the newly created agent project directory and execute the necessary commands to install dependencies and launch the local playground. It assumes the project structure generated by the create command.

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

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

### Local Development Setup and Playground Launch

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/development-guide

This command installs project dependencies and launches the local interactive UI playground for testing agent logic. It assumes the user is in the root directory of their agent project.

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

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

### Quick Project Creation with uvx

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

This command uses `uvx` to quickly create projects without a permanent installation. It's ideal for users who have `uv` installed and prefer a streamlined workflow.

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

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

### Create Project after Persistent/Venv Install

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

After installing the Agent Starter Pack persistently (via `pipx`, `uv tool install`) or within a virtual environment, use this command to create a new project. This command initiates the project creation process using the installed tool.

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

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

### Persistent CLI Installation with uv tool

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Install the `agent-starter-pack` command globally and in isolation using `uv tool install`. This method requires `uv` to be installed and provides a fast, isolated installation for the command-line tool.

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

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

### Verbose Pip Installation for Dependency Analysis

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Install the Agent Starter Pack with verbose output (`-v`) enabled. This provides detailed information about the installation process, which is helpful for identifying the root cause of package dependency conflicts.

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

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

### Upgrading Agent Starter Pack

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Instructions for upgrading the Agent Starter Pack depending on the installation method. For `pipx` and `uv tool`, re-running the install command performs the upgrade. For virtual environments, use `pip install --upgrade`.

```bash
# For pipx:
pipx upgrade agent-starter-pack

# For uv tool:
uv tool install agent-starter-pack

# For pip/uv pip (in .venv):
(uv) pip install --upgrade agent-starter-pack
```

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

### Persistent CLI Installation with pipx

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Install the `agent-starter-pack` command globally and in isolation using `pipx`. This ensures the command is accessible from anywhere on your system without interfering with other Python packages. The installation involves installing `pipx` if it's not already present, and then using `pipx` to install the agent starter pack.

```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 CI/CD Pipeline Setup

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/development-guide

This command initiates the setup of a fully automated CI/CD pipeline for staging and production environments. It creates a GitHub repository, connects to a CI/CD provider, provisions infrastructure using Terraform, and configures deployment triggers.

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

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

### Virtual Environment Installation

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Install the Agent Starter Pack into an isolated Python environment using `venv`. This method ensures that dependencies are managed within the virtual environment, preventing conflicts with other projects. It involves creating and activating the virtual environment, then installing the package using `pip` or `uv`.

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

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

### Verifying Package Installation Location

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Check the exact location where the `agent-starter-pack` was installed. This command is useful for diagnosing installation issues and ensuring the package is located where the system expects it.

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

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

### Checking Directory Permissions

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Inspect the permissions of the `.local/bin` directory to identify potential issues that might be causing permission errors during installation or execution. This helps in diagnosing access problems.

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

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

### Automated Deployment Command (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment

Initiates the automated setup of the entire CI/CD pipeline and infrastructure for the Agent Starter Pack. This command uses `uvx` to download and execute the `agent-starter-pack setup-cicd` command, automating provisioning and configuration.

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

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

### Quick Start: Register Agent Engine after Deployment

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/register_gemini_enterprise

This example demonstrates the quick start process for registering an agent with Gemini Enterprise after deployment. It assumes `deployment_metadata.json` is created by `make deploy`. The command automatically fetches display name and description, and creates or updates the registration.

```bash
make deploy  # Creates deployment_metadata.json

ID="projects/123456/locations/global/collections/default_collection/engines/my-engine" \
  make register-gemini-enterprise
```

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

### Agent Starter Pack Configuration Examples

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

Provides TOML examples for configuring the agent-starter-pack in `pyproject.toml` for different agent types like Data Science, Chat Bot, and Enterprise.

```toml
[tool.agent-starter-pack]
base_template = "adk_base"
[tool.agent-starter-pack.settings]
deployment_targets = ["cloud_run"]
extra_dependencies = ["pandas", "numpy", "scikit-learn"]

```

```toml
[tool.agent-starter-pack]
base_template = "adk_base"
[tool.agent-starter-pack.settings]
frontend_type = "adk_streamlit"
deployment_targets = ["agent_engine", "cloud_run"]

```

```toml
[tool.agent-starter-pack]
base_template = "adk_base"
[tool.agent-starter-pack.settings]
session_type = "alloydb"
deployment_targets = ["cloud_run"]
include_data_ingestion = true

```

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

### Checking Agent Starter Pack Version

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Verify that the Agent Starter Pack has been installed correctly by checking its version number. This command should output the currently installed version of the tool.

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

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

### Automate CI/CD Setup with `setup-cicd`

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd

The `setup-cicd` command automates the deployment of CI/CD infrastructure. It can be run directly or with project IDs and repository names as flags. Requires `uvx` or `agent-starter-pack` CLI, Terraform, `gh` CLI, and `gcloud` CLI.

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

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

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

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

### Creating a Virtual Environment with Specific Python Version

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Create a new virtual environment using a specific Python version (e.g., 3.10). This is useful when you need to ensure compatibility with older projects or when the default Python version is not suitable. After creation, the environment needs to be activated.

```bash
python3.10 -m venv .venv
source .venv/bin/activate
```

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

### Initial Git Commit and Push

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/development-guide

This bash script demonstrates the commands required to add all project files, configure Git user details if not already set, commit the changes with a descriptive message, and push the code to the upstream origin on the main branch. This action typically triggers a CI/CD pipeline for deployment.

```bash
git add -A
git config --global user.email "you@example.com" # If not already configured
git config --global user.name "Your Name"     # If not already configured
git commit -m "Initial commit of agent code"
git push --set-upstream origin main
```

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

### Setup CI/CD Pipeline with Agent Starter Pack (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd

This command configures a CI/CD pipeline for Google Cloud projects. It requires project IDs for staging and production, with optional parameters for CI/CD, development, region, and GitHub repository details. Flags like `--local-state`, `--auto-approve`, and `--debug` control state management, user interaction, and logging.

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

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

### Check Agent Starter Pack Installation

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/troubleshooting

Commands to verify if the agent-starter-pack is installed using pip, check your system's PATH for executables, and reinstall if necessary. Also includes steps for pipx users.

```bash
pip list | grep agent-starter-pack
echo $PATH
pip install --user agent-starter-pack
pipx ensurepath
source ~/.bashrc  # or ~/.zshrc
```

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

### Upgrading Pip and Setuptools

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Update `pip` and `setuptools` to their latest versions. This is a common step to resolve package dependency conflicts, as outdated package management tools can sometimes cause issues.

```bash
pip install --upgrade pip setuptools
```

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

### Initial Agent Prototype Setup (bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/enhance

This command initializes or enhances an agent prototype located in `/app/agent.py`. It uses the `uvx agent-starter-pack enhance` command with a specific agent descriptor `adk@production-ready`.

```bash
uvx agent-starter-pack enhance adk@production-ready
```

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

### Checking PATH Environment Variable

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Verify that the directory containing the installed scripts is included in your system's PATH environment variable. This is a common troubleshooting step for 'command not found' errors after installation.

```bash
echo $PATH
```

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

### Creating a Project with a Remote Template

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

Example command to create a new project using the 'uvx agent-starter-pack create' command, specifying a remote template from GitHub.

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

```

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

### Fixing Permissions for Executable Scripts

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Grant execute permissions to scripts within the `.local/bin` directory. This command ensures that the `agent-starter-pack` executable can be run without permission denied errors.

```bash
chmod +x ~/.local/bin/agent-starter-pack
```

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

### Initialize and Push Git Repository (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

These bash commands guide the process of initializing a Git repository in the template directory, adding all files, committing them with a message, setting the remote origin to a GitHub repository, and pushing the changes to the main branch.

```bash
cd my-first-remote-template
git init
git add .
git commit -m "Initial remote template"
git remote add origin https://github.com/your-username/my-first-remote-template
git push -u origin main
```

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

### Manually Adding Scripts Directory to PATH

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Add the user script directory to your PATH environment variable to make installed commands accessible. This is a manual step often required if the installer doesn't automatically update the PATH. Remember to add this to your shell's configuration file (`.bashrc`, `.zshrc`) for persistence.

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

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

### Checking Python Version

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Display the currently active Python version. This is crucial for troubleshooting compatibility issues, as the Agent Starter Pack requires Python 3.10 or newer.

```bash
python --version
```

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

### Navigate to Project Directory

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/development-guide

After creating a new agent project, this command is used to change the current directory to the newly created project folder, enabling further development and command execution within the project's context.

```bash
cd my-awesome-agent
```

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

### Dockerfile for Combined Backend and Frontend (Dockerfile)

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/deploy-ui

This Dockerfile configures a container to run both a Python backend and a Node.js frontend development server concurrently. It installs necessary dependencies for both Python (uv) and Node.js (npm), copies application files, and exposes ports for both services. The CMD instruction starts both servers in parallel. This setup is intended for development and testing.

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

```

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

### Uninstalling Agent Starter Pack

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/installation

Commands to uninstall the Agent Starter Pack based on the installation method used. This ensures that the tool and its associated files are completely removed from your system or environment.

```bash
# For pipx:
pipx uninstall agent-starter-pack

# For uv tool:
uv tool uninstall agent-starter-pack

# For pip/uv pip (in .venv):
(uv) pip uninstall agent-starter-pack
```

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

### Setup Development Environment (Make)

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment

A command to set up a standalone development environment for the Agent Starter Pack. It orchestrates the execution of Terraform configurations for provisioning and deploying the application to the dev environment.

```make
make setup-dev-env
```

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

### Basic Registration Example

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/register_gemini_enterprise

A basic example of registering an agent engine with Gemini Enterprise using the `register-gemini-enterprise` Makefile target. The `ID` environment variable specifies the agent engine resource name.

```bash
ID="projects/123456789/locations/global/collections/default_collection/engines/my-engine" \
  make register-gemini-enterprise
```

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

### Registration Using Environment Variables

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/register_gemini_enterprise

This example demonstrates registering an agent engine with Gemini Enterprise by setting all necessary parameters as environment variables before executing the command. This approach is useful for scripting and automation.

```bash
export GEMINI_ENTERPRISE_APP_ID="projects/.../engines/xxx"
export GEMINI_DISPLAY_NAME="Product Support Agent"
export GEMINI_DESCRIPTION="AI agent for product support"

agent-starter-pack-register-gemini-enterprise
```

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

### Configure Gcloud Project for Development

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/development-guide

This command sets the active Google Cloud project for the gcloud CLI. Replace 'YOUR_DEV_PROJECT_ID' with your actual project ID. This ensures subsequent gcloud commands target the correct environment.

```bash
# Replace YOUR_DEV_PROJECT_ID with your actual Google Cloud Project ID
gcloud config set project YOUR_DEV_PROJECT_ID
```

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

### Browse ADK Samples Interactively (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/using-remote-templates

This command initiates an interactive prompt to help you choose and create an agent from the ADK samples. When prompted, you can select the option to browse and select from the available ADK samples.

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

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

### Test Agent Creation Locally with uvx

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

Demonstrates how to test a local agent-starter-pack template using the `uvx` command. It shows basic local testing and testing with specific deployment targets.

```bash
# Test from parent directory
uvx agent-starter-pack create test-project -a local@./your-template

# Test with different options
uvx agent-starter-pack create test-project -a local@./your-template --deployment-target cloud_run
```

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

### List Available Templates (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/using-remote-templates

These commands show how to list available templates. The first command lists built-in agents, the second lists official ADK samples by using the `--adk` flag, and the third lists templates from a specified Git repository using the `--source` flag. Note that only configured templates are discoverable.

```bash
# Built-in agents:
uvx agent-starter-pack list

# Official ADK samples:
uvx agent-starter-pack list --adk

# Templates in a specific repository:
uvx agent-starter-pack list --source https://github.com/my-org/my-templates
```

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

### Commit and Push Code to GitHub (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/setup_cicd

These commands are used after setting up the CI/CD pipeline to commit the generated configuration files and push them to the main branch of your GitHub repository. This action triggers the newly configured CI/CD pipeline.

```bash
git add .
git commit -m "Initial commit of agent starter pack"
git push -u origin main
```

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

### List Agents and Templates (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/list

This command allows you to list available agents and templates. You can specify a source URL to list templates from a specific repository or use the --adk flag to list official ADK samples. The output shows discoverable templates configured with '[tool.agent-starter-pack]' in pyproject.toml.

```bash
uvx agent-starter-pack list [OPTIONS]
```

```bash
# List built-in agents
uvx agent-starter-pack list

# List ADK samples  
uvx agent-starter-pack list --adk

# List templates from repository
uvx agent-starter-pack list --source https://github.com/user/templates
```

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

### Deploy Application to Dev Environment (Make)

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment

Deploys the agent application to the already provisioned development environment. This command should be run after the development infrastructure has been set up.

```make
make deploy
```

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

### Registration with Custom Metadata

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/register_gemini_enterprise

This example shows how to register an agent engine with custom display name and description for Gemini Enterprise. It uses environment variables `GEMINI_DISPLAY_NAME` and `GEMINI_DESCRIPTION` along with the `ID` for the agent engine.

```bash
ID="projects/.../engines/xxx" \
  GEMINI_DISPLAY_NAME="Support Agent" \
  GEMINI_DESCRIPTION="Customer support assistant" \
  make register-gemini-enterprise
```

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

### Template Creation Options (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/using-remote-templates

These commands illustrate advanced options for the `create` command when using remote templates. They allow customization of the agent's deployment target, inclusion of data ingestion features with specified datastores, custom session storage, and skipping verification checks.

```bash
# Specify deployment target
uvx agent-starter-pack create my-agent -a template-url --deployment-target cloud_run

# Include data ingestion
uvx agent-starter-pack create my-agent -a template-url --include-data-ingestion --datastore alloydb

# Custom session storage
uvx agent-starter-pack create my-agent -a template-url --session-type alloydb

# Skip verification checks
uvx agent-starter-pack create my-agent -a template-url --skip-checks
```

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

### Full GitHub URL Template (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/using-remote-templates

This command demonstrates using a complete GitHub URL, including the organization, repository, branch, and a specific path within the repository, as a template for agent creation. This provides precise control over which part of a repository is used as the template.

```bash
# Complete GitHub URL (copy from browser)
uvx agent-starter-pack create my-agent -a https://github.com/my-org/my-repo/tree/main/path-to-template
```

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

### Log in and Set Project for Vertex AI

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/troubleshooting

Commands to authenticate with Google Cloud and set the active project for Vertex AI. Ensures your environment is correctly configured for Vertex AI operations.

```bash
gcloud auth login --update-adc
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
```

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

### Tag and Publish Agent Releases

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

Shows how to tag a stable release using Git and push it to the remote repository. It also illustrates how users can reference specific versions of a template during creation.

```bash
# Tag stable releases
git tag v1.0.0
git push origin v1.0.0

# Users can reference specific versions
uvx agent-starter-pack create my-agent -a github.com/user/template@v1.0.0
```

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

### ADK Samples Shortcut (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/using-remote-templates

This command utilizes a shortcut alias 'adk' to create agents from official Google Agent Development Kit (ADK) samples stored in the 'google/adk-samples' repository. It allows for quick instantiation of common agent types like 'gemini-fullstack', 'data-science', or 'chat-agent'.

```bash
# Creates an agent from the 'gemini-fullstack' template in adk-samples
uvx agent-starter-pack create my-agent -a adk@gemini-fullstack

# Other popular ADK samples
uvx agent-starter-pack create my-agent -a adk@data-science
uvx agent-starter-pack create my-agent -a adk@chat-agent
```

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

### Create Agent from Local Template (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

This bash command demonstrates how to create a new agent instance from a local template directory. It uses the 'uvx agent-starter-pack create' command, specifying the agent name and the local path to the template.

```bash
# Run from the parent directory of 'my-first-remote-template'
uvx agent-starter-pack create my-test-agent -a local@./my-first-remote-template
```

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

### Configure Dependencies and Settings with pyproject.toml

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

This TOML configuration file defines project metadata, Python dependencies, and specific settings for the agent starter pack. It includes sections for project name, version, description, and custom agent starter pack configurations like base templates and deployment targets.

```toml
[project]
name = "my-first-remote-template"
version = "0.1.0"
description = "A simple template that says hello"
dependencies = [
    "google-adk>=1.8.0",
]

[tool.agent-starter-pack]
# The built-in agent to use as a foundation
base_template = "adk_base"

# Template metadata (optional - falls back to [project] section)
name = "My First Remote Template"
description = "A simple template that demonstrates custom greetings"

# Override settings from the base template
[tool.agent-starter-pack.settings]
# This template will only support the 'agent_engine' deployment target
deployment_targets = ["agent_engine"]
# Optional: Customize the directory name for agent files (default: "app")
agent_directory = "app"
```

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

### TOML Configuration for Agent Starter Pack

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

Defines the project's metadata, dependencies, and specific settings for the Agent Starter Pack, including base template, name, description, deployment targets, frontend type, and agent directory.

```toml
[project]
name = "my-awesome-template"
description = "An awesome AI agent template"
dependencies = ["google-adk>=1.8.0", "custom-lib"]

[tool.agent-starter-pack]
base_template = "adk_base"
name = "My Awesome Template"  # Optional: falls back to [project].name
description = "Custom description"  # Optional: falls back to [project].description

[tool.agent-starter-pack.settings]
deployment_targets = ["cloud_run", "agent_engine"]
frontend_type = "adk_streamlit"
# Optional: Customize the directory name for agent files (default: "app")
agent_directory = "app"

```

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

### Create GCP AI Agent Project (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/create

Creates a new GCP-based AI agent project using a specified template. Supports built-in agents, remote GitHub repositories, ADK samples, and local projects as sources. If no template is specified, an interactive list is presented.

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

```bash
# Create with specific built-in agent
uvx agent-starter-pack create my-agent -a adk_base -d cloud_run

# Use ADK samples
uvx agent-starter-pack create my-agent -a adk@gemini-fullstack

# Use GitHub repository
uvx agent-starter-pack create my-agent -a https://github.com/user/my-template

# Use shorthand notation with branch
uvx agent-starter-pack create my-agent -a github.com/user/template@develop

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

```bash
# Include data ingestion with specific datastore
uvx agent-starter-pack create my-rag-agent -a adk_base -i -ds alloydb -d cloud_run

# Create with custom region and CI/CD
uvx agent-starter-pack create my-agent -a template-url --region europe-west1 --cicd-runner github_actions

# In-folder creation (add to existing project)
uvx agent-starter-pack create my-agent -a adk@data-science --in-folder

# Customize agent directory name
uvx agent-starter-pack create my-agent -a adk_base --agent-directory chatbot

# Skip all prompts for automation
uvx agent-starter-pack create my-agent -a template-url --auto-approve --skip-checks
```

```bash
# Create in specific directory
uvx agent-starter-pack create my-agent -o ./projects/

# Create in current directory with in-folder
uvx agent-starter-pack create existing-project -a template-url --in-folder
```

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

### Debug Agent Starter Pack Project Creation

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/troubleshooting

A command to create a new project using the Agent Starter Pack with the debug flag enabled. This provides more detailed output to help diagnose creation failures.

```bash
agent-starter-pack create my-project-name --debug
```

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

### TOML Configuration with Fallback Behavior

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

Illustrates the TOML configuration structure where project name and description fall back to the '[project]' section if not defined in '[tool.agent-starter-pack]'.

```toml
[project]
name = "my-agent-template"
description = "A template for building chatbots"

# This section is optional - without it, falls back to [project] + defaults
[tool.agent-starter-pack]
base_template = "adk_base"  # Override default
# name and description will use [project] values

```

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

### Shorthand URL Template Formats (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/using-remote-templates

These commands show shorthand notations for specifying remote templates, supporting various Git providers like GitHub, GitLab, and Bitbucket. You can specify a branch or tag using the '@' symbol for version control. This offers a concise way to reference templates.

```bash
# GitHub shorthand
uvx agent-starter-pack create my-agent -a github.com/my-org/my-repo/path-to-template

# Specify branch or tag with @
uvx agent-starter-pack create my-agent -a github.com/my-org/my-repo/path-to-template@develop

# Works with GitLab, Bitbucket, etc.
uvx agent-starter-pack create my-agent -a gitlab.com/my-org/my-repo/template@v1.0
```

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

### Create Agent from Remote Template (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/using-remote-templates

This command creates a new agent project named 'my-agent' using a remote Git repository as a template. The `-a` flag specifies the template URL, which can be a full GitHub URL, a shorthand notation, an ADK sample alias, or a local path. The system automatically fetches, configures, and generates the agent.

```bash
# Use any GitHub repository as a template
uvx agent-starter-pack create my-agent -a https://github.com/user/my-template

# Use shorthand notation
uvx agent-starter-pack create my-agent -a github.com/user/my-template@main

# Use official ADK samples
uvx agent-starter-pack create my-agent -a adk@gemini-fullstack

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

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

### Enhance Agent with Data Pipeline (bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/enhance

Integrates data ingestion capabilities into an existing agent. This is achieved by using the `uvx agent-starter-pack enhance` command with the `--include-data-ingestion` and `--datastore` flags, specifying `alloydb` as the datastore.

```bash
# Add data ingestion to existing agent
uvx agent-starter-pack enhance --include-data-ingestion --datastore alloydb
```

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

### Use Local Project as Template (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/using-remote-templates

This command allows you to use an existing local project directory as a template for creating a new agent. You can specify the path using either a relative or absolute path, enabling rapid iteration and development using your current codebase.

```bash
# Use your existing project as source
uvx agent-starter-pack create my-test-agent -a local@./path/to/your/project
uvx agent-starter-pack create my-test-agent -a local@/absolute/path/to/project
```

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

### Enable and Verify Vertex AI API

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/troubleshooting

Bash commands to enable the Vertex AI API in your Google Cloud project and then verify its status. This is crucial for operations that rely on Vertex AI services.

```bash
gcloud services enable aiplatform.googleapis.com
gcloud services list --filter=aiplatform.googleapis.com
```

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

### Enhance Agent with Infrastructure (bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/enhance

Adds Terraform and deployment capabilities to an existing agent project. This command utilizes the `uvx agent-starter-pack enhance` utility with the `--deployment-target` flag set to `cloud_run`.

```bash
# Add Terraform and deployment capabilities
uvx agent-starter-pack enhance --deployment-target cloud_run
```

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

### Custom Agent Logic in Python

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

This Python code defines a custom agent using the Agent class from the google.adk.agents library. It includes a greeting function and initializes the root agent with a specific model and instruction, also making the greeting function available as a tool.

```python
from google.adk.agents import Agent

def get_greeting(name: str = "World") -> str:
    """Returns a friendly greeting from the remote template."""
    return f"Hello, {name}! This greeting comes from a remote template."

root_agent = Agent(
    name="root_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful AI assistant. Use your tools to answer questions.",
    tools=[get_greeting],
)
```

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

### Create Agent from Remote Template (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

This bash command shows how to create a new agent instance using a remote template hosted on GitHub. It specifies the agent name and the URL of the Git repository containing the template.

```bash
uvx agent-starter-pack create my-remote-agent -a https://github.com/your-username/my-first-remote-template
```

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

### Enhance Project with Agent Starter Pack (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/enhance

The 'enhance' command is used to add agent-starter-pack capabilities to an existing project. It can use the current directory as a template, a local directory, a built-in agent name, or a remote template. Options allow customization of the agent directory, deployment target, and inclusion of data ingestion.

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

```bash
# Enhance current project with default template
uvx agent-starter-pack enhance

# Enhance with a specific agent template
uvx agent-starter-pack enhance adk@gemini-fullstack

# Enhance with custom project name
uvx agent-starter-pack enhance --name my-enhanced-agent
```

```bash
# Enhance with custom agent directory
uvx agent-starter-pack enhance . --agent-directory chatbot

# Enhance with specific deployment target
uvx agent-starter-pack enhance adk@data-science --deployment-target cloud_run

# Enhance with data ingestion capabilities
uvx agent-starter-pack enhance --include-data-ingestion --datastore alloydb

# Enhance with custom session storage
uvx agent-starter-pack enhance --session-type alloydb
```

```bash
# Enhance current project with LangGraph capabilities
uvx agent-starter-pack enhance . --base-template langgraph_base_react

# Enhance with RAG-enabled base template
uvx agent-starter-pack enhance . --base-template agentic_rag
```

```bash
# Enhance with custom agent directory
uvx agent-starter-pack enhance . --agent-directory my_agent
```

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

### Enhance Existing Project (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/using-remote-templates

The `enhance` command adds agent capabilities to an existing project. By providing a template alias (like 'adk@gemini-fullstack'), it integrates the necessary files and configurations to transform a standard project into an agent-ready one.

```bash
# Add agent functionality to current project
uvx agent-starter-pack enhance adk@gemini-fullstack
```

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

### Create Agent with Data Ingestion (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/guide/data-ingestion

This command creates a new agent project and includes a data ingestion pipeline, specifying either Vertex AI Search or Vertex AI Vector Search as the datastore.

```bash
# Using Vertex AI Search
agent-starter-pack create my-agent-project --include-data-ingestion -ds vertex_ai_search

# Using Vertex AI Vector Search
agent-starter-pack create my-agent-project --include-data-ingestion -ds vertex_ai_vector_search
```

```bash
# Example with Vertex AI Search
agent-starter-pack create my-project -ds vertex_ai_search

# Example with Vertex AI Vector Search
agent-starter-pack create my-project -ds vertex_ai_vector_search
```

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

### Create Agent from Custom Git Repository Template

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates

Generates a new agent project by cloning a custom Git repository as a template. This is useful for using your own or community-provided templates. It requires the agent name and the URL of the Git repository.

```bash
# After creating your template repository
uvx agent-starter-pack create test-agent -a https://github.com/you/your-template
```

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

### Create Agent with Predefined Remote Template

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates

Generates a new agent project using a predefined remote template. This command assumes the template is registered or accessible via a known alias. It requires the agent name and the template alias.

```bash
uvx agent-starter-pack create my-agent -a adk@gemini-fullstack
```

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

### Locking Agent Starter Pack Version - Bash Commands

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

Provides bash commands to generate a lock file after updating dependencies and to commit the updated configuration files.

```bash
uv lock

git add pyproject.toml uv.lock
git commit -m "Lock agent-starter-pack version for compatibility"

```

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

### Create Agent In-Folder (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/using-remote-templates

The `--in-folder` flag modifies the `create` command to generate agent files directly in the current directory, rather than creating a new subdirectory for the agent. This is useful for integrating templates into existing project structures.

```bash
# Standard: creates ./my-agent/ directory
uvx agent-starter-pack create my-agent -a template-url

# In-folder: creates files in current directory
uvx agent-starter-pack create my-agent -a template-url --in-folder
```

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

### Python Dependencies in pyproject.toml

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

Specifies Python project dependencies, including the 'google-adk' and custom packages, within the 'pyproject.toml' file.

```toml
[project]
dependencies = [
    "google-adk>=1.8.0",
    "your-custom-package>=1.0.0",
    "another-dependency",
]

```

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

### Locking Agent Starter Pack Version

Source: https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/creating-remote-templates

Demonstrates how to lock the Agent Starter Pack to a specific version in 'pyproject.toml' as a development dependency for reproducible builds.

```toml
[dependency-groups]
dev = [
    "agent-starter-pack==0.14.1",  # Lock to specific version
    # ... your other dev dependencies
]

```

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

### Upgrade Agent Base Template (bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/enhance

Upgrades an agent from a basic to an advanced template, or changes the base template inheritance. This involves using the `uvx agent-starter-pack enhance` command with specific template identifiers like `adk@gemini-fullstack` or by specifying a local path and a new base template like `langgraph_base_react`.

```bash
# Upgrade from basic to advanced agent template
uvx agent-starter-pack enhance adk@gemini-fullstack

# Or change base template inheritance
uvx agent-starter-pack enhance . --base-template langgraph_base_react
```

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

### Agent Starter Pack Enhance Command Alias (Bash)

Source: https://googlecloudplatform.github.io/agent-starter-pack/cli/enhance

The 'enhance' command is an alias for the 'create' command with specific flags set to modify the current directory in-place. It automatically sets the project name, enables in-folder templating, and validates the project structure.

```bash
uvx agent-starter-pack create PROJECT_NAME --agent TEMPLATE --in-folder
```
Tokens:
Raw