google-agents-cli-deploy

Name: google-agents-cli-deploy
Author: google

bygoogle· 116 skills

Installs

65k

Stars

5.4k

Forks

565

How to install google-agents-cli-deploy?

google/agents-cli/google-agents-cli-deploy

$npx -y skills add google/agents-cli --skill google-agents-cli-deploy

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/google/agents-cli" --skill "google/agents-cli/google-agents-cli-deploy"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/google/agents-cli" that are relevant to the current task. Run `npx skills add "https://github.com/google/agents-cli"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# ADK Deployment Guide
2
3	> Requires: `agents-cli` (`uv tool install google-agents-cli`) — [install uv](https://docs.astral.sh/uv/getting-started/installation/index.md) first if needed.
4
5	> Prefer using the `agents-cli` commands throughout this guide — they wrap Terraform, Docker, and deployment into a tested pipeline. If your project isn't scaffolded yet, see `/google-agents-cli-scaffold` to add deployment support first.
6
7	### Reference Files
8
9	For deeper details, consult these reference files in `references/`:
10
11	- `cloud-run.md` — Scaling defaults, Dockerfile, session types, networking
12	- `agent-runtime.md` — container-based deploy, unified FastAPI app, the `/api` passthrough, Terraform resource, deployment metadata, CI/CD differences
13	- `gke.md` — GKE Autopilot cluster, Kubernetes manifests, Workload Identity, session types, networking
14	- `terraform-patterns.md` — Custom infrastructure, IAM, state management, importing resources
15	- `batch-inference.md` — BigQuery Remote Function trigger; for Pub/Sub / Eventarc see `/google-agents-cli-adk-code`
16	- `cicd-pipeline.md` — Full CI/CD pipeline setup, `infra cicd` flags, runner comparison, WIF auth, pipeline stages
17	- `testing-deployed-agents.md` — Testing instructions per deployment target, curl examples, load tests
18
19	> Observability: See the `/google-agents-cli-observability` skill for Cloud Trace, prompt-response logging, BigQuery Analytics, and third-party integrations.
20
21	---
22
23	## Deployment Target Decision Matrix
24
25	Choose the right deployment target based on your requirements:
26
27	\| Criteria \| Agent Runtime \| Cloud Run \| GKE \|
28	\|----------\|-------------\|-----------\|-----\|
29	\| Scaling \| Managed auto-scaling (configurable min/max, concurrency) \| Fully configurable (min/max instances, concurrency, CPU allocation) \| Full Kubernetes scaling (HPA, VPA, node auto-provisioning) \|
30	\| Networking \| VPC-SC and PSC-I supported (private VPC connectivity via network attachments) \| Full VPC support, direct VPC egress, IAP, ingress rules \| Full Kubernetes networking \|
31	\| Session state \| Native `VertexAiSessionService` (persistent, managed) \| In-memory (dev), Cloud SQL, or Agent Platform Sessions backend \| In-memory (dev), Cloud SQL, or Agent Platform Sessions backend \|
32	\| Batch/event processing \| Trigger endpoints reachable via the Agent Engine `/api` passthrough \| Native trigger endpoints (Pub/Sub, Eventarc); see `/google-agents-cli-adk-code` \| Custom (Kubernetes Jobs, Pub/Sub) \|
33	\| Cost model \| vCPU-hours + memory-hours (not billed when idle) \| Per-instance-second + min instance costs \| Node pool costs (always-on or auto-provisioned) \|
34	\| Setup complexity \| Lower (managed, purpose-built for agents) \| Medium (Dockerfile, Terraform, networking) \| Higher (Kubernetes expertise required) \|
35	\| Best for \| Managed infrastructure, minimal ops \| Custom infra, full networking control \| Full Kubernetes control \|
36
37	Ask the user which deployment target fits their needs. Each is a valid production choice with different trade-offs.
38
39	All three targets are container-based, so any language works.
40
41	> Product name mapping: "Agent Engine" / "Vertex AI Agent Engine" is now Agent Runtime. Use `--deployment-target agent_runtime`.
42
43	> Ambient / scheduled / event-driven agents: ADK's `trigger_sources` registers `/apps/{app}/trigger/` endpoints on the same FastAPI app for all* targets. On Cloud Run / GKE these are public HTTP routes you point a Pub/Sub push subscription or Eventarc trigger at; on Agent Runtime the same routes are reachable through the Agent Engine `/api` passthrough (e.g. `.../reasoningEngines/v1/{resource}/api/apps/{app}/trigger/pubsub`). Cloud Run remains the simplest target for unauthenticated trigger sources. See `/google-agents-cli-adk-code` (`references/adk-python.md`, section "12. Event-Driven / Ambient Agents") for the `trigger_sources` pattern.
44
45	> OAuth / user consent agents: Use Agent Runtime with Gemini Enterprise for agents that need OAuth 2.0 user consent (e.g., accessing Google Drive, Calendar, or other user-scoped APIs). Cloud Run does not currently support managed OAuth flows. See the `adk-ae-oauth` sample in the `/google-agents-cli-workflow` sample catalog (Phase 1).
46
47	---
48
49	## Deploying to Dev
50
51	### Deploy Workflow
52
53	Task tracking: Deployment involves multiple sequential steps (infra setup, CI/CD configuration, deploy, verification). Use a task list to track progress through these steps — skipping one often causes failures in later steps that are hard to trace back.
54
55	1. If prototype (no deployment target), first enhance: `agents-cli scaffold enhance . --deployment-target <target>`
56	2. Notify the human: "Eval scores meet thresholds and tests pass. Ready to deploy to dev?"
57	3. Wait for explicit approval
58	4. Once approved: `agents-cli deploy`
59
60	> Agent Runtime timeout recovery: Agent Runtime deploys can take 5-10 minutes and may exceed command timeouts. If the deploy command is cancelled or times out, the deployment continues server-side. Run `agents-cli deploy --status` to check progress — poll every 60 seconds until it reports completion or failure.
61
62	IMPORTANT: Never run `agents-cli deploy` without explicit human approval.
63
64	> Do NOT run `agents-cli infra single-project` before deploying. It is not a prerequisite — `agents-cli deploy` works on its own. Run it separately if the user needs observability features (prompt-response logging, BigQuery analytics) — see `/google-agents-cli-observability`.
65
66	### Single-Project Infrastructure Setup (Optional — Advanced)
67
68	`agents-cli infra single-project` runs `terraform apply` in `deployment/terraform/single-project/`. Use this to provision single-project GCP infrastructure without CI/CD (service accounts, IAM bindings, telemetry resources, Artifact Registry). Also useful to test things in a single project before going to production. It is NOT required for deploying.
69
70	```bash
71	# Optional — provision infrastructure in a single GCP project
72	agents-cli infra single-project
73	```
74
75	> Note: `agents-cli deploy` doesn't automatically use the Terraform-created `app_sa`. Pass the service account explicitly: `agents-cli deploy --service-account SA_EMAIL`.
76
77	### Deploy Flag Reference
78
79	\| Flag \| Description \| Targets \|
80	\|------\|-------------\|---------\|
81	\| `--project` \| GCP project ID \| All \|
82	\| `--region` \| GCP region \| All \|
83	\| `--service-account` \| Service account email for the deployed agent \| All \|
84	\| `--service-name` \| Override the deployed service name (Cloud Run service or Agent Runtime display name); defaults to the project name. If you override it, consider updating your Terraform and CI (if present) — they name resources from the project name. Not supported for GKE, whose names are fully owned by Terraform. \| Agent Runtime, Cloud Run \|
85	\| `--secrets` \| Comma-separated `ENV=SECRET` or `ENV=SECRET:VERSION` pairs \| Agent Runtime, Cloud Run \|
86	\| `--update-env-vars` \| Comma-separated `KEY=VALUE` environment variables \| Agent Runtime, Cloud Run \|
87	\| `--agent-identity` \| Enable [agent identity](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity) (Preview) \| Agent Runtime \|
88	\| `--network-attachment` \| Network attachment resource name for [PSC interface](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/private-service-connect-interface) (enables private VPC connectivity) \| Agent Runtime \|
89	\| `--dns-peering-domain` \| DNS peering domain suffix, e.g. `my-internal.corp.` (requires `--network-attachment`) \| Agent Runtime \|
90	\| `--dns-peering-project` \| Project ID hosting the Cloud DNS managed zone for DNS peering (requires `--network-attachment`) \| Agent Runtime \|
91	\| `--dns-peering-network` \| VPC network name in the target project for DNS peering (requires `--network-attachment`) \| Agent Runtime \|
92	\| `--memory` \| Memory limit (default: `4Gi`) \| Agent Runtime, Cloud Run \|
93	\| `--cpu` \| CPU limit (default: `1`) \| Agent Runtime, Cloud Run \|
94	\| `--min-instances` \| Minimum number of instances (default: `1`) \| Agent Runtime, Cloud Run \|
95	\| `--max-instances` \| Maximum number of instances (default: `10`) \| Agent Runtime, Cloud Run \|
96	\| `--concurrency` \| Concurrent requests per container (default: `8`; see [Sizing a deployment](#sizing-a-deployment)) \| Agent Runtime, Cloud Run \|
97	\| `--port` \| Container port \| Cloud Run, Agent Runtime \|
98	\| `--build-args` \| Comma-separated `KEY=VALUE` Docker build args \| Agent Runtime \|
99	\| `--iap` \| Enable Identity-Aware Proxy \| Cloud Run \|
100	\| `--image` \| Container image URI (skips source build; not supported for Agent Runtime) \| Cloud Run, GKE \|
101	\| `--no-wait` \| Start deployment and return immediately \| Agent Runtime, Cloud Run \|
102	\| `--status` \| Check the status of a pending `--no-wait` deployment \| Agent Runtime, Cloud Run \|
103	\| `--list` \| List existing deployments and exit \| All \|
104	\| `--dry-run` / `-n` \| Print what would be executed without running it \| All \|
105	\| `--no-confirm-project` \| Skip project confirmation prompt \| All \|
106
107	Run `agents-cli deploy --help` for the full flag reference.
108
109	> Advanced Cloud Run Deploys: If you need features not exposed via `agents-cli` flags, use `--dry-run` (or `-n`) to print the full `gcloud` command, copy it, and add additional arguments as needed.
110
111	> Project Confirmation: If the project is resolved automatically (not passed via `--project`), the command will prompt for confirmation in interactive mode. Since agents typically run in non-interactive mode, you MUST pass `--no-confirm-project` to proceed if you are relying on automatic project resolution.
112
113	---
114
115	## Sizing a deployment
116
117	Defaults (same on Agent Runtime, Cloud Run, and the generated `service.tf`): `--cpu 1`, `--memory 4Gi`, `--concurrency 8`, `--min-instances 1`, `--max-instances 10`.
118
119	The params are coupled — scale them together:
120
121	- One async process — scale out, not up. The container runs a single `uvicorn` process that serves many requests concurrently on the event loop, so throughput comes from `--concurrency` and horizontal scale (`--max-instances`), not extra worker processes. Raise `--cpu` only if profiling shows the event loop or synchronous tool calls are CPU-bound.
122	- Memory bounds concurrency. Each concurrent request keeps its full working set (context window, history, RAG chunks, response buffer) in memory while it waits on the model, so peak ≈ base + `concurrency × per-request memory`. Memory — not CPU — is the first limit, so raising `--concurrency` without `--memory` is the main OOM cause.
123	- Concurrency default is conservative. An async worker can serve many concurrent requests while it waits on the model, but per-request memory is agent-specific, so `8` protects a memory-heavy (RAG/multimodal) agent. Light agents can raise it to 16–32+ after load-testing. See [Underutilized asynchronous workers](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/optimize-and-scale#underutilized-workers).
124
125	```bash
126	# 4x throughput: scale every param, not just one
127	agents-cli deploy --cpu 4 --concurrency 16 --memory 16Gi --max-instances 20
128	```
129
130	Tune with the scaffolded load test (`tests/load_test/`, run locally or in the CI/CD staging pipeline): drive load, watch max latency and memory/OOM restarts, then adjust — high max latency → raise concurrency (+ workers/cpu); OOM → raise memory or lower concurrency.
131
132	> On GKE these sizing flags are rejected — size via the Terraform manifests + HorizontalPodAutoscaler under `deployment/terraform/`.
133
134	---
135
136	## Production Deployment — CI/CD Pipeline
137
138	For the full CI/CD pipeline setup guide — prerequisites, `infra cicd` flags, runner comparison, WIF authentication, pipeline stages, and production approval — see `references/cicd-pipeline.md`.
139
140	---
141
142	## Cloud Run Specifics
143
144	For detailed infrastructure configuration (scaling defaults, Dockerfile, FastAPI endpoints, session types, networking), see `references/cloud-run.md`. For ADK docs on Cloud Run deployment, fetch `https://adk.dev/deploy/cloud-run/index.md`.
145
146	For event-driven / ambient agent deployment on Cloud Run, see the [`ambient-expense-agent`](https://github.com/google/adk-samples/tree/main/python/agents/ambient-expense-agent) sample and `/google-agents-cli-adk-code` (`references/adk-python.md`, section "12. Event-Driven / Ambient Agents") for the `trigger_sources` pattern.
147
148	---
149
150	## Agent Runtime Specifics
151
152	Agent Runtime is a managed Vertex AI service for deploying Python ADK agents. Uses container-based deployment: `agents-cli deploy` packages your project and Agent Engine builds the image from your project's `Dockerfile` (required) — the same `fast_api_app:app` image that serves Cloud Run and GKE.
153
154	> No `gcloud` CLI exists for Agent Runtime. Deploy via `agents-cli deploy`. Query via the Python `vertexai.Client` SDK.
155
156	Deployments can take 5-10 minutes. Use `--no-wait` to start a deployment and return immediately, then check on it later with `--status`:
157
158	```bash
159	# Start deployment without blocking
160	agents-cli deploy --no-wait
161
162	# Check on progress later
163	agents-cli deploy --status
164	```
165
166	When `--status` detects the operation has completed, it writes `deployment_metadata.json` and prints the same success output as a normal deploy.
167
168	For detailed infrastructure configuration (container deploy flow, the unified FastAPI app and `/api` passthrough, Terraform resource, deployment metadata, session/artifact services, CI/CD differences), see `references/agent-runtime.md`. For ADK docs on Agent Runtime deployment, fetch `https://adk.dev/deploy/agent-runtime/index.md`.
169
170	---
171
172	## GKE Specifics
173
174	For detailed infrastructure configuration (Kubernetes manifests, Terraform resources, Workload Identity, session types, networking), see `references/gke.md`. For ADK docs on GKE deployment, fetch `https://adk.dev/deploy/gke/index.md`.
175
176	---
177
178	## Service Account Architecture
179
180	Scaffolded projects use two service accounts:
181
182	- `app_sa` (per environment) — Runtime identity for the deployed agent. Roles defined in `deployment/terraform/iam.tf`.
183	- `cicd_runner_sa` (CI/CD project) — CI/CD pipeline identity (GitHub Actions / Cloud Build). Lives in the CI/CD project (defaults to prod project), needs permissions in both staging and prod projects.
184
185	Check `deployment/terraform/iam.tf` for exact role bindings. Cross-project permissions (Cloud Run service agents, artifact registry access) are also configured there.
186
187	Common 403 errors:
188	- "Permission denied on Cloud Run" → `cicd_runner_sa` missing deployment role in the target project
189	- "Cannot act as service account" → Missing `iam.serviceAccountUser` binding on `app_sa`
190	- "Secret access denied" → `app_sa` missing `secretmanager.secretAccessor`
191	- "Cloud SQL connection failed / Not authorized" → Runtime service account missing `roles/cloudsql.client`
192	- "Artifact Registry read denied" → Cloud Run service agent missing read access in CI/CD project
193
194	---
195
196	## Required Permissions for CI/CD Setup
197
198	- `roles/secretmanager.admin` granted to the Cloud Build service account (`service-<PROJECT_NUMBER>@gcp-sa-cloudbuild.iam.gserviceaccount.com`) in the CI/CD project. This allows Cloud Build to access the GitHub token stored in Secret Manager.
199
200	---
201
202	## Required APIs
203
204	The following Google Cloud APIs must be enabled in your project for the skills and deployment to work:
205
206	- `cloudbuild.googleapis.com` — Required for building container images and running CI/CD pipelines.
207	- `secretmanager.googleapis.com` — Required for managing secrets and API keys.
208	- `run.googleapis.com` — Required for deploying to Cloud Run.
209
210	Ensure these are enabled before running deployment or CI/CD setup commands:
211	```bash
212	gcloud services enable cloudbuild.googleapis.com secretmanager.googleapis.com run.googleapis.com --project=YOUR_PROJECT_ID
213	```
214
215	---
216
217	## Secret Manager (for API Credentials)
218
219	Instead of passing sensitive keys as environment variables, use GCP Secret Manager.
220
221	```bash
222	# Create a secret
223	echo -n "YOUR_API_KEY" \| gcloud secrets create MY_SECRET_NAME --data-file=-
224
225	# Update an existing secret
226	echo -n "NEW_API_KEY" \| gcloud secrets versions add MY_SECRET_NAME --data-file=-
227	```
228
229	Grant access: For Cloud Run, grant `secretmanager.secretAccessor` to `app_sa`. For Agent Runtime, grant it to the platform-managed SA (`service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com`). For GKE, grant `secretmanager.secretAccessor` to `app_sa`. Access secrets via Kubernetes Secrets or directly via the Secret Manager API with Workload Identity.
230
231	Pass secrets at deploy time (Agent Runtime, Cloud Run):
232	```bash
233	agents-cli deploy --secrets "API_KEY=my-api-key,DB_PASS=db-password:2"
234	```
235
236	Format: `ENV_VAR=SECRET_ID` or `ENV_VAR=SECRET_ID:VERSION` (defaults to latest). Access in code via `os.environ.get("API_KEY")`.
237
238	---
239
240	## Cloud SQL Permissions (Manual Deployment)
241
242	When using Cloud SQL with Cloud Run in a manual deployment (e.g., adding `--add-cloudsql-instances` in non-Terraform setups), you must manually grant the `Cloud SQL Client` role to the runtime service account.
243
244	Without this, the deployment may succeed but fail at runtime with `cloudsql.instances.get` authorization errors.
245
246	```bash
247	gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
248	--member="serviceAccount:YOUR_RUNTIME_SA_EMAIL" \
249	--role="roles/cloudsql.client"
250	```
251
252	> Note: In full Terraform-managed setups (`infra cicd` / `infra single-project`), this role is configured and managed automatically.
253
254	---
255
256	## Observability
257
258	See the agents-cli-observability skill for observability configuration (Cloud Trace, prompt-response logging, BigQuery Analytics, third-party integrations).
259
260	---
261
262	## Testing Your Deployed Agent
263
264	The quickest way to test a deployed agent is `agents-cli run --url <service-url> --mode <a2a\|adk> "your prompt"` — it handles auth, sessions, and streaming automatically (supports Agent Runtime and Cloud Run).
265
266	For advanced testing (custom headers, session reuse, scripting, load tests), see `references/testing-deployed-agents.md`.
267
268	---
269
270	## Deploying with a UI (IAP)
271
272	IAP (Identity-Aware Proxy) secures a Cloud Run service so only authorized Google accounts can access it. Enable it by adding the `--iap` flag when deploying (Cloud Run only): `agents-cli deploy --iap`.
273
274	For Agent Runtime with a custom frontend, use a decoupled deployment — deploy the frontend separately to Cloud Run or Cloud Storage, connecting to the Agent Runtime backend API.
275
276	For more information on IAP with Cloud Run, see the [Cloud Console IAP settings](https://cloud.google.com/run/docs/securing/identity-aware-proxy-cloud-run#manage_user_or_group_access).
277
278	---
279
280	## Rollback & Recovery
281
282	The primary rollback mechanism is git-based: fix the issue, commit, and push to `main`. The CI/CD pipeline will automatically build and deploy the new version through staging → production.
283
284	For immediate Cloud Run rollback without a new commit, use revision traffic shifting:
285	```bash
286	gcloud run revisions list --service=SERVICE_NAME --region=REGION
287	gcloud run services update-traffic SERVICE_NAME \
288	--to-revisions=REVISION_NAME=100 --region=REGION
289	```
290
291	Agent Runtime doesn't support revision-based rollback — fix and redeploy via `agents-cl

6 picks

Type

Run `npx skills use "https://github.com/google/agents-cli" --skill "google/agents-cli/google-agents-cli-deploy"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/google/agents-cli" that are relevant to the current task. Run `npx skills add "https://github.com/google/agents-cli"` and select the relevant skills, then follow their instructions.

google-agents-cli-deploy

How to install google-agents-cli-deploy?

Related

google-agents-cli-deploy

How to install google-agents-cli-deploy?

Related