# Technical Documentation: GoogleCloudPlatform/agent-starter-pack

> ℹ️ **Provenance:** Hybrid Fusion: `GoogleCloudPlatform/agent-starter-pack` (README + 3 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/GoogleCloudPlatform/agent-starter-pack) · Recency: Active (< 180 days)

## 1. Project Overview & Quickstart (GoogleCloudPlatform/agent-starter-pack)

# 🚀 Agent Starter Pack

 [](https://youtu.be/jHt-ZVD660g) [](https://googlecloudplatform.github.io/agent-starter-pack/) <a href="https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fagent_starter_pack%2Fresources%2Fidx">
  
    
    
    
  
</a> [](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs) 

> ## ⚠️ Agent Starter Pack is in maintenance mode — switch to `agents-cli`
>
> **Active development has moved to [`agents-cli`](https://github.com/google/agents-cli)**, the next evolution of Agent Starter Pack. ASP will continue to receive critical fixes only — **no new features, no new templates, no new deployment targets.** New projects should start with `agents-cli`; existing projects should migrate.
>
> ```bash
> uvx google-agents-cli setup
> ```
>
> **Migration takes minutes** — your agent code, tests, Terraform, and CI/CD carry over with no rewrites.
>
> **What you gain:**
> - 🛠️ **Unified CLI** in place of the Makefile — `run`, `deploy`, `eval run`, `eval compare`, `playground`, `lint`, and more
> - 🧠 **Bundled coding-agent skills** that turn Claude Code, Gemini CLI, or Codex into an ADK expert
> - 🔁 **End-to-end lifecycle tooling**: scaffold → eval → deploy → publish → observe
> - ☁️ **First-class support** for Google Cloud's Agent Platform
>
> **→ [Migration guide](https://google.github.io/agents-cli/reference/from-agent-starter-pack/)** &nbsp;•&nbsp; [Get started](https://google.github.io/agents-cli/) &nbsp;•&nbsp; [Docs](https://google.github.io/agents-cli/) &nbsp;•&nbsp; [GitHub](https://github.com/google/agents-cli) &nbsp;•&nbsp; [PyPI](https://pypi.org/project/google-agents-cli/)

---

A Python package that provides **production-ready templates** for GenAI agents on Google Cloud.

Focus on your agent logic—the starter pack provides everything else: infrastructure, CI/CD, observability, and security.

| ⚡️ Launch | 🧪 Experiment  | ✅ Deploy | 🛠️ Customize |
|---|---|---|---|
| [Pre-built agent templates](./agent_starter_pack/agents/) (ReAct, RAG, multi-agent, Live API). | [Vertex AI evaluation](https://cloud.google.com/vertex-ai/generative-ai/docs/models/evaluation-overview) and an interactive playground. | Production-ready infra with [monitoring, observability](https://googlecloudplatform.github.io/agent-starter-pack/guide/observability), and [CI/CD](https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment) on [Cloud Run](https://cloud.google.com/run) or [Agent Engine](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview). | Extend and customize templates according to your needs. 🆕 Now integrating with [Gemini CLI](https://github.com/google-gemini/gemini-cli) |

---

## ⚡ Get Started in 1 Minute

**From zero to production-ready agent in 60 seconds using [`uv`](https://docs.astral.sh/uv/getting-started/installation/):**

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


 ✨ Alternative: Using pip

If you don't have [`uv`](https://github.com/astral-sh/uv) installed, you can use pip:
```bash
# Create and activate a Python virtual environment
python -m venv .venv && source .venv/bin/activate

# Install the agent starter pack
pip install --upgrade agent-starter-pack

# Create a new agent project
agent-starter-pack create
```


**That's it!** You now have a fully functional agent project—complete with backend, frontend, and deployment infrastructure—ready for you to explore and customize.

### 🔧 Enhance Existing Agents

Already have an agent? Add production-ready deployment and infrastructure by running this command in your project's root folder:

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

See [Installation Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/installation) for more options, or try with zero setup in [Firebase Studio](https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fsrc%2Fresources%2Fidx) or [Cloud Shell](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs).

---

## 🤖 Agents

| Agent Name                  | Description                                                                                                                       |
|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| `adk`      | A base ReAct agent implemented using Google's [Agent Development Kit](https://github.com/google/adk-python) |
| `adk_a2a`  | An ADK agent with [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/) support for distributed agent communication and interoperability |
| `agentic_rag` | A RAG agent for document retrieval and Q&A. 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).       |
| `langgraph`      | A base ReAct agent implemented using LangChain's [LangGraph](https://github.com/langchain-ai/langgraph) |
| `adk_java`   | A base ReAct agent implemented using Google's [Agent Development Kit for Java](https://github.com/google/adk-java) |
| `adk_live`       | A real-time multimodal RAG agent powered by Gemini, supporting audio/video/text chat     |

**More agents are on the way!** We are continuously expanding our [agent library](https://googlecloudplatform.github.io/agent-starter-pack/agents/overview). Have a specific agent type in mind? [Raise an issue as a feature request!](https://github.com/GoogleCloudPlatform/agent-starter-pack/issues/new?labels=enhancement)

**🔍 ADK Samples**

Looking to explore more ADK examples? Check out the [ADK Samples Repository](https://github.com/google/adk-samples) for additional examples and use cases demonstrating ADK's capabilities.

---

## 🌟 Community Showcase

Explore amazing projects built with the Agent Starter Pack! 

**[View Community Showcase →](https://googlecloudplatform.github.io/agent-starter-pack/guide/community-showcase)**

## Key Features

The `agent-starter-pack` offers key features to accelerate and simplify the development of your agent:
- **🔄 [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](https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/)**: 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.

## High-Level Architecture

This starter pack covers all aspects of Agent development, from prototyping and evaluation to deployment and monitoring.



---

## 🔧 Requirements

- Python 3.10+
- [Google Cloud SDK](https://cloud.google.com/sdk/docs/install)
- [Terraform](https://developer.hashicorp.com/terraform/downloads) (for deployment)
- [Make](https://www.gnu.org/software/make/) (for development tasks)


## 📚 Documentation

Visit our [documentation site](https://googlecloudplatform.github.io/agent-starter-pack/) for comprehensive guides and references!

🔍 **New to the codebase?** Explore the [CodeWiki](https://codewiki.google/github.com/googlecloudplatform/agent-starter-pack) for AI-powered code understanding and navigation.

- [Getting Started Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/getting-started) - First steps with agent-starter-pack
- [Installation Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/installation) - Setting up your environment
- [Deployment Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment) - Taking your agent to production
- [Agent Templates Overview](https://googlecloudplatform.github.io/agent-starter-pack/agents/overview) - Explore available agent patterns
- [CLI Reference](https://googlecloudplatform.github.io/agent-starter-pack/cli/) - Command-line tool documentation


### Video Walkthrough:

- **[From Demo to Production with Agent Starter Pack](https://www.youtube.com/watch?v=mtJMYgJkTt8)**: Learn how the Agent Starter Pack acts as an Automated Architect, building the professional infrastructure for your AI project in seconds. Covers why most AI projects fail at deployment and how ASP automates Terraform, CI/CD, and observability.

- **[6-minute introduction](https://www.youtube.com/live/eZ-8UQ_t4YM?feature=shared&t=2791)** (April 2025): Explaining the Agent Starter Pack and demonstrating its key features. Part of the Kaggle GenAI intensive course.

Looking for more examples and resources for Generative AI on Google Cloud? Check out the [GoogleCloudPlatform/generative-ai](https://github.com/GoogleCloudPlatform/generative-ai) repository for notebooks, code samples, and more!

## Contributing

Contributions are welcome! See the [Contributing Guide](CONTRIBUTING.md).

## Feedback

We value your input! Your feedback helps us improve this starter pack and make it more useful for the community.

### Getting Help

If you encounter any issues or have specific suggestions, please first consider [raising an issue](https://github.com/GoogleCloudPlatform/generative-ai/issues) on our GitHub repository.

### Share Your Experience

For other types of feedback, or if you'd like to share a positive experience or success story using this starter pack, we'd love to hear from you! You can reach out to us at [agent-starter-pack@google.com](mailto:agent-starter-pack@google.com).

Thank you for your contributions!

## Disclaimer

This repository is for demonstrative purposes only and is not an officially supported Google product.

## Terms of Service

The agent-starter-pack templating CLI and the templates in this starter pack leverage Google Cloud APIs. When you use this starter pack, you'll be deploying resources in your own Google Cloud project and will be responsible for those resources. Please review the [Google Cloud Service Terms](https://cloud.google.com/terms/service-terms) for details on the terms of service associated with these APIs.

## 2. In-Tree Documentation Chapters (GoogleCloudPlatform/agent-starter-pack)

## File: README.md

# 🚀 Agent Starter Pack

 [](https://youtu.be/jHt-ZVD660g) [](https://googlecloudplatform.github.io/agent-starter-pack/) <a href="https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fagent_starter_pack%2Fresources%2Fidx">
  
    
    
    
  
</a> [](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs) 

> ## ⚠️ Agent Starter Pack is in maintenance mode — switch to `agents-cli`
>
> **Active development has moved to [`agents-cli`](https://github.com/google/agents-cli)**, the next evolution of Agent Starter Pack. ASP will continue to receive critical fixes only — **no new features, no new templates, no new deployment targets.** New projects should start with `agents-cli`; existing projects should migrate.
>
> ```bash
> uvx google-agents-cli setup
> ```
>
> **Migration takes minutes** — your agent code, tests, Terraform, and CI/CD carry over with no rewrites.
>
> **What you gain:**
> - 🛠️ **Unified CLI** in place of the Makefile — `run`, `deploy`, `eval run`, `eval compare`, `playground`, `lint`, and more
> - 🧠 **Bundled coding-agent skills** that turn Claude Code, Gemini CLI, or Codex into an ADK expert
> - 🔁 **End-to-end lifecycle tooling**: scaffold → eval → deploy → publish → observe
> - ☁️ **First-class support** for Google Cloud's Agent Platform
>
> **→ [Migration guide](https://google.github.io/agents-cli/reference/from-agent-starter-pack/)** &nbsp;•&nbsp; [Get started](https://google.github.io/agents-cli/) &nbsp;•&nbsp; [Docs](https://google.github.io/agents-cli/) &nbsp;•&nbsp; [GitHub](https://github.com/google/agents-cli) &nbsp;•&nbsp; [PyPI](https://pypi.org/project/google-agents-cli/)

---

A Python package that provides **production-ready templates** for GenAI agents on Google Cloud.

Focus on your agent logic—the starter pack provides everything else: infrastructure, CI/CD, observability, and security.

| ⚡️ Launch | 🧪 Experiment  | ✅ Deploy | 🛠️ Customize |
|---|---|---|---|
| [Pre-built agent templates](./agent_starter_pack/agents/) (ReAct, RAG, multi-agent, Live API). | [Vertex AI evaluation](https://cloud.google.com/vertex-ai/generative-ai/docs/models/evaluation-overview) and an interactive playground. | Production-ready infra with [monitoring, observability](https://googlecloudplatform.github.io/agent-starter-pack/guide/observability), and [CI/CD](https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment) on [Cloud Run](https://cloud.google.com/run) or [Agent Engine](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview). | Extend and customize templates according to your needs. 🆕 Now integrating with [Gemini CLI](https://github.com/google-gemini/gemini-cli) |

---

## ⚡ Get Started in 1 Minute

**From zero to production-ready agent in 60 seconds using [`uv`](https://docs.astral.sh/uv/getting-started/installation/):**

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


 ✨ Alternative: Using pip

If you don't have [`uv`](https://github.com/astral-sh/uv) installed, you can use pip:
```bash
# Create and activate a Python virtual environment
python -m venv .venv && source .venv/bin/activate

# Install the agent starter pack
pip install --upgrade agent-starter-pack

# Create a new agent project
agent-starter-pack create
```


**That's it!** You now have a fully functional agent project—complete with backend, frontend, and deployment infrastructure—ready for you to explore and customize.

### 🔧 Enhance Existing Agents

Already have an agent? Add production-ready deployment and infrastructure by running this command in your project's root folder:

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

See [Installation Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/installation) for more options, or try with zero setup in [Firebase Studio](https://studio.firebase.google.com/new?template=https%3A%2F%2Fgithub.com%2FGoogleCloudPlatform%2Fagent-starter-pack%2Ftree%2Fmain%2Fsrc%2Fresources%2Fidx) or [Cloud Shell](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https%3A%2F%2Fgithub.com%2Feliasecchig%2Fasp-open-in-cloud-shell&cloudshell_print=open-in-cs).

---

## 🤖 Agents

| Agent Name                  | Description                                                                                                                       |
|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| `adk`      | A base ReAct agent implemented using Google's [Agent Development Kit](https://github.com/google/adk-python) |
| `adk_a2a`  | An ADK agent with [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/) support for distributed agent communication and interoperability |
| `agentic_rag` | A RAG agent for document retrieval and Q&A. 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).       |
| `langgraph`      | A base ReAct agent implemented using LangChain's [LangGraph](https://github.com/langchain-ai/langgraph) |
| `adk_java`   | A base ReAct agent implemented using Google's [Agent Development Kit for Java](https://github.com/google/adk-java) |
| `adk_live`       | A real-time multimodal RAG agent powered by Gemini, supporting audio/video/text chat     |

**More agents are on the way!** We are continuously expanding our [agent library](https://googlecloudplatform.github.io/agent-starter-pack/agents/overview). Have a specific agent type in mind? [Raise an issue as a feature request!](https://github.com/GoogleCloudPlatform/agent-starter-pack/issues/new?labels=enhancement)

**🔍 ADK Samples**

Looking to explore more ADK examples? Check out the [ADK Samples Repository](https://github.com/google/adk-samples) for additional examples and use cases demonstrating ADK's capabilities.

---

## 🌟 Community Showcase

Explore amazing projects built with the Agent Starter Pack! 

**[View Community Showcase →](https://googlecloudplatform.github.io/agent-starter-pack/guide/community-showcase)**

## Key Features

The `agent-starter-pack` offers key features to accelerate and simplify the development of your agent:
- **🔄 [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](https://googlecloudplatform.github.io/agent-starter-pack/remote-templates/)**: 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.

## High-Level Architecture

This starter pack covers all aspects of Agent development, from prototyping and evaluation to deployment and monitoring.



---

## 🔧 Requirements

- Python 3.10+
- [Google Cloud SDK](https://cloud.google.com/sdk/docs/install)
- [Terraform](https://developer.hashicorp.com/terraform/downloads) (for deployment)
- [Make](https://www.gnu.org/software/make/) (for development tasks)


## 📚 Documentation

Visit our [documentation site](https://googlecloudplatform.github.io/agent-starter-pack/) for comprehensive guides and references!

🔍 **New to the codebase?** Explore the [CodeWiki](https://codewiki.google/github.com/googlecloudplatform/agent-starter-pack) for AI-powered code understanding and navigation.

- [Getting Started Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/getting-started) - First steps with agent-starter-pack
- [Installation Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/installation) - Setting up your environment
- [Deployment Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/deployment) - Taking your agent to production
- [Agent Templates Overview](https://googlecloudplatform.github.io/agent-starter-pack/agents/overview) - Explore available agent patterns
- [CLI Reference](https://googlecloudplatform.github.io/agent-starter-pack/cli/) - Command-line tool documentation


### Video Walkthrough:

- **[From Demo to Production with Agent Starter Pack](https://www.youtube.com/watch?v=mtJMYgJkTt8)**: Learn how the Agent Starter Pack acts as an Automated Architect, building the professional infrastructure for your AI project in seconds. Covers why most AI projects fail at deployment and how ASP automates Terraform, CI/CD, and observability.

- **[6-minute introduction](https://www.youtube.com/live/eZ-8UQ_t4YM?feature=shared&t=2791)** (April 2025): Explaining the Agent Starter Pack and demonstrating its key features. Part of the Kaggle GenAI intensive course.

Looking for more examples and resources for Generative AI on Google Cloud? Check out the [GoogleCloudPlatform/generative-ai](https://github.com/GoogleCloudPlatform/generative-ai) repository for notebooks, code samples, and more!

## Contributing

Contributions are welcome! See the [Contributing Guide](CONTRIBUTING.md).

## Feedback

We value your input! Your feedback helps us improve this starter pack and make it more useful for the community.

### Getting Help

If you encounter any issues or have specific suggestions, please first consider [raising an issue](https://github.com/GoogleCloudPlatform/generative-ai/issues) on our GitHub repository.

### Share Your Experience

For other types of feedback, or if you'd like to share a positive experience or success story using this starter pack, we'd love to hear from you! You can reach out to us at [agent-starter-pack@google.com](mailto:agent-starter-pack@google.com).

Thank you for your contributions!

## Disclaimer

This repository is for demonstrative purposes only and is not an officially supported Google product.

## Terms of Service

The agent-starter-pack templating CLI and the templates in this starter pack leverage Google Cloud APIs. When you use this starter pack, you'll be deploying resources in your own Google Cloud project and will be responsible for those resources. Please review the [Google Cloud Service Terms](https://cloud.google.com/terms/service-terms) for details on the terms of service associated with these APIs.

---

## File: docs/cli/create.md

# create

Create new GCP-based AI agent projects from built-in agents or remote templates.

## Usage

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

## Arguments

- `PROJECT_NAME` (optional): Name for your new agent project directory and base for resource naming.
  If omitted, you'll be prompted interactively (or defaults to `my-agent` with `--auto-approve`).
  *Note: This name will be converted to lowercase and must be 26 characters or less.*

## Template Selection

### `--agent`, `-a` TEMPLATE
Specify which template to use for your agent:

**Built-in agents:**
```bash
uvx agent-starter-pack create my-agent -a adk
uvx agent-starter-pack create my-agent -a chat_agent
```

**Remote templates:**
```bash
# Full GitHub URL
uvx agent-starter-pack create my-agent -a https://github.com/user/repo

# Shorthand notation  
uvx agent-starter-pack create my-agent -a github.com/user/repo@main

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

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

If omitted, you'll see an interactive list of available agents.

## Deployment Options

### `--deployment-target`, `-d` TARGET
Deployment target for your agent:
- `cloud_run` - Deploy to Google Cloud Run (serverless containers)
- `gke` - Deploy to Google Kubernetes Engine (Autopilot)
- `agent_engine` - Deploy to Google Cloud Agent Engine (managed platform)

### `--cicd-runner` RUNNER
CI/CD runner to use:
- `google_cloud_build` - Use Google Cloud Build
- `github_actions` - Use GitHub Actions
- `skip` - No CI/CD (minimal project, same as `--prototype`)

### `--prototype`, `-p`
Create a minimal project without CI/CD or Terraform infrastructure. Ideal for:
- Quick prototyping and experimentation
- Learning and tutorials
- Teams with custom deployment pipelines

**What gets skipped:**
- `.github/workflows/` or `.cloudbuild/`
- `deployment/` (Terraform)
- `tests/load_test/`
- Makefile `setup-dev-env` target

**Upgrade path:** Run `uvx agent-starter-pack enhance` later to add CI/CD scaffolding.

### `--region` REGION
GCP region for deployment (default: `us-east1`)

## Data & Storage Options

### `--datastore`, `-ds` DATASTORE
Type of datastore for data ingestion. Automatically enables data ingestion when specified. For agents that require data ingestion (e.g., `agentic_rag`), you will be prompted to select a datastore if not specified:
- `vertex_ai_search`
- `vertex_ai_vector_search`
- `cloud_sql`

### `--session-type` TYPE
Session storage type (for Cloud Run and GKE deployments):
- `in_memory` - Store sessions in memory
- `cloud_sql` - Store sessions in Cloud SQL (PostgreSQL)
- `agent_engine` - Use Agent Engine session management

## Project Creation Options

### `--output-dir`, `-o` DIRECTORY
Output directory for the project (default: current directory)

### `--agent-directory`, `-dir` DIRECTORY
Name of the agent directory (overrides template default, usually `app`). This determines where your agent code files will be located within the project structure.

### `--base-template`, `-bt` TEMPLATE
Override the base template specified in a remote template's configuration. Only applicable when using remote templates with the `--agent` flag. This allows you to use a different built-in agent as the foundation instead of the one specified in the remote template's `pyproject.toml`.

**Interactive dependency management:**
When overriding the base template, you'll be prompted to add required dependencies using `uv add`:

```bash
# Use adk_a2a as base instead of the remote template's default
uvx agent-starter-pack create my-agent -a github.com/user/template --base-template adk_a2a

✓ Base template override: Using 'adk_a2a' as foundation
  This requires adding the following dependencies:
    • google-adk>=1.16.0,<2.0.0
    • a2a-sdk~=0.3.22

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

With `--auto-approve`, dependencies are added automatically without prompting:
```bash
uvx agent-starter-pack create my-agent -a template --base-template adk_a2a --auto-approve
# Dependencies are added automatically
```

### `--in-folder`
Create agent files directly in the current directory instead of creating a new project subdirectory.

**Standard behavior:**
```bash
uvx agent-starter-pack create my-agent -a template
# Creates: ./my-agent/[project files]
```

**In-folder behavior:**
```bash  
uvx agent-starter-pack create my-agent -a template --in-folder
# Creates: ./[project files] (in current directory)
```

**Use cases:**
- Adding agent capabilities to existing projects
- Working within established repository structures
- Containerized development environments

**Automatic Backup:** When using `--in-folder`, a complete backup of your directory is automatically created at `~/.agent-starter-pack/backups/[dirname]_[timestamp]` before any changes are made.

## Automation Options

### `--auto-approve`, `--yes`, `-y`
Skip interactive confirmation prompts and use sensible defaults:
- Project name defaults to `my-agent`
- Agent defaults to first available (typically `adk`)
- Deployment target defaults to `agent_engine`
- CI/CD runner defaults to `google_cloud_build`

### `--google-api-key`, `--api-key`, `-k` [KEY]
Use Google AI Studio API key instead of Vertex AI. If provided without a value, generates a `.env` file with a `YOUR_API_KEY` placeholder.

### `--skip-checks`
Skip verification checks for GCP authentication and Vertex AI connection.

### `--debug`
Enable debug logging for troubleshooting.

## Examples

### Quick Start

```bash
# Create with all defaults (project: my-agent, agent: adk, target: agent_engine)
uvx agent-starter-pack create -y

# Fully interactive mode
uvx agent-starter-pack create

# Quick prototype (no CI/CD, no Terraform)
uvx agent-starter-pack create my-prototype -p -d agent_engine
```

### Basic Usage

```bash
# Create a new project with specific name
uvx agent-starter-pack create my-agent-project

# Create with specific built-in agent (Python)
uvx agent-starter-pack create my-agent -a adk -d cloud_run

# Create a Go agent (Cloud Run only)
uvx agent-starter-pack create my-go-agent -a adk_go

# Create a TypeScript agent (Cloud Run only)
uvx agent-starter-pack create my-ts-agent -a adk_ts
```

### Remote Templates

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

# Override the base template of a remote template
uvx agent-starter-pack create my-agent -a adk@data-science --base-template adk_live
```

### Advanced Configuration

```bash
# Include data ingestion with specific datastore
uvx agent-starter-pack create my-rag-agent -a adk -i -ds cloud_sql -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 --agent-directory chatbot

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

### Output Directory

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

## Related Commands

- [`enhance`](./enhance.md) - Add agent capabilities to existing projects (automatically uses `--in-folder`)
- [`list`](./list.md) - List available templates and agents

## See Also

- [Using Remote Templates](../remote-templates/using-remote-templates.md) - Complete guide for using remote templates
- [Creating Remote Templates](../remote-templates/creating-remote-templates.md) - Guide for creating your own templates

---

## File: docs/cli/setup_cicd.md

# `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-east1`).
*   `--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.

--- METRICS ---
- Files Extracted: 4
- Estimated Token Budget: ~9189 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/GoogleCloudPlatform/agent-starter-pack