[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69904JP7GH5TSBDZFAAZQ92":3,"skill-same:01M69904JP7GH5TSBDZFAAZQ92":124},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":34,"publishedAt":54,"linkOnly":55,"markdownContent":56,"markdownBody":57,"frontMatter":58,"refName":66,"commitSha":67,"skillDirectory":68,"forksCount":69,"repositoryHtmlUrl":70,"repositoryHomepageUrl":71,"ownerHtmlUrl":72,"ownerBlogUrl":73,"ownerDescription":74,"updatedAt":75,"install":76,"resources":89},"01M69904JP7GH5TSBDZFAAZQ92","google-agents-cli-deploy",null,"This skill should be used when the user wants to \"deploy an agent\", \"deploy my ADK agent\", \"set up CI\u002FCD\", \"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).","google\u002Fagents-cli","google","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1342004?v=4","01M698VYEFDM0VJBZDYYJ2T83S","Google","01M698ZVGDEBGAXVZGNKKKCRBQ",6349,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fskills\u002Fgoogle-agents-cli-deploy\u002FSKILL.md",[18,23,26,29],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000011","运维与部署",{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":30,"categoryName":31,"taxonomyType":32,"taxonomyTypeDesc":33},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[35,36,9,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53],"google agents cli deploy","cli","deploy","deployment","for","cloud run","do","infrastructure","langchain","Evaluation","run","gke","code patterns","workflows","uv","eval","ci","project","adk","2026-11-10 10:12:30",false,"---\nname: google-agents-cli-deploy\ndescription: >\n  This skill should be used when the user wants to \"deploy an agent\",\n  \"deploy my ADK agent\", \"set up CI\u002FCD\", \"configure secrets\",\n  \"troubleshoot a deployment\", or needs guidance on Agent Runtime,\n  Cloud Run, or GKE deployment targets, or binding an agent to an Agent Gateway.\n  Covers deployment workflows, service accounts, rollback, and production infrastructure.\n  Applies to any framework agents-cli deploys (ADK, LangChain, ...).\n  Part of the agents-cli skills suite.\n  Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), evaluation\n  (use google-agents-cli-eval), or project scaffolding (use google-agents-cli-scaffold).\nmetadata:\n  author: Google\n  license: Apache-2.0\n  version: 1.14.0\n  requires:\n    bins:\n      - agents-cli\n    install: \"uv tool install google-agents-cli\"\n---\n\n# Deployment Guide\n\n> **Requires:** `agents-cli` (`uv tool install google-agents-cli`) — [install uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002Fgetting-started\u002Finstallation\u002Findex.md) first if needed.\n\n> 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 `\u002Fgoogle-agents-cli-scaffold` to add deployment support first.\n\n### Reference Files\n\nFor deeper details, consult these reference files in `references\u002F`:\n\n- **`cloud-run.md`** — Scaling defaults, Dockerfile, session types, networking\n- **`agent-runtime.md`** — container-based deploy, unified FastAPI app, the `\u002Fapi` passthrough, Terraform resource, deployment metadata, CI\u002FCD differences\n- **`gke.md`** — GKE Autopilot cluster, Kubernetes manifests, Workload Identity, session types, networking\n- **`terraform-patterns.md`** — Custom infrastructure, IAM, state management, importing resources\n- **`batch-inference.md`** — BigQuery Remote Function trigger; for Pub\u002FSub \u002F Eventarc on ADK see `\u002Fgoogle-agents-cli-adk-code`\n- **`cicd-pipeline.md`** — Full CI\u002FCD pipeline setup, `infra cicd` flags, runner comparison, WIF auth, pipeline stages\n- **`testing-deployed-agents.md`** — Testing instructions per deployment target, curl examples, load tests\n- **`cmek.md`** — Customer-managed encryption keys on Agent Runtime in Gemini platform: key grants, `deploy --key` for dev, Terraform edits for staging\u002Fprod\n\n> **Observability:** See the `\u002Fgoogle-agents-cli-observability` skill for Cloud Trace, prompt-response logging, BigQuery Analytics, and third-party integrations.\n\n---\n\n## Deployment Target Decision Matrix\n\nChoose the right deployment target based on your requirements:\n\n| Criteria | Agent Runtime | Cloud Run | GKE |\n|----------|-------------|-----------|-----|\n| **Scaling** | Managed auto-scaling (configurable min\u002Fmax, concurrency) | Fully configurable (min\u002Fmax instances, concurrency, CPU allocation) | Full Kubernetes scaling (HPA, VPA, node auto-provisioning) |\n| **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 |\n| **Session state** | Sessions in Gemini platform (ADK wires `VertexAiSessionService` automatically) | In-memory (dev), Cloud SQL, or a managed sessions backend | In-memory (dev), Cloud SQL, or a managed sessions backend |\n| **Batch\u002Fevent processing** | Trigger endpoints reachable via the Agent Runtime `\u002Fapi` passthrough | Native trigger endpoints (Pub\u002FSub, Eventarc); ADK: see `\u002Fgoogle-agents-cli-adk-code` | Custom (Kubernetes Jobs, Pub\u002FSub) |\n| **Cost model** | vCPU-hours + memory-hours (not billed when idle) | Per-instance-second + min instance costs | Node pool costs (always-on or auto-provisioned) |\n| **Setup complexity** | Lower (managed, purpose-built for agents) | Medium (Dockerfile, Terraform, networking) | Higher (Kubernetes expertise required) |\n| **Best for** | Managed infrastructure, minimal ops | Custom infra, full networking control | Full Kubernetes control |\n\n**Ask the user** which deployment target fits their needs. Each is a valid production choice with different trade-offs.\n\nAll three targets are container-based, so any language works.\n\n> **Product name mapping:** users may say \"Agent Engine\", \"Vertex AI Agent Engine\", or \"Agent Runtime\"; all mean Agent Runtime. Use `--deployment-target agent_runtime`.\n\n> **Ambient \u002F scheduled \u002F event-driven agents (ADK projects):** ADK's `trigger_sources` registers `\u002Fapps\u002F{app}\u002Ftrigger\u002F*` endpoints on the same FastAPI app for **all** targets. On **Cloud Run** \u002F **GKE** these are public HTTP routes you point a Pub\u002FSub push subscription or Eventarc trigger at; on **Agent Runtime** the same routes are reachable through its `\u002Fapi` passthrough (e.g. `...\u002FreasoningEngines\u002Fv1\u002F{resource}\u002Fapi\u002Fapps\u002F{app}\u002Ftrigger\u002Fpubsub`). Cloud Run remains the simplest target for unauthenticated trigger sources. See `\u002Fgoogle-agents-cli-adk-code` (`references\u002Fadk-python.md`, section \"12. Event-Driven \u002F Ambient Agents\") for the `trigger_sources` pattern.\n\n> **OAuth \u002F user consent agents:** Use **Agent Runtime**, registered with Gemini, 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 `\u002Fgoogle-agents-cli-adk-code` → `references\u002Frecipes.md`.\n\n> **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: `\u002Fgoogle-agents-cli-adk-code` (`references\u002Fadk-python-live.md`).\n\n---\n\n## Deploying to Dev\n\n### Deploy Workflow\n\n**Task tracking:** Deployment involves multiple sequential steps (infra setup, CI\u002FCD 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.\n\n1. If prototype (no deployment target), first enhance: `agents-cli scaffold enhance . --deployment-target \u003Ctarget>`\n2. **Notify the human**: paste the eval scores and test results, then ask \"Ready to deploy to dev?\"\n3. **Wait for explicit approval**\n4. Once approved: `agents-cli deploy`\n\n> **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.\n\n**IMPORTANT**: Never run `agents-cli deploy` without explicit human approval.\n\n> **Not a prerequisite.** `agents-cli deploy` works on its own. One exception: if the user wants Terraform-managed observability (prompt-response logging, BigQuery analytics), run `agents-cli infra single-project --apply` first, see `\u002Fgoogle-agents-cli-observability`.\n\n### Single-Project Infrastructure Setup (Optional — Advanced)\n\n`agents-cli infra single-project --apply` runs `terraform apply` in `deployment\u002Fterraform\u002Fsingle-project\u002F`. Use this to **provision single-project GCP infrastructure without CI\u002FCD** (service accounts, IAM bindings, telemetry resources, Artifact Registry). It is required before deployment only when Terraform will manage observability; basic Agent Runtime and Cloud Run deployments do not need it, while GKE deploy handles its own targeted Terraform.\n\n```bash\n# Optional — provision infrastructure in a single GCP project\nagents-cli infra single-project --apply\n```\n\n> **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`. With Agent Identity, `--service-account` is ignored.\n\n### Deploy Flag Reference\n\n| Flag | Description | Targets |\n|------|-------------|---------|\n| `--project` | GCP project ID | All |\n| `--region` | GCP region | All |\n| `--service-account` | Service account email for the deployed agent | All |\n| `--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 |\n| `--secrets` \u002F `--update-secrets` | Comma-separated `ENV=SECRET` or `ENV=SECRET:VERSION` pairs. Cloud Run adds them to the service's existing secrets; Agent Runtime replaces the agent's existing secrets with the ones you pass. | Agent Runtime, Cloud Run |\n| `--remove-secrets` | Comma-separated secret `KEY`s to remove. Keys that don't exist are ignored. A key can't also be in `--secrets`. Cannot be combined with `--clear-secrets`. | Agent Runtime, Cloud Run |\n| `--clear-secrets` | Remove all secrets, including ones set outside agents-cli (e.g. Terraform's `DB_PASS` for Cloud SQL sessions) and, on Cloud Run, secrets mounted as volumes. Combine with `--secrets` to replace the secret set; the clear is applied first. Cannot be combined with `--remove-secrets`. | Agent Runtime, Cloud Run |\n| `--env-vars` \u002F `--update-env-vars` | Comma-separated `KEY=VALUE` environment variables to add or update, applied on top of the project `.env` (which every deploy propagates). On GKE, a deploy without `--image` first resets the env vars to Terraform's, so values passed on earlier deploys are dropped; keep lasting ones in `.env` or Terraform. | All |\n| `--remove-env-vars` | Comma-separated env var `KEY`s to remove. Keys that don't exist are ignored. A key can't also be in `--env-vars` or the project `.env` (delete it from `.env` instead). Defaults agents-cli sets on every deploy (e.g. `AGENT_VERSION`, `APP_URL`) are kept. Cannot be combined with `--clear-env-vars`. | Agent Runtime, Cloud Run |\n| `--clear-env-vars` | Remove all env vars, including ones set outside agents-cli (e.g. Terraform's `LOGS_BUCKET_NAME` and `OTEL_*`); secrets are kept. The project `.env`, `--env-vars` and agents-cli's defaults are applied after the clear. Cannot be combined with `--remove-env-vars`. Not on GKE, where Terraform manages the deployment's env vars. | Agent Runtime, Cloud Run |\n| `--agent-identity` | Enable [Agent Identity](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fscale\u002Fruntime\u002Fagent-identity) | Agent Runtime, Cloud Run |\n| `--no-agent-identity` | Disable Agent Identity. Passing neither `--agent-identity` nor `--no-agent-identity` follows the project's identity default in `agents-cli-manifest.yaml` when the agent is created, or keeps the current identity type on later deploys. On Cloud Run, Agent Identity can't be turned off: for a service that already has it, the deploy stops and asks you to delete the service and redeploy. | Agent Runtime, Cloud Run |\n| `--network-attachment` | Network attachment resource name for [PSC interface](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fscale\u002Fruntime\u002Fprivate-service-connect-interface) (enables private VPC connectivity) | Agent Runtime |\n| `--dns-peering-domain` | DNS peering domain suffix, e.g. `my-internal.corp.` (requires `--network-attachment`) | Agent Runtime |\n| `--dns-peering-project` | Project ID hosting the Cloud DNS managed zone for DNS peering (requires `--network-attachment`) | Agent Runtime |\n| `--dns-peering-network` | VPC network name in the target project for DNS peering (requires `--network-attachment`) | Agent Runtime |\n| `--agent-gateway-egress` | Bind the agent to an [Agent Gateway](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fagent-gateway-overview) 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-gateway) | Agent Runtime |\n| `--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 |\n| `--key` | Cloud KMS key for customer-managed encryption (CMEK), as a full `projects\u002FPROJECT\u002Flocations\u002FREGION\u002FkeyRings\u002FRING\u002FcryptoKeys\u002FKEY` name. Set on create only; for dev deployments (staging\u002Fprod set the key in Terraform). See [Customer-managed encryption](#customer-managed-encryption-cmek) | Agent Runtime |\n| `--memory` | Memory limit (default: `4Gi`) | Agent Runtime, Cloud Run |\n| `--cpu` | CPU limit (default: `1`) | Agent Runtime, Cloud Run |\n| `--min-instances` | Minimum number of instances (default: `0`, i.e. scale to zero; the generated Terraform uses `1`) | Agent Runtime, Cloud Run |\n| `--max-instances` | Maximum number of instances (default: `10`) | Agent Runtime, Cloud Run |\n| `--concurrency` | Concurrent requests per container (default: `8`; see [Sizing a deployment](#sizing-a-deployment)) | Agent Runtime, Cloud Run |\n| `--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 |\n| `--port` | Container port | Cloud Run, Agent Runtime |\n| `--build-args` | Comma-separated `KEY=VALUE` Docker build args | Agent Runtime |\n| `--labels` \u002F `--update-labels` | Comma-separated `KEY=VALUE` resource labels to add or update. Additive: adds\u002Fupdates the labels you name; labels you don't name are preserved. | Agent Runtime, Cloud Run |\n| `--remove-labels` | Comma-separated label `KEY`s to remove. Keys that don't exist are ignored. Can be combined with `--labels`, but a key can't appear in both. Cannot be combined with `--clear-labels`. | Agent Runtime, Cloud Run |\n| `--clear-labels` | Remove all resource labels (Cloud Run keeps its reserved `created-by` label). Combine with `--labels` to replace the label set; the clear is applied first. Cannot be combined with `--remove-labels`. | Agent Runtime, Cloud Run |\n| `--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](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Freference\u002Frest\u002Fv1\u002Fprojects.locations.reasoningEngines#ReasoningEngineSpec)) | Agent Runtime |\n| `--iap` | Enable Identity-Aware Proxy | Cloud Run |\n| `--image` | Prebuilt container image URI (skips source build). On Agent Runtime the image must be in Artifact Registry and readable by the Agent Runtime service agent (`roles\u002Fartifactregistry.reader`); can't be combined with `--build-args` | All |\n| `--no-wait` | Start deployment and return immediately | Agent Runtime, Cloud Run |\n| `--status` | Check the status of a pending `--no-wait` deployment | Agent Runtime, Cloud Run |\n| `--list` | List existing deployments and exit | All |\n| `--dry-run` \u002F `-n` | Print what would be executed without running it. For Agent Runtime, Cloud Run and GKE, it first runs read-only checks on Google Cloud. | All |\n| `--no-confirm-project` | Skip project confirmation prompt | All |\n\nRun `agents-cli deploy --help` for the full flag reference.\n\n> **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.\n\n> **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.\n\n---\n\n## Sizing a deployment\n\nDefaults (same on Agent Runtime and Cloud Run): `--cpu 1`, `--memory 4Gi`, `--concurrency 8`, `--min-instances 0`, `--max-instances 10`. The generated `service.tf` matches, except it pins `min_instances = 1` so production deployments don't experience cold starts. The recommended values were tuned against Python agents, so treat them as a starting point and tune them with load tests (see below).\n\n`agents-cli deploy` scales to zero by default so idle dev and demo agents don't hold capacity. Pass `--min-instances 1` (or deploy via Terraform) when you need a warm instance.\n\nThe params are coupled — scale them together:\n\n- **One process — scale out, not up.** The container runs a single server process handling many requests concurrently, so throughput comes from `--concurrency` and horizontal scale (`--max-instances`), not from extra worker processes. Raise `--cpu` only when profiling shows real CPU saturation rather than time spent waiting on the model.\n- **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.\n- **Concurrency default is conservative.** A 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\u002Fmultimodal) agent. Light agents can raise it to 16–32+ after load-testing. See [Underutilized asynchronous workers](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fscale\u002Fruntime\u002Foptimize-and-scale#underutilized-workers).\n\n```bash\n# 4x throughput: scale every param, not just one\nagents-cli deploy --cpu 4 --concurrency 16 --memory 16Gi --max-instances 20\n```\n\n**Tune with the scaffolded load test** (`tests\u002Fload_test\u002F` in a Python project, `e2e\u002Fload_test\u002F` in a Go one; run locally or in the CI\u002FCD staging pipeline): drive load, watch *max* latency and memory\u002FOOM restarts, then adjust — high max latency → raise concurrency (+ workers\u002Fcpu); OOM → raise memory or lower concurrency.\n\n> On **GKE** these sizing flags are rejected — size via the Terraform manifests + HorizontalPodAutoscaler under `deployment\u002Fterraform\u002F`.\n\n---\n\n## Production Deployment — CI\u002FCD Pipeline\n\nFor the full CI\u002FCD pipeline setup guide — prerequisites, `infra cicd` flags, runner comparison, WIF authentication, pipeline stages, and production approval — see `references\u002Fcicd-pipeline.md`.\n\n---\n\n## Cloud Run Specifics\n\nFor detailed infrastructure configuration (scaling defaults, Dockerfile, FastAPI endpoints, session types, networking), see `references\u002Fcloud-run.md`. **ADK:** for ADK docs on Cloud Run deployment, fetch `https:\u002F\u002Fadk.dev\u002Fdeploy\u002Fcloud-run\u002Findex.md`.\n\n> **ADK projects.** For event-driven \u002F ambient agent deployment on Cloud Run, see the [`ambient-expense-agent`](https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fadk-recipes\u002Ftree\u002Fmain\u002Fcore\u002Fpython\u002Fambient-expense-agent) recipe and `\u002Fgoogle-agents-cli-adk-code` (`references\u002Fadk-python.md`, section \"12. Event-Driven \u002F Ambient Agents\") for the `trigger_sources` pattern.\n\n---\n\n## Agent Runtime specifics\n\nAgent Runtime is a managed Gemini platform service for deploying agents as containers. Uses container-based deployment: `agents-cli deploy` packages your project and Agent Runtime builds the image from your project's `Dockerfile` (required unless you pass a prebuilt `--image`) — the same image that serves Cloud Run and GKE.\n\n> **No `gcloud` CLI exists for Agent Runtime.** Deploy via `agents-cli deploy`. Query via the Python `agentplatform.Client` SDK.\n\nDeployments can take 5-10 minutes. Use `--no-wait` to start a deployment and return immediately, then check on it later with `--status`:\n\n```bash\n# Start deployment without blocking\nagents-cli deploy --no-wait\n\n# Check on progress later\nagents-cli deploy --status\n```\n\nWhen `--status` detects the operation has completed, it writes `deployment_metadata.json`, stores an A2A project's agent card on Agent Runtime (as a normal deploy does), and prints the same success output.\n\nFor detailed infrastructure configuration (container deploy flow, the unified FastAPI app and `\u002Fapi` passthrough, Terraform resource, deployment metadata, session\u002Fartifact services, CI\u002FCD differences), see `references\u002Fagent-runtime.md`. **ADK:** for ADK docs on Agent Runtime deployment, fetch `https:\u002F\u002Fadk.dev\u002Fdeploy\u002Fagent-runtime\u002Findex.md`.\n\n---\n\n## GKE Specifics\n\nFor detailed infrastructure configuration (Kubernetes manifests, Terraform resources, Workload Identity, session types, networking), see `references\u002Fgke.md`. **ADK:** for ADK docs on GKE deployment, fetch `https:\u002F\u002Fadk.dev\u002Fdeploy\u002Fgke\u002Findex.md`.\n\n---\n\n## Service Account Architecture\n\nScaffolded projects use two service accounts:\n\n- **`app_sa`** (per environment) — Runtime identity for the deployed agent. Roles defined in `deployment\u002Fterraform\u002Fiam.tf`.\n- **`cicd_runner_sa`** (CI\u002FCD project) — CI\u002FCD pipeline identity (GitHub Actions \u002F Cloud Build). Lives in the CI\u002FCD project (defaults to prod project), needs permissions in **both** staging and prod projects.\n\nCheck `deployment\u002Fterraform\u002Fiam.tf` for exact role bindings. Cross-project permissions (Cloud Run service agents, artifact registry access) are also configured there.\n\n**Common 403 errors:**\n- \"Permission denied on Cloud Run\" → `cicd_runner_sa` missing deployment role in the target project\n- \"Cannot act as service account\" → Missing `iam.serviceAccountUser` binding on `app_sa`\n- \"Secret access denied\" → `app_sa` missing `secretmanager.secretAccessor`\n- \"Cloud SQL connection failed \u002F Not authorized\" → Runtime service account missing `roles\u002Fcloudsql.client`\n- \"Artifact Registry read denied\" → Cloud Run service agent missing read access in CI\u002FCD project\n\n---\n\n## Required Permissions for CI\u002FCD Setup\n\n- **`roles\u002Fsecretmanager.admin`** granted to the Cloud Build service account (`service-\u003CPROJECT_NUMBER>@gcp-sa-cloudbuild.iam.gserviceaccount.com`) in the CI\u002FCD project. This allows Cloud Build to access the GitHub token stored in Secret Manager.\n\n---\n\n## Required APIs\n\nThe following Google Cloud APIs must be enabled in your project for the skills and deployment to work:\n\n- **`cloudbuild.googleapis.com`** — Required for building container images and running CI\u002FCD pipelines.\n- **`secretmanager.googleapis.com`** — Required for managing secrets and API keys.\n- **`run.googleapis.com`** — Required for deploying to Cloud Run.\n\nEnsure these are enabled before running deployment or CI\u002FCD setup commands:\n```bash\ngcloud services enable cloudbuild.googleapis.com secretmanager.googleapis.com run.googleapis.com --project=YOUR_PROJECT_ID\n```\n\n---\n\n## Secret Manager (for API Credentials)\n\nInstead of passing sensitive keys as environment variables, use GCP Secret Manager.\n\n```bash\n# Create a secret\necho -n \"YOUR_API_KEY\" | gcloud secrets create MY_SECRET_NAME --data-file=-\n\n# Update an existing secret\necho -n \"NEW_API_KEY\" | gcloud secrets versions add MY_SECRET_NAME --data-file=-\n```\n\n**Grant access:** For Cloud Run, grant `secretmanager.secretAccessor` to the service account the service records (`app_sa` when Terraform created the service, the default compute SA when `agents-cli deploy` created it, or the account a later deploy passed with `--service-account`), even when deploying with Agent Identity -- Cloud Run checks that account when it deploys. 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.\n\n**Pass secrets at deploy time (Agent Runtime, Cloud Run):**\n```bash\nagents-cli deploy --secrets \"API_KEY=my-api-key,DB_PASS=db-password:2\"\n```\n\nFormat: `ENV_VAR=SECRET_ID` or `ENV_VAR=SECRET_ID:VERSION` (defaults to latest).\n\n---\n\n## Cloud SQL Permissions (Manual Deployment)\n\nWhen 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.\n\nWithout this, the deployment may succeed but fail at runtime with `cloudsql.instances.get` authorization errors.\n\n```bash\ngcloud projects add-iam-policy-binding YOUR_PROJECT_ID \\\n  --member=\"serviceAccount:YOUR_RUNTIME_SA_EMAIL\" \\\n  --role=\"roles\u002Fcloudsql.client\"\n```\n\n> **Note:** In full Terraform-managed setups (`infra cicd` \u002F `infra single-project`), this role is configured and managed automatically.\n\n---\n\n## Observability\n\nSee the **agents-cli-observability** skill for observability configuration (Cloud Trace, prompt-response logging, BigQuery Analytics, third-party integrations).\n\n---\n\n## Testing Your Deployed Agent\n\nThe quickest way to test a deployed agent is `agents-cli run --url \u003Cservice-url> --mode a2a \"your prompt\"` — it handles auth, sessions, and streaming automatically (supports Agent Runtime and Cloud Run). **ADK:** `--mode adk` talks to the ADK streaming API instead.\n\nFor advanced testing (custom headers, session reuse, scripting, load tests), see `references\u002Ftesting-deployed-agents.md`.\n\n---\n\n## Deploying with a UI (IAP)\n\nIAP (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`.\n\nFor 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.\n\nFor more information on IAP with Cloud Run, see the [Cloud Console IAP settings](https:\u002F\u002Fcloud.google.com\u002Frun\u002Fdocs\u002Fsecuring\u002Fidentity-aware-proxy-cloud-run#manage_user_or_group_access).\n\n---\n\n## Rollback & Recovery\n\nThe primary rollback mechanism is **git-based**: fix the issue, commit, and push to `main`. The CI\u002FCD pipeline will automatically build and deploy the new version through staging → production.\n\nFor immediate Cloud Run rollback without a new commit, use revision traffic shifting:\n```bash\ngcloud run revisions list --service=SERVICE_NAME --region=REGION\ngcloud run services update-traffic SERVICE_NAME \\\n  --to-revisions=REVISION_NAME=100 --region=REGION\n```\n\nAgent Runtime doesn't support revision-based rollback — fix and redeploy via `agents-cli deploy`.\n\nFor GKE rollback, use `kubectl rollout undo`:\n```bash\nkubectl rollout undo deployment\u002FDEPLOYMENT_NAME -n NAMESPACE\nkubectl rollout status deployment\u002FDEPLOYMENT_NAME -n NAMESPACE\n```\n\n---\n\n## Custom Infrastructure (Terraform)\n\n**CRITICAL**: When your agent requires custom infrastructure (Cloud SQL, Pub\u002FSub, Eventarc, BigQuery, etc.), you MUST define it in Terraform — never create resources manually via `gcloud` commands. Exception: quick experimentation is fine with `gcloud` or console, but production infrastructure must be in Terraform.\n\nFor custom infrastructure patterns, consult `references\u002Fterraform-patterns.md` for:\n- Where to put custom Terraform files (single-project vs CI\u002FCD)\n- Resource examples (Pub\u002FSub, BigQuery, Eventarc triggers)\n- IAM bindings for custom resources\n- Terraform state management (remote vs local, importing resources)\n- Common infrastructure patterns\n\n---\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| Terraform state locked | `terraform force-unlock -force LOCK_ID` in deployment\u002Fterraform\u002F |\n| GitHub Actions auth failed | Re-run `terraform apply` in CI\u002FCD terraform dir; verify WIF pool\u002Fprovider |\n| Cloud Build authorization pending | Use `github_actions` runner instead |\n| Resource already exists | `terraform import` (see `references\u002Fterraform-patterns.md`) |\n| Agent Runtime deploy timeout \u002F hangs | Deployments take 5-10 min; check if engine was created (see Agent Runtime specifics) |\n| Secret not available | Verify `secretAccessor` granted to `app_sa` (not the default compute SA), and to the Agent Identity principal (if using Agent Identity) |\n| Cloud SQL connection failed \u002F 403 | Grant `roles\u002Fcloudsql.client` to the runtime service account when using manual deployments |\n| 403 on deploy | Check `deployment\u002Fterraform\u002Fiam.tf` — `cicd_runner_sa` needs deployment + SA impersonation roles in the target project |\n| 403 when testing Cloud Run | Default is `--no-allow-unauthenticated`; include `Authorization: Bearer $(gcloud auth print-identity-token)` header |\n| Cold starts too slow | Set `min_instance_count > 0` in Cloud Run Terraform config |\n| Cloud Run 503 errors | Check resource limits (memory\u002FCPU), increase `max_instance_count`, or check container crash logs |\n| 403 right after granting IAM role | IAM propagation is not instant — wait a couple of minutes before retrying. Don't keep re-granting the same role |\n| Resource seems missing but Terraform created it | Run `terraform state list` to check what Terraform actually manages. Resources created via `null_resource` + `local-exec` (e.g., BQ linked datasets) won't appear in `gcloud` CLI output |\n| Deployment failed or agent not responding | Check Cloud Logging: `gcloud logging read \"resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE\" --project=PROJECT --limit=50 --format=\"table(timestamp,severity,textPayload)\"` for Cloud Run, or `gcloud logging read \"resource.type=aiplatform.googleapis.com\u002FReasoningEngine\" --project=PROJECT --limit=50` for Agent Runtime |\n| Agent returns errors after deploy | Open Cloud Logging in Console → filter by service name (Cloud Run) or reasoning engine resource (Agent Runtime) → look for stack traces or permission errors in recent log entries |\n\n---\n\n## Platform Registration\n\nFor registering deployed agents with Gemini, see `\u002Fgoogle-agents-cli-publish`.\n\n---\n\n## Agent Gateway\n\n> **Note:** There are no `agents-cli` commands for creating or managing Agent Gateways or\n> Semantic Governance policies — set those up separately (via Terraform or the Cloud Console).\n> `agents-cli deploy` is the only gateway-aware command, and its support is a passthrough: it\n> binds the agent to an *existing* gateway as part of the Agent Runtime create\u002Fupdate call.\n\n**Agent Gateway** is the networking + security entry\u002Fexit point for all agent interactions\n(user↔agent, agent↔tool, agent↔agent) — it centralizes access control and governed\nconnectivity (ingress\u002Fegress). It is not a deployment target.\n\nTo set up a gateway, follow [Set up an Agent Gateway](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fset-up-agent-gateway)\nand [Route Agent Runtime traffic through Agent Gateway](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fscale\u002Fruntime\u002Fagent-gateway-runtime-deploy). You may also manage the gateway in Terraform with [`google_network_services_agent_gateway`](https:\u002F\u002Fregistry.terraform.io\u002Fproviders\u002Fhashicorp\u002Fgoogle\u002Flatest\u002Fdocs\u002Fresources\u002Fnetwork_services_agent_gateway) (currently in the `google-beta` provider). For the gateway with its surrounding enterprise infrastructure, use the [genai-factory](https:\u002F\u002Fgithub.com\u002FGoogleCloudPlatform\u002Fgenai-factory) blueprints, installed as an extension with `agents-cli extension add GoogleCloudPlatform\u002Fgenai-factory`.\n\nOnce a gateway exists, `agents-cli deploy` binds an agent to it with `--agent-gateway-egress`\nand\u002For `--agent-gateway-ingress`, each taking a full resource name\n(`projects\u002FPROJECT\u002Flocations\u002FREGION\u002FagentGateways\u002FGATEWAY`). Only Agent Runtime deployment is\nsupported, and the agent must have Agent Identity.\n\nAn egress gateway performs TLS decryption and inspection on outbound agent communications,\nso the image must trust the gateway's root CA. That setup is opt-in at scaffold time. If you're\ncreating a new project, pass `--agent-gateway` flag to `agents-cli create`:\n\n```bash\nagents-cli create my-agent --agent adk_python -d agent_runtime --agent-gateway\n```\n\nAlternatively, you can pass the same flag to `agents-cli scaffold enhance` to upgrade an\nexisting project:\n```bash\nagents-cli scaffold enhance . --agent-gateway\n```\n\nEither writes a Dockerfile that consumes the `AGENT_GATEWAY_ROOT_CERTIFICATES` build arg the\nplatform injects, and records `agent_gateway: true` under `create_params` so `scaffold upgrade`\nkeeps it. Deploying with `--agent-gateway-egress` against a Dockerfile that lacks the build arg\nfails with a pointer to the command above; `--no-agent-gateway` removes the setup again.\n\nBackground: [Agent Gateway overview](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fagent-gateway-overview).\n\n## Customer-managed encryption (CMEK)\n\nAn Agent Runtime agent can be encrypted with your Cloud KMS key. The key is fixed at creation,\nso set it where the agent is created: `deploy --key` for dev deployments, or the Terraform files\nfor staging\u002Fprod (`infra cicd`) and `infra single-project`; `--key` cannot add a key to an agent\nTerraform created. Required key grants and the Terraform edits: `references\u002Fcmek.md`.\n\n## Semantic Governance\n\n**Semantic Governance Policies (SGP)** add a natural-language security\u002Fcompliance layer\nthat keeps an agent's tool invocations aligned with user intent and organizational\nconstraints.\n\n- Overview: https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fpolicies\u002Fsemantic-governance-overview\n- Configure: https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fpolicies\u002Fconfigure-semantic-governance\n\n---\n\n## Related Skills\n\n- `\u002Fgoogle-agents-cli-workflow` — Development workflow, coding guidelines, and operational rules\n- `\u002Fgoogle-agents-cli-adk-code` — ADK API quick reference for writing agent code\n- `\u002Fgoogle-agents-cli-eval` — Evaluation methodology, dataset schema, and the eval-fix loop\n- `\u002Fgoogle-agents-cli-scaffold` — Project creation and enhancement with `agents-cli scaffold create` \u002F `scaffold enhance`\n- `\u002Fgoogle-agents-cli-observability` — Cloud Trace, logging, BigQuery Analytics, and third-party integrations\n- `\u002Fgoogle-agents-cli-publish` — Gemini registration\n","# Deployment Guide\n\n> **Requires:** `agents-cli` (`uv tool install google-agents-cli`) — [install uv](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002Fgetting-started\u002Finstallation\u002Findex.md) first if needed.\n\n> 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 `\u002Fgoogle-agents-cli-scaffold` to add deployment support first.\n\n### Reference Files\n\nFor deeper details, consult these reference files in `references\u002F`:\n\n- **`cloud-run.md`** — Scaling defaults, Dockerfile, session types, networking\n- **`agent-runtime.md`** — container-based deploy, unified FastAPI app, the `\u002Fapi` passthrough, Terraform resource, deployment metadata, CI\u002FCD differences\n- **`gke.md`** — GKE Autopilot cluster, Kubernetes manifests, Workload Identity, session types, networking\n- **`terraform-patterns.md`** — Custom infrastructure, IAM, state management, importing resources\n- **`batch-inference.md`** — BigQuery Remote Function trigger; for Pub\u002FSub \u002F Eventarc on ADK see `\u002Fgoogle-agents-cli-adk-code`\n- **`cicd-pipeline.md`** — Full CI\u002FCD pipeline setup, `infra cicd` flags, runner comparison, WIF auth, pipeline stages\n- **`testing-deployed-agents.md`** — Testing instructions per deployment target, curl examples, load tests\n- **`cmek.md`** — Customer-managed encryption keys on Agent Runtime in Gemini platform: key grants, `deploy --key` for dev, Terraform edits for staging\u002Fprod\n\n> **Observability:** See the `\u002Fgoogle-agents-cli-observability` skill for Cloud Trace, prompt-response logging, BigQuery Analytics, and third-party integrations.\n\n---\n\n## Deployment Target Decision Matrix\n\nChoose the right deployment target based on your requirements:\n\n| Criteria | Agent Runtime | Cloud Run | GKE |\n|----------|-------------|-----------|-----|\n| **Scaling** | Managed auto-scaling (configurable min\u002Fmax, concurrency) | Fully configurable (min\u002Fmax instances, concurrency, CPU allocation) | Full Kubernetes scaling (HPA, VPA, node auto-provisioning) |\n| **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 |\n| **Session state** | Sessions in Gemini platform (ADK wires `VertexAiSessionService` automatically) | In-memory (dev), Cloud SQL, or a managed sessions backend | In-memory (dev), Cloud SQL, or a managed sessions backend |\n| **Batch\u002Fevent processing** | Trigger endpoints reachable via the Agent Runtime `\u002Fapi` passthrough | Native trigger endpoints (Pub\u002FSub, Eventarc); ADK: see `\u002Fgoogle-agents-cli-adk-code` | Custom (Kubernetes Jobs, Pub\u002FSub) |\n| **Cost model** | vCPU-hours + memory-hours (not billed when idle) | Per-instance-second + min instance costs | Node pool costs (always-on or auto-provisioned) |\n| **Setup complexity** | Lower (managed, purpose-built for agents) | Medium (Dockerfile, Terraform, networking) | Higher (Kubernetes expertise required) |\n| **Best for** | Managed infrastructure, minimal ops | Custom infra, full networking control | Full Kubernetes control |\n\n**Ask the user** which deployment target fits their needs. Each is a valid production choice with different trade-offs.\n\nAll three targets are container-based, so any language works.\n\n> **Product name mapping:** users may say \"Agent Engine\", \"Vertex AI Agent Engine\", or \"Agent Runtime\"; all mean Agent Runtime. Use `--deployment-target agent_runtime`.\n\n> **Ambient \u002F scheduled \u002F event-driven agents (ADK projects):** ADK's `trigger_sources` registers `\u002Fapps\u002F{app}\u002Ftrigger\u002F*` endpoints on the same FastAPI app for **all** targets. On **Cloud Run** \u002F **GKE** these are public HTTP routes you point a Pub\u002FSub push subscription or Eventarc trigger at; on **Agent Runtime** the same routes are reachable through its `\u002Fapi` passthrough (e.g. `...\u002FreasoningEngines\u002Fv1\u002F{resource}\u002Fapi\u002Fapps\u002F{app}\u002Ftrigger\u002Fpubsub`). Cloud Run remains the simplest target for unauthenticated trigger sources. See `\u002Fgoogle-agents-cli-adk-code` (`references\u002Fadk-python.md`, section \"12. Event-Driven \u002F Ambient Agents\") for the `trigger_sources` pattern.\n\n> **OAuth \u002F user consent agents:** Use **Agent Runtime**, registered with Gemini, 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 `\u002Fgoogle-agents-cli-adk-code` → `references\u002Frecipes.md`.\n\n> **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: `\u002Fgoogle-agents-cli-adk-code` (`references\u002Fadk-python-live.md`).\n\n---\n\n## Deploying to Dev\n\n### Deploy Workflow\n\n**Task tracking:** Deployment involves multiple sequential steps (infra setup, CI\u002FCD 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.\n\n1. If prototype (no deployment target), first enhance: `agents-cli scaffold enhance . --deployment-target \u003Ctarget>`\n2. **Notify the human**: paste the eval scores and test results, then ask \"Ready to deploy to dev?\"\n3. **Wait for explicit approval**\n4. Once approved: `agents-cli deploy`\n\n> **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.\n\n**IMPORTANT**: Never run `agents-cli deploy` without explicit human approval.\n\n> **Not a prerequisite.** `agents-cli deploy` works on its own. One exception: if the user wants Terraform-managed observability (prompt-response logging, BigQuery analytics), run `agents-cli infra single-project --apply` first, see `\u002Fgoogle-agents-cli-observability`.\n\n### Single-Project Infrastructure Setup (Optional — Advanced)\n\n`agents-cli infra single-project --apply` runs `terraform apply` in `deployment\u002Fterraform\u002Fsingle-project\u002F`. Use this to **provision single-project GCP infrastructure without CI\u002FCD** (service accounts, IAM bindings, telemetry resources, Artifact Registry). It is required before deployment only when Terraform will manage observability; basic Agent Runtime and Cloud Run deployments do not need it, while GKE deploy handles its own targeted Terraform.\n\n```bash\n# Optional — provision infrastructure in a single GCP project\nagents-cli infra single-project --apply\n```\n\n> **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`. With Agent Identity, `--service-account` is ignored.\n\n### Deploy Flag Reference\n\n| Flag | Description | Targets |\n|------|-------------|---------|\n| `--project` | GCP project ID | All |\n| `--region` | GCP region | All |\n| `--service-account` | Service account email for the deployed agent | All |\n| `--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 |\n| `--secrets` \u002F `--update-secrets` | Comma-separated `ENV=SECRET` or `ENV=SECRET:VERSION` pairs. Cloud Run adds them to the service's existing secrets; Agent Runtime replaces the agent's existing secrets with the ones you pass. | Agent Runtime, Cloud Run |\n| `--remove-secrets` | Comma-separated secret `KEY`s to remove. Keys that don't exist are ignored. A key can't also be in `--secrets`. Cannot be combined with `--clear-secrets`. | Agent Runtime, Cloud Run |\n| `--clear-secrets` | Remove all secrets, including ones set outside agents-cli (e.g. Terraform's `DB_PASS` for Cloud SQL sessions) and, on Cloud Run, secrets mounted as volumes. Combine with `--secrets` to replace the secret set; the clear is applied first. Cannot be combined with `--remove-secrets`. | Agent Runtime, Cloud Run |\n| `--env-vars` \u002F `--update-env-vars` | Comma-separated `KEY=VALUE` environment variables to add or update, applied on top of the project `.env` (which every deploy propagates). On GKE, a deploy without `--image` first resets the env vars to Terraform's, so values passed on earlier deploys are dropped; keep lasting ones in `.env` or Terraform. | All |\n| `--remove-env-vars` | Comma-separated env var `KEY`s to remove. Keys that don't exist are ignored. A key can't also be in `--env-vars` or the project `.env` (delete it from `.env` instead). Defaults agents-cli sets on every deploy (e.g. `AGENT_VERSION`, `APP_URL`) are kept. Cannot be combined with `--clear-env-vars`. | Agent Runtime, Cloud Run |\n| `--clear-env-vars` | Remove all env vars, including ones set outside agents-cli (e.g. Terraform's `LOGS_BUCKET_NAME` and `OTEL_*`); secrets are kept. The project `.env`, `--env-vars` and agents-cli's defaults are applied after the clear. Cannot be combined with `--remove-env-vars`. Not on GKE, where Terraform manages the deployment's env vars. | Agent Runtime, Cloud Run |\n| `--agent-identity` | Enable [Agent Identity](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fscale\u002Fruntime\u002Fagent-identity) | Agent Runtime, Cloud Run |\n| `--no-agent-identity` | Disable Agent Identity. Passing neither `--agent-identity` nor `--no-agent-identity` follows the project's identity default in `agents-cli-manifest.yaml` when the agent is created, or keeps the current identity type on later deploys. On Cloud Run, Agent Identity can't be turned off: for a service that already has it, the deploy stops and asks you to delete the service and redeploy. | Agent Runtime, Cloud Run |\n| `--network-attachment` | Network attachment resource name for [PSC interface](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fscale\u002Fruntime\u002Fprivate-service-connect-interface) (enables private VPC connectivity) | Agent Runtime |\n| `--dns-peering-domain` | DNS peering domain suffix, e.g. `my-internal.corp.` (requires `--network-attachment`) | Agent Runtime |\n| `--dns-peering-project` | Project ID hosting the Cloud DNS managed zone for DNS peering (requires `--network-attachment`) | Agent Runtime |\n| `--dns-peering-network` | VPC network name in the target project for DNS peering (requires `--network-attachment`) | Agent Runtime |\n| `--agent-gateway-egress` | Bind the agent to an [Agent Gateway](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fagent-gateway-overview) 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-gateway) | Agent Runtime |\n| `--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 |\n| `--key` | Cloud KMS key for customer-managed encryption (CMEK), as a full `projects\u002FPROJECT\u002Flocations\u002FREGION\u002FkeyRings\u002FRING\u002FcryptoKeys\u002FKEY` name. Set on create only; for dev deployments (staging\u002Fprod set the key in Terraform). See [Customer-managed encryption](#customer-managed-encryption-cmek) | Agent Runtime |\n| `--memory` | Memory limit (default: `4Gi`) | Agent Runtime, Cloud Run |\n| `--cpu` | CPU limit (default: `1`) | Agent Runtime, Cloud Run |\n| `--min-instances` | Minimum number of instances (default: `0`, i.e. scale to zero; the generated Terraform uses `1`) | Agent Runtime, Cloud Run |\n| `--max-instances` | Maximum number of instances (default: `10`) | Agent Runtime, Cloud Run |\n| `--concurrency` | Concurrent requests per container (default: `8`; see [Sizing a deployment](#sizing-a-deployment)) | Agent Runtime, Cloud Run |\n| `--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 |\n| `--port` | Container port | Cloud Run, Agent Runtime |\n| `--build-args` | Comma-separated `KEY=VALUE` Docker build args | Agent Runtime |\n| `--labels` \u002F `--update-labels` | Comma-separated `KEY=VALUE` resource labels to add or update. Additive: adds\u002Fupdates the labels you name; labels you don't name are preserved. | Agent Runtime, Cloud Run |\n| `--remove-labels` | Comma-separated label `KEY`s to remove. Keys that don't exist are ignored. Can be combined with `--labels`, but a key can't appear in both. Cannot be combined with `--clear-labels`. | Agent Runtime, Cloud Run |\n| `--clear-labels` | Remove all resource labels (Cloud Run keeps its reserved `created-by` label). Combine with `--labels` to replace the label set; the clear is applied first. Cannot be combined with `--remove-labels`. | Agent Runtime, Cloud Run |\n| `--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](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Freference\u002Frest\u002Fv1\u002Fprojects.locations.reasoningEngines#ReasoningEngineSpec)) | Agent Runtime |\n| `--iap` | Enable Identity-Aware Proxy | Cloud Run |\n| `--image` | Prebuilt container image URI (skips source build). On Agent Runtime the image must be in Artifact Registry and readable by the Agent Runtime service agent (`roles\u002Fartifactregistry.reader`); can't be combined with `--build-args` | All |\n| `--no-wait` | Start deployment and return immediately | Agent Runtime, Cloud Run |\n| `--status` | Check the status of a pending `--no-wait` deployment | Agent Runtime, Cloud Run |\n| `--list` | List existing deployments and exit | All |\n| `--dry-run` \u002F `-n` | Print what would be executed without running it. For Agent Runtime, Cloud Run and GKE, it first runs read-only checks on Google Cloud. | All |\n| `--no-confirm-project` | Skip project confirmation prompt | All |\n\nRun `agents-cli deploy --help` for the full flag reference.\n\n> **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.\n\n> **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.\n\n---\n\n## Sizing a deployment\n\nDefaults (same on Agent Runtime and Cloud Run): `--cpu 1`, `--memory 4Gi`, `--concurrency 8`, `--min-instances 0`, `--max-instances 10`. The generated `service.tf` matches, except it pins `min_instances = 1` so production deployments don't experience cold starts. The recommended values were tuned against Python agents, so treat them as a starting point and tune them with load tests (see below).\n\n`agents-cli deploy` scales to zero by default so idle dev and demo agents don't hold capacity. Pass `--min-instances 1` (or deploy via Terraform) when you need a warm instance.\n\nThe params are coupled — scale them together:\n\n- **One process — scale out, not up.** The container runs a single server process handling many requests concurrently, so throughput comes from `--concurrency` and horizontal scale (`--max-instances`), not from extra worker processes. Raise `--cpu` only when profiling shows real CPU saturation rather than time spent waiting on the model.\n- **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.\n- **Concurrency default is conservative.** A 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\u002Fmultimodal) agent. Light agents can raise it to 16–32+ after load-testing. See [Underutilized asynchronous workers](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fscale\u002Fruntime\u002Foptimize-and-scale#underutilized-workers).\n\n```bash\n# 4x throughput: scale every param, not just one\nagents-cli deploy --cpu 4 --concurrency 16 --memory 16Gi --max-instances 20\n```\n\n**Tune with the scaffolded load test** (`tests\u002Fload_test\u002F` in a Python project, `e2e\u002Fload_test\u002F` in a Go one; run locally or in the CI\u002FCD staging pipeline): drive load, watch *max* latency and memory\u002FOOM restarts, then adjust — high max latency → raise concurrency (+ workers\u002Fcpu); OOM → raise memory or lower concurrency.\n\n> On **GKE** these sizing flags are rejected — size via the Terraform manifests + HorizontalPodAutoscaler under `deployment\u002Fterraform\u002F`.\n\n---\n\n## Production Deployment — CI\u002FCD Pipeline\n\nFor the full CI\u002FCD pipeline setup guide — prerequisites, `infra cicd` flags, runner comparison, WIF authentication, pipeline stages, and production approval — see `references\u002Fcicd-pipeline.md`.\n\n---\n\n## Cloud Run Specifics\n\nFor detailed infrastructure configuration (scaling defaults, Dockerfile, FastAPI endpoints, session types, networking), see `references\u002Fcloud-run.md`. **ADK:** for ADK docs on Cloud Run deployment, fetch `https:\u002F\u002Fadk.dev\u002Fdeploy\u002Fcloud-run\u002Findex.md`.\n\n> **ADK projects.** For event-driven \u002F ambient agent deployment on Cloud Run, see the [`ambient-expense-agent`](https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fadk-recipes\u002Ftree\u002Fmain\u002Fcore\u002Fpython\u002Fambient-expense-agent) recipe and `\u002Fgoogle-agents-cli-adk-code` (`references\u002Fadk-python.md`, section \"12. Event-Driven \u002F Ambient Agents\") for the `trigger_sources` pattern.\n\n---\n\n## Agent Runtime specifics\n\nAgent Runtime is a managed Gemini platform service for deploying agents as containers. Uses container-based deployment: `agents-cli deploy` packages your project and Agent Runtime builds the image from your project's `Dockerfile` (required unless you pass a prebuilt `--image`) — the same image that serves Cloud Run and GKE.\n\n> **No `gcloud` CLI exists for Agent Runtime.** Deploy via `agents-cli deploy`. Query via the Python `agentplatform.Client` SDK.\n\nDeployments can take 5-10 minutes. Use `--no-wait` to start a deployment and return immediately, then check on it later with `--status`:\n\n```bash\n# Start deployment without blocking\nagents-cli deploy --no-wait\n\n# Check on progress later\nagents-cli deploy --status\n```\n\nWhen `--status` detects the operation has completed, it writes `deployment_metadata.json`, stores an A2A project's agent card on Agent Runtime (as a normal deploy does), and prints the same success output.\n\nFor detailed infrastructure configuration (container deploy flow, the unified FastAPI app and `\u002Fapi` passthrough, Terraform resource, deployment metadata, session\u002Fartifact services, CI\u002FCD differences), see `references\u002Fagent-runtime.md`. **ADK:** for ADK docs on Agent Runtime deployment, fetch `https:\u002F\u002Fadk.dev\u002Fdeploy\u002Fagent-runtime\u002Findex.md`.\n\n---\n\n## GKE Specifics\n\nFor detailed infrastructure configuration (Kubernetes manifests, Terraform resources, Workload Identity, session types, networking), see `references\u002Fgke.md`. **ADK:** for ADK docs on GKE deployment, fetch `https:\u002F\u002Fadk.dev\u002Fdeploy\u002Fgke\u002Findex.md`.\n\n---\n\n## Service Account Architecture\n\nScaffolded projects use two service accounts:\n\n- **`app_sa`** (per environment) — Runtime identity for the deployed agent. Roles defined in `deployment\u002Fterraform\u002Fiam.tf`.\n- **`cicd_runner_sa`** (CI\u002FCD project) — CI\u002FCD pipeline identity (GitHub Actions \u002F Cloud Build). Lives in the CI\u002FCD project (defaults to prod project), needs permissions in **both** staging and prod projects.\n\nCheck `deployment\u002Fterraform\u002Fiam.tf` for exact role bindings. Cross-project permissions (Cloud Run service agents, artifact registry access) are also configured there.\n\n**Common 403 errors:**\n- \"Permission denied on Cloud Run\" → `cicd_runner_sa` missing deployment role in the target project\n- \"Cannot act as service account\" → Missing `iam.serviceAccountUser` binding on `app_sa`\n- \"Secret access denied\" → `app_sa` missing `secretmanager.secretAccessor`\n- \"Cloud SQL connection failed \u002F Not authorized\" → Runtime service account missing `roles\u002Fcloudsql.client`\n- \"Artifact Registry read denied\" → Cloud Run service agent missing read access in CI\u002FCD project\n\n---\n\n## Required Permissions for CI\u002FCD Setup\n\n- **`roles\u002Fsecretmanager.admin`** granted to the Cloud Build service account (`service-\u003CPROJECT_NUMBER>@gcp-sa-cloudbuild.iam.gserviceaccount.com`) in the CI\u002FCD project. This allows Cloud Build to access the GitHub token stored in Secret Manager.\n\n---\n\n## Required APIs\n\nThe following Google Cloud APIs must be enabled in your project for the skills and deployment to work:\n\n- **`cloudbuild.googleapis.com`** — Required for building container images and running CI\u002FCD pipelines.\n- **`secretmanager.googleapis.com`** — Required for managing secrets and API keys.\n- **`run.googleapis.com`** — Required for deploying to Cloud Run.\n\nEnsure these are enabled before running deployment or CI\u002FCD setup commands:\n```bash\ngcloud services enable cloudbuild.googleapis.com secretmanager.googleapis.com run.googleapis.com --project=YOUR_PROJECT_ID\n```\n\n---\n\n## Secret Manager (for API Credentials)\n\nInstead of passing sensitive keys as environment variables, use GCP Secret Manager.\n\n```bash\n# Create a secret\necho -n \"YOUR_API_KEY\" | gcloud secrets create MY_SECRET_NAME --data-file=-\n\n# Update an existing secret\necho -n \"NEW_API_KEY\" | gcloud secrets versions add MY_SECRET_NAME --data-file=-\n```\n\n**Grant access:** For Cloud Run, grant `secretmanager.secretAccessor` to the service account the service records (`app_sa` when Terraform created the service, the default compute SA when `agents-cli deploy` created it, or the account a later deploy passed with `--service-account`), even when deploying with Agent Identity -- Cloud Run checks that account when it deploys. 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.\n\n**Pass secrets at deploy time (Agent Runtime, Cloud Run):**\n```bash\nagents-cli deploy --secrets \"API_KEY=my-api-key,DB_PASS=db-password:2\"\n```\n\nFormat: `ENV_VAR=SECRET_ID` or `ENV_VAR=SECRET_ID:VERSION` (defaults to latest).\n\n---\n\n## Cloud SQL Permissions (Manual Deployment)\n\nWhen 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.\n\nWithout this, the deployment may succeed but fail at runtime with `cloudsql.instances.get` authorization errors.\n\n```bash\ngcloud projects add-iam-policy-binding YOUR_PROJECT_ID \\\n  --member=\"serviceAccount:YOUR_RUNTIME_SA_EMAIL\" \\\n  --role=\"roles\u002Fcloudsql.client\"\n```\n\n> **Note:** In full Terraform-managed setups (`infra cicd` \u002F `infra single-project`), this role is configured and managed automatically.\n\n---\n\n## Observability\n\nSee the **agents-cli-observability** skill for observability configuration (Cloud Trace, prompt-response logging, BigQuery Analytics, third-party integrations).\n\n---\n\n## Testing Your Deployed Agent\n\nThe quickest way to test a deployed agent is `agents-cli run --url \u003Cservice-url> --mode a2a \"your prompt\"` — it handles auth, sessions, and streaming automatically (supports Agent Runtime and Cloud Run). **ADK:** `--mode adk` talks to the ADK streaming API instead.\n\nFor advanced testing (custom headers, session reuse, scripting, load tests), see `references\u002Ftesting-deployed-agents.md`.\n\n---\n\n## Deploying with a UI (IAP)\n\nIAP (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`.\n\nFor 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.\n\nFor more information on IAP with Cloud Run, see the [Cloud Console IAP settings](https:\u002F\u002Fcloud.google.com\u002Frun\u002Fdocs\u002Fsecuring\u002Fidentity-aware-proxy-cloud-run#manage_user_or_group_access).\n\n---\n\n## Rollback & Recovery\n\nThe primary rollback mechanism is **git-based**: fix the issue, commit, and push to `main`. The CI\u002FCD pipeline will automatically build and deploy the new version through staging → production.\n\nFor immediate Cloud Run rollback without a new commit, use revision traffic shifting:\n```bash\ngcloud run revisions list --service=SERVICE_NAME --region=REGION\ngcloud run services update-traffic SERVICE_NAME \\\n  --to-revisions=REVISION_NAME=100 --region=REGION\n```\n\nAgent Runtime doesn't support revision-based rollback — fix and redeploy via `agents-cli deploy`.\n\nFor GKE rollback, use `kubectl rollout undo`:\n```bash\nkubectl rollout undo deployment\u002FDEPLOYMENT_NAME -n NAMESPACE\nkubectl rollout status deployment\u002FDEPLOYMENT_NAME -n NAMESPACE\n```\n\n---\n\n## Custom Infrastructure (Terraform)\n\n**CRITICAL**: When your agent requires custom infrastructure (Cloud SQL, Pub\u002FSub, Eventarc, BigQuery, etc.), you MUST define it in Terraform — never create resources manually via `gcloud` commands. Exception: quick experimentation is fine with `gcloud` or console, but production infrastructure must be in Terraform.\n\nFor custom infrastructure patterns, consult `references\u002Fterraform-patterns.md` for:\n- Where to put custom Terraform files (single-project vs CI\u002FCD)\n- Resource examples (Pub\u002FSub, BigQuery, Eventarc triggers)\n- IAM bindings for custom resources\n- Terraform state management (remote vs local, importing resources)\n- Common infrastructure patterns\n\n---\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| Terraform state locked | `terraform force-unlock -force LOCK_ID` in deployment\u002Fterraform\u002F |\n| GitHub Actions auth failed | Re-run `terraform apply` in CI\u002FCD terraform dir; verify WIF pool\u002Fprovider |\n| Cloud Build authorization pending | Use `github_actions` runner instead |\n| Resource already exists | `terraform import` (see `references\u002Fterraform-patterns.md`) |\n| Agent Runtime deploy timeout \u002F hangs | Deployments take 5-10 min; check if engine was created (see Agent Runtime specifics) |\n| Secret not available | Verify `secretAccessor` granted to `app_sa` (not the default compute SA), and to the Agent Identity principal (if using Agent Identity) |\n| Cloud SQL connection failed \u002F 403 | Grant `roles\u002Fcloudsql.client` to the runtime service account when using manual deployments |\n| 403 on deploy | Check `deployment\u002Fterraform\u002Fiam.tf` — `cicd_runner_sa` needs deployment + SA impersonation roles in the target project |\n| 403 when testing Cloud Run | Default is `--no-allow-unauthenticated`; include `Authorization: Bearer $(gcloud auth print-identity-token)` header |\n| Cold starts too slow | Set `min_instance_count > 0` in Cloud Run Terraform config |\n| Cloud Run 503 errors | Check resource limits (memory\u002FCPU), increase `max_instance_count`, or check container crash logs |\n| 403 right after granting IAM role | IAM propagation is not instant — wait a couple of minutes before retrying. Don't keep re-granting the same role |\n| Resource seems missing but Terraform created it | Run `terraform state list` to check what Terraform actually manages. Resources created via `null_resource` + `local-exec` (e.g., BQ linked datasets) won't appear in `gcloud` CLI output |\n| Deployment failed or agent not responding | Check Cloud Logging: `gcloud logging read \"resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE\" --project=PROJECT --limit=50 --format=\"table(timestamp,severity,textPayload)\"` for Cloud Run, or `gcloud logging read \"resource.type=aiplatform.googleapis.com\u002FReasoningEngine\" --project=PROJECT --limit=50` for Agent Runtime |\n| Agent returns errors after deploy | Open Cloud Logging in Console → filter by service name (Cloud Run) or reasoning engine resource (Agent Runtime) → look for stack traces or permission errors in recent log entries |\n\n---\n\n## Platform Registration\n\nFor registering deployed agents with Gemini, see `\u002Fgoogle-agents-cli-publish`.\n\n---\n\n## Agent Gateway\n\n> **Note:** There are no `agents-cli` commands for creating or managing Agent Gateways or\n> Semantic Governance policies — set those up separately (via Terraform or the Cloud Console).\n> `agents-cli deploy` is the only gateway-aware command, and its support is a passthrough: it\n> binds the agent to an *existing* gateway as part of the Agent Runtime create\u002Fupdate call.\n\n**Agent Gateway** is the networking + security entry\u002Fexit point for all agent interactions\n(user↔agent, agent↔tool, agent↔agent) — it centralizes access control and governed\nconnectivity (ingress\u002Fegress). It is not a deployment target.\n\nTo set up a gateway, follow [Set up an Agent Gateway](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fset-up-agent-gateway)\nand [Route Agent Runtime traffic through Agent Gateway](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fscale\u002Fruntime\u002Fagent-gateway-runtime-deploy). You may also manage the gateway in Terraform with [`google_network_services_agent_gateway`](https:\u002F\u002Fregistry.terraform.io\u002Fproviders\u002Fhashicorp\u002Fgoogle\u002Flatest\u002Fdocs\u002Fresources\u002Fnetwork_services_agent_gateway) (currently in the `google-beta` provider). For the gateway with its surrounding enterprise infrastructure, use the [genai-factory](https:\u002F\u002Fgithub.com\u002FGoogleCloudPlatform\u002Fgenai-factory) blueprints, installed as an extension with `agents-cli extension add GoogleCloudPlatform\u002Fgenai-factory`.\n\nOnce a gateway exists, `agents-cli deploy` binds an agent to it with `--agent-gateway-egress`\nand\u002For `--agent-gateway-ingress`, each taking a full resource name\n(`projects\u002FPROJECT\u002Flocations\u002FREGION\u002FagentGateways\u002FGATEWAY`). Only Agent Runtime deployment is\nsupported, and the agent must have Agent Identity.\n\nAn egress gateway performs TLS decryption and inspection on outbound agent communications,\nso the image must trust the gateway's root CA. That setup is opt-in at scaffold time. If you're\ncreating a new project, pass `--agent-gateway` flag to `agents-cli create`:\n\n```bash\nagents-cli create my-agent --agent adk_python -d agent_runtime --agent-gateway\n```\n\nAlternatively, you can pass the same flag to `agents-cli scaffold enhance` to upgrade an\nexisting project:\n```bash\nagents-cli scaffold enhance . --agent-gateway\n```\n\nEither writes a Dockerfile that consumes the `AGENT_GATEWAY_ROOT_CERTIFICATES` build arg the\nplatform injects, and records `agent_gateway: true` under `create_params` so `scaffold upgrade`\nkeeps it. Deploying with `--agent-gateway-egress` against a Dockerfile that lacks the build arg\nfails with a pointer to the command above; `--no-agent-gateway` removes the setup again.\n\nBackground: [Agent Gateway overview](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fagent-gateway-overview).\n\n## Customer-managed encryption (CMEK)\n\nAn Agent Runtime agent can be encrypted with your Cloud KMS key. The key is fixed at creation,\nso set it where the agent is created: `deploy --key` for dev deployments, or the Terraform files\nfor staging\u002Fprod (`infra cicd`) and `infra single-project`; `--key` cannot add a key to an agent\nTerraform created. Required key grants and the Terraform edits: `references\u002Fcmek.md`.\n\n## Semantic Governance\n\n**Semantic Governance Policies (SGP)** add a natural-language security\u002Fcompliance layer\nthat keeps an agent's tool invocations aligned with user intent and organizational\nconstraints.\n\n- Overview: https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fpolicies\u002Fsemantic-governance-overview\n- Configure: https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fpolicies\u002Fconfigure-semantic-governance\n\n---\n\n## Related Skills\n\n- `\u002Fgoogle-agents-cli-workflow` — Development workflow, coding guidelines, and operational rules\n- `\u002Fgoogle-agents-cli-adk-code` — ADK API quick reference for writing agent code\n- `\u002Fgoogle-agents-cli-eval` — Evaluation methodology, dataset schema, and the eval-fix loop\n- `\u002Fgoogle-agents-cli-scaffold` — Project creation and enhancement with `agents-cli scaffold create` \u002F `scaffold enhance`\n- `\u002Fgoogle-agents-cli-observability` — Cloud Trace, logging, BigQuery Analytics, and third-party integrations\n- `\u002Fgoogle-agents-cli-publish` — Gemini registration\n",{"name":5,"metadata":59,"description":65},{"author":12,"license":15,"version":60,"requires":61},"1.14.0",{"bins":62,"install":64},[63],"agents-cli","uv tool install google-agents-cli","This skill should be used when the user wants to \"deploy an agent\", \"deploy my ADK agent\", \"set up CI\u002FCD\", \"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).\n","main","6eedbdc2f44c388cbfc5f305eb83b9924cfefebb","skills\u002Fgoogle-agents-cli-deploy",731,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli","https:\u002F\u002Fgoogle.github.io\u002Fagents-cli\u002F","https:\u002F\u002Fgithub.com\u002Fgoogle","https:\u002F\u002Fopensource.google\u002F","Google ❤️ Open Source","2026-11-12 23:04:58",{"source":8,"skillName":5,"commands":77,"prompt":87,"zipAvailable":88},[78,81,84],{"tool":79,"command":80},"npx","npx skills add google\u002Fagents-cli --skill google-agents-cli-deploy",{"tool":82,"command":83},"bunx","bunx skills add google\u002Fagents-cli --skill google-agents-cli-deploy",{"tool":85,"command":86},"pnpm","pnpm dlx skills add google\u002Fagents-cli --skill google-agents-cli-deploy","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fskills\u002Fgoogle-agents-cli-deploy\u002FSKILL.md",true,[90,96,100,104,108,112,116,120],{"path":91,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":94,"sourceHtmlUrl":95},"references\u002Fagent-runtime.md","REFERENCE","参考文档",10201,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fskills\u002Fgoogle-agents-cli-deploy\u002Freferences\u002Fagent-runtime.md",{"path":97,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":98,"sourceHtmlUrl":99},"references\u002Fbatch-inference.md",4840,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fskills\u002Fgoogle-agents-cli-deploy\u002Freferences\u002Fbatch-inference.md",{"path":101,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":102,"sourceHtmlUrl":103},"references\u002Fcicd-pipeline.md",5342,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fskills\u002Fgoogle-agents-cli-deploy\u002Freferences\u002Fcicd-pipeline.md",{"path":105,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":106,"sourceHtmlUrl":107},"references\u002Fcloud-run.md",3646,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fskills\u002Fgoogle-agents-cli-deploy\u002Freferences\u002Fcloud-run.md",{"path":109,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":110,"sourceHtmlUrl":111},"references\u002Fcmek.md",4069,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fskills\u002Fgoogle-agents-cli-deploy\u002Freferences\u002Fcmek.md",{"path":113,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":114,"sourceHtmlUrl":115},"references\u002Fgke.md",5955,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fskills\u002Fgoogle-agents-cli-deploy\u002Freferences\u002Fgke.md",{"path":117,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":118,"sourceHtmlUrl":119},"references\u002Fterraform-patterns.md",6337,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fskills\u002Fgoogle-agents-cli-deploy\u002Freferences\u002Fterraform-patterns.md",{"path":121,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":122,"sourceHtmlUrl":123},"references\u002Ftesting-deployed-agents.md",5012,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fskills\u002Fgoogle-agents-cli-deploy\u002Freferences\u002Ftesting-deployed-agents.md",[125,150,170,193,217,235],{"skillNo":126,"name":127,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":134,"publishedAt":54},"01M6990ZGJV6CHR6CZK81S58CN","google-agents-cli-workflow","This skill should be used when the user wants to \"develop an agent\", \"build an agent using ADK\", \"run the agent locally\", \"debug agent code\", \"test an agent\", \"deploy an agent\", \"publish an agent\", \"monitor an agent\", or needs the ADK (Agent Development Kit) development lifecycle and coding guidelines. Entrypoint for building ADK agents. Always active — provides the full workflow (scaffold, build, evaluate, deploy, publish, observe), code preservation rules, model selection guidance, and troubleshooting steps for ADK or any agent development.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fsrc\u002Fgoogle\u002Fagents\u002Fcli\u002Fskills\u002Fdata\u002Fgoogle-agents-cli-workflow\u002FSKILL.md",[131,132,133],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":30,"categoryName":31,"taxonomyType":32,"taxonomyTypeDesc":33},[9,135,36,136,53,137,138,139,140,141,142,143,144,49,145,146,147,148,149,45],"google agents cli workflow","workflow","agent development kit","agent development","development lifecycle","model","observe","selection","model selection","kit","code","debug agent","publish","apache","active",{"skillNo":151,"name":152,"nameZh":6,"description":153,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":154,"categories":155,"keywords":158,"publishedAt":54},"01M6990XH0S4MNS7YTDAMNAAEW","google-agents-cli-scaffold","This skill should be used when the user wants to \"create an agent project\", \"start a new ADK project\", \"build me a new agent\", \"add CI\u002FCD to my project\", \"add deployment\", \"enhance my project\", or \"upgrade my project\". Part of the agents-cli skills suite. Covers `agents-cli scaffold create`, `scaffold enhance`, and `scaffold upgrade` commands, template options, deployment targets, and the prototype-first workflow. Do NOT use for writing agent code (ADK projects: use google-agents-cli-adk-code) or deployment operations (use google-agents-cli-deploy).","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fsrc\u002Fgoogle\u002Fagents\u002Fcli\u002Fskills\u002Fdata\u002Fgoogle-agents-cli-scaffold\u002FSKILL.md",[156,157],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},[159,9,36,160,53,161,162,163,52,51,49,164,136,145,165,166,148,167,168,169],"google agents cli scaffold","scaffold","writing","projects","new agent","upgrade","create","me","options","template","CI\u002FCD",{"skillNo":171,"name":172,"nameZh":6,"description":173,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":174,"categories":175,"keywords":178,"publishedAt":54},"01M6990VP634A9G6052KQCZNYJ","google-agents-cli-publish","This skill should be used when the user wants to \"publish an agent\", \"publish my ADK agent\", \"register an agent with Gemini\", \"publish to Gemini\" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to \"manage agents in Agent Registry\", \"list\u002Fupdate\u002Fdelete registered agents\", or \"register an MCP server\". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fsrc\u002Fgoogle\u002Fagents\u002Fcli\u002Fskills\u002Fdata\u002Fgoogle-agents-cli-publish\u002FSKILL.md",[176,177],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},[9,36,179,147,53,180,181,49,182,183,184,185,186,148,187,188,189,190,191,192],"google agents cli publish","MCP","programmatic","auto","mcp server","agent registry","server","delete","command","update","install","suite","fleet","registry",{"skillNo":194,"name":195,"nameZh":6,"description":196,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":197,"categories":198,"keywords":207,"publishedAt":54},"01M6990SFDY0JKXYP921BKRJYE","google-agents-cli-observability","This skill should be used when the user wants to \"set up tracing\", \"monitor my agent\", \"configure logging\", \"add observability\", \"debug production traffic\", or needs guidance on monitoring deployed agents, including ADK (Agent Development Kit) agents. Covers Cloud Trace, prompt-response logging, BigQuery Agent Analytics, third-party integrations (AgentOps, Phoenix, MLflow, etc.), and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment setup (use google-agents-cli-deploy) or API code patterns (use google-agents-cli-adk-code).","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fsrc\u002Fgoogle\u002Fagents\u002Fcli\u002Fskills\u002Fdata\u002Fgoogle-agents-cli-observability\u002FSKILL.md",[199,202,203,204],{"categoryNo":200,"categoryName":201,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000013","分析与可视化",{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":30,"categoryName":31,"taxonomyType":32,"taxonomyTypeDesc":33},{"categoryNo":205,"categoryName":206,"taxonomyType":32,"taxonomyTypeDesc":33},"01JBSEEDCAT000000000000033","数据分析师",[9,36,208,209,53,137,138,210,211,144,49,212,213,47,145,214,215,148,189,216],"google agents cli observability","observability","SET","up","traffic","configure","api","monitoring","mlflow",{"skillNo":218,"name":219,"nameZh":6,"description":220,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":221,"categories":222,"keywords":225,"publishedAt":54},"01M6990PXZ0S6NHYV8PGGVFT6E","google-agents-cli-eval","This skill should be used when the user wants to \"run an evaluation\", \"evaluate my agent\", \"evaluate my ADK agent\", \"write an eval dataset\", \"analyze eval failures\", \"compare eval results\", \"optimize agent\", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fsrc\u002Fgoogle\u002Fagents\u002Fcli\u002Fskills\u002Fdata\u002Fgoogle-agents-cli-eval\u002FSKILL.md",[223,224],{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":30,"categoryName":31,"taxonomyType":32,"taxonomyTypeDesc":33},[9,36,226,50,53,227,52,228,49,229,47,145,230,214,231,232,233,148,45,234],"google agents cli eval","project scaffolding","scaffolding","dataset","scoring","common","analyze","optimize","write",{"skillNo":236,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":237,"categories":238,"keywords":243,"publishedAt":54},"01M6990MAHH0X6XCNVB74Q67P6","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fagents-cli\u002Fblob\u002Fmain\u002Fsrc\u002Fgoogle\u002Fagents\u002Fcli\u002Fskills\u002Fdata\u002Fgoogle-agents-cli-deploy\u002FSKILL.md",[239,240,241,242],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":27,"categoryName":28,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":30,"categoryName":31,"taxonomyType":32,"taxonomyTypeDesc":33},[9,35,36,37,53,52,51,50,49,48,47,46,45,44,43,42,41,40,39,38]]