---

name: google-agents-cli-deploy description: > This skill should be used when the user wants to "deploy an agent", "deploy my ADK agent", "set up CI/CD", "configure secrets", "troubleshoot a deployment", or needs guidance on Agent Runtime, Cloud Run, or GKE deployment targets, or binding an agent to an Agent Gateway. Covers deployment workflows, service accounts, rollback, and production infrastructure. Applies to any framework agents-cli deploys (ADK, LangChain, ...). Part of the agents-cli skills suite. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), evaluation (use google-agents-cli-eval), or project scaffolding (use google-agents-cli-scaffold). metadata: author: Google license: Apache-2.0 version: 1.7.0 requires: bins: - agents-cli install: "uv tool install google-agents-cli"

Deployment Guide

Requires: agents-cli (uv tool install google-agents-cli) — install uv first if needed.

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.

Reference Files

For deeper details, consult these reference files in references/:

• cloud-run.md — Scaling defaults, Dockerfile, session types, networking
• agent-runtime.md — container-based deploy, unified FastAPI app, the /api passthrough, Terraform resource, deployment metadata, CI/CD differences
• gke.md — GKE Autopilot cluster, Kubernetes manifests, Workload Identity, session types, networking
• terraform-patterns.md — Custom infrastructure, IAM, state management, importing resources
• batch-inference.md — BigQuery Remote Function trigger; for Pub/Sub / Eventarc on ADK see /google-agents-cli-adk-code
• cicd-pipeline.md — Full CI/CD pipeline setup, infra cicd flags, runner comparison, WIF auth, pipeline stages
• testing-deployed-agents.md — Testing instructions per deployment target, curl examples, load tests

Observability: See the /google-agents-cli-observability skill for Cloud Trace, prompt-response logging, BigQuery Analytics, and third-party integrations.

---

Deployment Target Decision Matrix

Choose the right deployment target based on your requirements:

| Criteria | Agent Runtime | Cloud Run | GKE | |----------|-------------|-----------|-----| | Scaling | Managed auto-scaling (configurable min/max, concurrency) | Fully configurable (min/max instances, concurrency, CPU allocation) | Full Kubernetes scaling (HPA, VPA, node auto-provisioning) | | 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 | | Session state | Managed Agent Engine sessions (ADK wires VertexAiSessionService automatically) | In-memory (dev), Cloud SQL, or Agent Platform Sessions backend | In-memory (dev), Cloud SQL, or Agent Platform Sessions backend | | Batch/event processing | Trigger endpoints reachable via the Agent Engine /api passthrough | Native trigger endpoints (Pub/Sub, Eventarc); ADK: see /google-agents-cli-adk-code | Custom (Kubernetes Jobs, Pub/Sub) | | Cost model | vCPU-hours + memory-hours (not billed when idle) | Per-instance-second + min instance costs | Node pool costs (always-on or auto-provisioned) | | Setup complexity | Lower (managed, purpose-built for agents) | Medium (Dockerfile, Terraform, networking) | Higher (Kubernetes expertise required) | | Best for | Managed infrastructure, minimal ops | Custom infra, full networking control | Full Kubernetes control |

Ask the user which deployment target fits their needs. Each is a valid production choice with different trade-offs.

All three targets are container-based, so any language works.

Product name mapping: "Agent Engine" / "Vertex AI Agent Engine" is now Agent Runtime. Use --deployment-target agent_runtime.

Ambient / scheduled / event-driven agents (ADK projects): 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.

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. For a worked ADK example, look up OAuth user consent in the topic index in /google-agents-cli-adk-code → references/samples.md.

Live and voice agents: pass --timeout 3600 on Cloud Run so a session outlives the 300s default, and --min-instances 1 on Cloud Run or Agent Runtime so the first caller after idle does not hear a cold start. GKE sizes pods in Terraform. URL shapes and session caps: /google-agents-cli-adk-code (references/adk-python-live.md).

---

Deploying to Dev

Deploy Workflow

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.

1. If prototype (no deployment target), first enhance: agents-cli scaffold enhance . --deployment-target <target>
2. Notify the human: paste the eval scores and test results, then ask "Ready to deploy to dev?"
3. Wait for explicit approval
4. Once approved: agents-cli deploy

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.

IMPORTANT: Never run agents-cli deploy without explicit human approval.

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.

Single-Project Infrastructure Setup (Optional — Advanced)

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.

# Optional — provision infrastructure in a single GCP project
agents-cli infra single-project

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.

Deploy Flag Reference

| Flag | Description | Targets | |------|-------------|---------| | --project | GCP project ID | All | | --region | GCP region | All | | --service-account | Service account email for the deployed agent | All | | --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 | | --secrets | Comma-separated ENV=SECRET or ENV=SECRET:VERSION pairs | Agent Runtime, Cloud Run | | --update-env-vars | Comma-separated KEY=VALUE environment variables | Agent Runtime, Cloud Run | | --agent-identity | Enable Agent Identity | Agent Runtime | | --no-agent-identity | Disable Agent Identity. Passing neither --agent-identity nor --no-agent-identity defaults to no Agent Identity, when a new agent is created, or keeps the current identity type on subsequent re-deployments. | Agent Runtime | | --network-attachment | Network attachment resource name for PSC interface (enables private VPC connectivity) | Agent Runtime | | --dns-peering-domain | DNS peering domain suffix, e.g. my-internal.corp. (requires --network-attachment) | Agent Runtime | | --dns-peering-project | Project ID hosting the Cloud DNS managed zone for DNS peering (requires --network-attachment) | Agent Runtime | | --dns-peering-network | VPC network name in the target project for DNS peering (requires --network-attachment) | Agent Runtime | | --agent-gateway-egress | Bind the agent to an Agent Gateway governing outbound traffic. Full resource name of a gateway with governedAccessPath=AGENT_TO_ANYWHERE. Empty value unbinds; omit to leave unchanged. See Agent Gateway | Agent Runtime | | --agent-gateway-ingress | Bind the agent to an Agent Gateway governing inbound traffic. Full resource name of a gateway with governedAccessPath=CLIENT_TO_AGENT. Empty value unbinds; omit to leave unchanged | Agent Runtime | | --memory | Memory limit (default: 4Gi) | Agent Runtime, Cloud Run | | --cpu | CPU limit (default: 1) | Agent Runtime, Cloud Run | | --min-instances | Minimum number of instances (default: 0, i.e. scale to zero; the generated Terraform uses 1) | Agent Runtime, Cloud Run | | --max-instances | Maximum number of instances (default: 10) | Agent Runtime, Cloud Run | | --concurrency | Concurrent requests per container (default: 8; see Sizing a deployment) | Agent Runtime, Cloud Run | | --timeout | Request timeout in seconds, up to 3600 (Cloud Run default: 300). Applied on create and update; unset leaves the service's current value | Cloud Run | | --port | Container port | Cloud Run, Agent Runtime | | --build-args | Comma-separated KEY=VALUE Docker build args | Agent Runtime | | --labels | Comma-separated KEY=VALUE resource labels. Additive: adds/updates the labels you name; labels you don't name are preserved. | Agent Runtime, Cloud Run | | --framework | Framework the deployed container implements (defaults to framework: in agents-cli-manifest.yaml, which the template sets; google-adk when absent). Sets agent_framework on the deployment, which picks the Google Cloud console playground and the runtime contract the deployment declares. The API owns the accepted values (reference) | Agent Runtime | | --iap | Enable Identity-Aware Proxy | Cloud Run | | --image | Container image URI (skips source build; not supported for Agent Runtime) | Cloud Run, GKE | | --no-wait | Start deployment and return immediately | Agent Runtime, Cloud Run | | --status | Check the status of a pending --no-wait deployment | Agent Runtime, Cloud Run | | --list | List existing deployments and exit | All | | --dry-run / -n | Print what would be executed without run