# GCP Best Practices — propane-will-491900-m5

## Platform context (2025–2026)
- **Vertex AI Agent Engine** has been rebranded as **Gemini Enterprise Agent Platform**.
  Agent runtimes are fully managed serverless — no VM management required.
- **ADK (Agent Development Kit)** 2.0 is open-source, supports Python/TypeScript/Go/Java/Kotlin.
  Agents run locally for dev, then deploy to Agent Runtime, Cloud Run, or GKE.
- Region: **us-central1** for all resources (low latency, widest feature availability).

## Required APIs (enable once, idempotent)
```
aiplatform.googleapis.com           # Vertex AI / Gemini Agent Platform
storage.googleapis.com              # Cloud Storage staging
cloudbilling.googleapis.com         # Billing Budget API
cloudresourcemanager.googleapis.com
iam.googleapis.com
run.googleapis.com                  # If using Cloud Run as deploy target
monitoring.googleapis.com
logging.googleapis.com
cloudtrace.googleapis.com
secretmanager.googleapis.com
artifactregistry.googleapis.com
cloudbuild.googleapis.com
```

## ADK install
```bash
pip install google-adk>=2.0.0 google-cloud-aiplatform[adk,agent_engines]>=1.112.0
gcloud components update
gcloud auth application-default login
```

## Deploy targets — decision matrix
| Target | Best for | Cost model | Auth |
|---|---|---|---|
| **Agent Runtime** (managed) | Production agents, Memory Bank, Sessions | Per vCPU-second + GiB-second | ADC / SA |
| **Cloud Run** | Custom containers, public API endpoints, lower ops | Pay-per-request, scales to 0 | ADC / SA |
| **GKE** | Complex multi-agent meshes, custom networking | Cluster uptime + node cost | Workload Identity |

## ADK 2.0 — new in 2026
- Graph workflows and collaborative agents (coordinator + sub-agents)
- **ADK Kotlin** — new language support
- `adk deploy cloud_run` and `adk deploy agent_engine` CLI commands
- Native MCP client and server support
- A2A (Agent-to-Agent) protocol support
- `SecretManagerClient` integration (requires ADK ≥ 1.29)

## Four platform pillars (Gemini Enterprise Agent Platform)
| Pillar | Key features |
|---|---|
| **Build** | ADK 2.0, Agent Studio (visual designer), Agents CLI, 200+ models via Model Garden |
| **Scale** | Agent Runtime, Sessions, Memory Bank, Code Execution, multi-day workflows |
| **Govern** | Agent Identity, Agent Registry, Agent Gateway, Model Armor, Agent Security dashboard |
| **Optimize** | Agent Evaluation, Agent Optimizer (auto-clusters failures), Example Store, Observability |

## Model landscape (May 2026)
| Model | Status | Recommended use |
|---|---|---|
| `gemini-2.5-flash` | GA | Balanced cost/quality — **recommended default** |
| `gemini-3-flash` | Public preview | Cheapest option for dev/test |
| `gemma-4` | GA (open-source) | Self-hosted / fine-tuning |
| ~~`gemini-1.5-*`~~ | **Discontinued** | Migrate immediately |
| ~~`claude-3.5-haiku`~~ | **Deprecated** (shutdown Jul 2026) | Migrate immediately |

## agent-starter-pack (Google official)
```bash
uvx agent-starter-pack enhance   # add CI/CD + eval + observability to existing agent
uvx agent-starter-pack create my-agent  # scaffold from scratch
```
Provides: CI/CD (Cloud Build), Evaluation, Observability, Terraform IaC out of the box.
GitHub: https://github.com/GoogleCloudPlatform/agent-starter-pack

## Key constraints
- Never use GPU instances (A100/V100) unless business-critical.
- Default compute: `e2-micro` for background tasks, up to `e2-standard-4` for Colab.
- Agent Runtimes bill when deployed — always run `03-teardown.sh` at end of day.
- Cloud Storage buckets do NOT auto-delete — lifecycle rules are mandatory.