google-agents-cli-deploy
由 google 提供的 google-agents-cli-deploy Skill,包含安装方法、功能说明、完整指令和 GitHub 原文入口。
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.14.0 requires: bins: - agents-cli install: "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/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).
快速安装
npx skills add https://github.com/google/agents-cli --skill google-agents-cli-deploy
交给 AI 助手使用
以下是页面提示词的中文转述,命令保持原样。
运行 npx skills use "https://github.com/google/agents-cli" --skill "google-agents-cli-deploy",完整阅读输出并按 Skill 说明操作。必要时先将输出保存到临时文件;相对路径以输出提供的支持文件目录为准。
补充说明
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...
Deployment Guide
Requires:
agents-cli(uv tool install google-agents-cli) — install uv first if needed.
Prefer using the
agents-clicommands throughout this guide — they wrap Terraform, Docker, and deployment into a tested pipeline. If your project isn't scaffolded yet, see/google-agents-cli-scaffoldto add deployment support first.
Reference Files
For deeper details, consult these reference files in references/:
cloud-run.md— Scaling defaults, Dockerfile, session types, networkingagent-runtime.md— container-based deploy, unified FastAPI app, the/apipassthrough, Terraform resource, deployment metadata, CI/CD differencesgke.md— GKE Autopilot cluster, Kubernetes manifests, Workload Identity, session types, networkingterraform-patterns.md— Custom infrastructure, IAM, state management, importing resourcesbatch-inference.md— BigQuery Remote Function trigger; for Pub/Sub / Eventarc on ADK see/google-agents-cli-adk-codecicd-pipeline.md— Full CI/CD pipeline setup,infra cicdflags, runner comparison, WIF auth, pipeline stagestesting-deployed-agents.md— Testing instructions per deployment target, curl examples, load testscmek.md— Customer-managed encryption keys on Agent Runtime in Gemini platform: key grants,deploy --keyfor dev, Terraform edits for staging/prod
Observability: See the
/google-agents-cli-observabilityskill 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 | 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 |
| Batch/event processing | Trigger endpoints reachable via the Agent Runtime /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: users may say "Agent Engine", "Vertex AI Agent Engine", or "Agent Runtime"; all mean Agent Runtime. Use
--deployment-target agent_runtime.
Ambient / scheduled / event-driven agents (ADK projects): ADK's
trigger_sourcesregisters/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 its/apipassthrough (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 thetrigger_sourcespattern.
OAuth / 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
/google-agents-cli-adk-code→references/recipes.md.
Live and voice agents: pass
--timeout 3600on Cloud Run so a session outlives the 300s default, and--min-instances 1on 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.
- If prototype (no deployment target), first enhance:
agents-cli scaffold enhance . --deployment-target <target> - Notify the human: paste the eval scores and test results, then ask "Ready to deploy to dev?"
- Wait for explicit approval
- 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 --statusto check progress — poll every 60 seconds until it reports completion or failure.
IMPORTANT: Never run agents-cli deploy without explicit human approval.
Not a prerequisite.
agents-cli deployworks on its own. One exception: if the user wants Terraform-managed observability (prompt-response logging, BigQuery analytics), runagents-cli infra single-project --applyfirst, see/google-agents-cli-observability.
Single-Project Infrastructure Setup (Optional — Advanced)
agents-cli infra single-project --apply 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). 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.
# Optional — provision infrastructure in a single GCP project
agents-cli infra single-project --apply
Note:
agents-cli deploydoesn't automatically use the Terraform-createdapp_sa. Pass the service account explicitly:agents-cli deploy --service-account SA_EMAIL. With Agent Identity,--service-accountis ignored.
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 / --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 |
--remove-secrets |
Comma-separated secret KEYs 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 |
--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 |
--env-vars / --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 |
--remove-env-vars |
Comma-separated env var KEYs 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 |
--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 |
--agent-identity |
Enable Agent Identity | Agent Runtime, Cloud Run |
--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 |
--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 |
--key |
Cloud KMS key for customer-managed encryption (CMEK), as a full projects/PROJECT/locations/REGION/keyRings/RING/cryptoKeys/KEY name. Set on create only; for dev deployments (staging/prod set the key in Terraform). See Customer-managed encryption |
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 / --update-labels |
Comma-separated KEY=VALUE resource labels to add or update. Additive: adds/updates the labels you name; labels you don't name are preserved. |
Agent Runtime, Cloud Run |
--remove-labels |
Comma-separated label KEYs 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 |
--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 |
--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 |
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/artifactregistry.reader); can't be combined with --build-args |
All |
--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 running it. For Agent Runtime, Cloud Run and GKE, it first runs read-only checks on Google Cloud. | All |
--no-confirm-project |
Skip project confirmation prompt | All |
Run agents-cli deploy --help for the full flag reference.
Advanced Cloud Run Deploys: If you need features not exposed via
agents-cliflags, use--dry-run(or-n) to print the fullgcloudcommand, copy it, and add additional arguments as needed.
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-projectto proceed if you are relying on automatic project resolution.
Sizing a deployment
Defaults (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).
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.
The params are coupled — scale them together:
- One process — scale out, not up. The container runs a single server process handling many requests concurrently, so throughput comes from
--concurrencyand horizontal scale (--max-instances), not from extra worker processes. Raise--cpuonly when profiling shows real CPU saturation rather than time spent waiting on the model. - 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--concurrencywithout--memoryis the main OOM cause. - 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
8protects a memory-heavy (RAG/multimodal) agent. Light agents can raise it to 16–32+ after load-testing. See Underutilized asynchronous workers.
# 4x throughput: scale every param, not just one
agents-cli deploy --cpu 4 --concurrency 16 --memory 16Gi --max-instances 20
Tune with the scaffolded load test (tests/load_test/ in a Python project, e2e/load_test/ in a Go one; run locally or in the CI/CD staging pipeline): drive load, watch max latency and memory/OOM restarts, then adjust — high max latency → raise concurrency (+ workers/cpu); OOM → raise memory or lower concurrency.
On GKE these sizing flags are rejected — size via the Terraform manifests + HorizontalPodAutoscaler under
deployment/terraform/.
Production Deployment — CI/CD Pipeline
For the full CI/CD pipeline setup guide — prerequisites, infra cicd flags, runner comparison, WIF authentication, pipeline stages, and production approval — see references/cicd-pipeline.md.
Cloud Run Specifics
For detailed infrastructure configuration (scaling defaults, Dockerfile, FastAPI endpoints, session types, networking), see references/cloud-run.md. ADK: for ADK docs on Cloud Run deployment, fetch https://adk.dev/deploy/cloud-run/index.md.
ADK projects. For event-driven / ambient agent deployment on Cloud Run, see the
ambient-expense-agentrecipe and/google-agents-cli-adk-code(references/adk-python.md, section "12. Event-Driven / Ambient Agents") for thetrigger_sourcespattern.
Agent Runtime specifics
Agent 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.
No
gcloudCLI exists for Agent Runtime. Deploy viaagents-cli deploy. Query via the Pythonagentplatform.ClientSDK.
Deployments can take 5-10 minutes. Use --no-wait to start a deployment and return immediately, then check on it later with --status:
# Start deployment without blocking
agents-cli deploy --no-wait
# Check on progress later
agents-cli deploy --status
When --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.
For detailed infrastructure configuration (container deploy flow, the unified FastAPI app and /api passthrough, Terraform resource, deployment metadata, session/artifact services, CI/CD differences), see references/agent-runtime.md. ADK: for ADK docs on Agent Runtime deployment, fetch https://adk.dev/deploy/agent-runtime/index.md.
GKE Specifics
For detailed infrastructure configuration (Kubernetes manifests, Terraform resources, Workload Identity, session types, networking), see references/gke.md. ADK: for ADK docs on GKE deployment, fetch https://adk.dev/deploy/gke/index.md.
Service Account Architecture
Scaffolded projects use two service accounts:
app_sa(per environment) — Runtime identity for the deployed agent. Roles defined indeployment/terraform/iam.tf.cicd_runner_sa(CI/CD project) — CI/CD pipeline identity (GitHub Actions / Cloud Build). Lives in the CI/CD project (defaults to prod project), needs permissions in both staging and prod projects.
Check deployment/terraform/iam.tf for exact role bindings. Cross-project permissions (Cloud Run service agents, artifact registry access) are also configured there.
Common 403 errors:
- "Permission denied on Cloud Run" →
cicd_runner_samissing deployment role in the target project - "Cannot act as service account" → Missing
iam.serviceAccountUserbinding onapp_sa - "Secret access denied" →
app_samissingsecretmanager.secretAccessor - "Cloud SQL connection failed / Not authorized" → Runtime service account missing
roles/cloudsql.client - "Artifact Registry read denied" → Cloud Run service agent missing read access in CI/CD project
Required Permissions for CI/CD Setup
roles/secretmanager.admingranted to the Cloud Build service account (service-<PROJECT_NUMBER>@gcp-sa-cloudbuild.iam.gserviceaccount.com) in the CI/CD project. This allows Cloud Build to access the GitHub token stored in Secret Manager.
Required APIs
The following Google Cloud APIs must be enabled in your project for the skills and deployment to work:
cloudbuild.googleapis.com— Required for building container images and running CI/CD pipelines.secretmanager.googleapis.com— Required for managing secrets and API keys.run.googleapis.com— Required for deploying to Cloud Run.
Ensure these are enabled before running deployment or CI/CD setup commands:
gcloud services enable cloudbuild.googleapis.com secretmanager.googleapis.com run.googleapis.com --project=YOUR_PROJECT_ID
Secret Manager (for API Credentials)
Instead of passing sensitive keys as environment variables, use GCP Secret Manager.
# Create a secret
echo -n "YOUR_API_KEY" | gcloud secrets create MY_SECRET_NAME --data-file=-
# Update an existing secret
echo -n "NEW_API_KEY" | gcloud secrets versions add MY_SECRET_NAME --data-file=-
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.
Pass secrets at deploy time (Agent Runtime, Cloud Run):
agents-cli deploy --secrets "API_KEY=my-api-key,DB_PASS=db-password:2"
Format: ENV_VAR=SECRET_ID or ENV_VAR=SECRET_ID:VERSION (defaults to latest).
Cloud SQL Permissions (Manual Deployment)
When using Cloud SQL with Cloud Run in a manual deployment (e.g., adding --add-cloudsql-instances in non-Terraform setups), you must manually grant the Cloud SQL Client role to the runtime service account.
Without this, the deployment may succeed but fail at runtime with cloudsql.instances.get authorization errors.
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:YOUR_RUNTIME_SA_EMAIL" \
--role="roles/cloudsql.client"
Note: In full Terraform-managed setups (
infra cicd/infra single-project), this role is configured and managed automatically.
Observability
See the agents-cli-observability skill for observability configuration (Cloud Trace, prompt-response logging, BigQuery Analytics, third-party integrations).
Testing Your Deployed Agent
The quickest way to test a deployed agent is agents-cli run --url <service-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.
For advanced testing (custom headers, session reuse, scripting, load tests), see references/testing-deployed-agents.md.
Deploying with a UI (IAP)
IAP (Identity-Aware Proxy) secures a Cloud Run service so only authorized Google accounts can access it. Enable it by adding the --iap flag when deploying (Cloud Run only): agents-cli deploy --iap.
For Agent Runtime with a custom frontend, use a decoupled deployment — deploy the frontend separately to Cloud Run or Cloud Storage, connecting to the Agent Runtime backend API.
For more information on IAP with Cloud Run, see the Cloud Console IAP settings.
Rollback & Recovery
The primary rollback mechanism is git-based: fix the issue, commit, and push to main. The CI/CD pipeline will automatically build and deploy the new version through staging → production.
For immediate Cloud Run rollback without a new commit, use revision traffic shifting:
gcloud run revisions list --service=SERVICE_NAME --region=REGION
gcloud run services update-traffic SERVICE_NAME \
--to-revisions=REVISION_NAME=100 --region=REGION
Agent Runtime doesn't support revision-based rollback — fix and redeploy via agents-cli deploy.
For GKE rollback, use kubectl rollout undo:
kubectl rollout undo deployment/DEPLOYMENT_NAME -n NAMESPACE
kubectl rollout status deployment/DEPLOYMENT_NAME -n NAMESPACE
Custom Infrastructure (Terraform)
CRITICAL: When your agent requires custom infrastructure (Cloud SQL, Pub/Sub, 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.
For custom infrastructure patterns, consult references/terraform-patterns.md for:
- Where to put custom Terraform files (single-project vs CI/CD)
- Resource examples (Pub/Sub, BigQuery, Eventarc triggers)
- IAM bindings for custom resources
- Terraform state management (remote vs local, importing resources)
- Common infrastructure patterns
Troubleshooting
| Issue | Solution |
|---|---|
| Terraform state locked | terraform force-unlock -force LOCK_ID in deployment/terraform/ |
| GitHub Actions auth failed | Re-run terraform apply in CI/CD terraform dir; verify WIF pool/provider |
| Cloud Build authorization pending | Use github_actions runner instead |
| Resource already exists | terraform import (see references/terraform-patterns.md) |
| Agent Runtime deploy timeout / hangs | Deployments take 5-10 min; check if engine was created (see Agent Runtime specifics) |
| Secret not available | Verify secretAccessor granted to app_sa (not the default compute SA), and to the Agent Identity principal (if using Agent Identity) |
| Cloud SQL connection failed / 403 | Grant roles/cloudsql.client to the runtime service account when using manual deployments |
| 403 on deploy | Check deployment/terraform/iam.tf — cicd_runner_sa needs deployment + SA impersonation roles in the target project |
| 403 when testing Cloud Run | Default is --no-allow-unauthenticated; include Authorization: Bearer $(gcloud auth print-identity-token) header |
| Cold starts too slow | Set min_instance_count > 0 in Cloud Run Terraform config |
| Cloud Run 503 errors | Check resource limits (memory/CPU), increase max_instance_count, or check container crash logs |
| 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 |
| 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 |
| 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/ReasoningEngine" --project=PROJECT --limit=50 for Agent Runtime |
| 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 |
Platform Registration
For registering deployed agents with Gemini, see /google-agents-cli-publish.
Agent Gateway
Note: There are no
agents-clicommands for creating or managing Agent Gateways or Semantic Governance policies — set those up separately (via Terraform or the Cloud Console).agents-cli deployis the only gateway-aware command, and its support is a passthrough: it binds the agent to an existing gateway as part of the Agent Runtime create/update call.
Agent Gateway is the networking + security entry/exit point for all agent interactions (user↔agent, agent↔tool, agent↔agent) — it centralizes access control and governed connectivity (ingress/egress). It is not a deployment target.
To set up a gateway, follow Set up an Agent Gateway
and Route Agent Runtime traffic through Agent Gateway. You may also manage the gateway in Terraform with google_network_services_agent_gateway (currently in the google-beta provider). For the gateway with its surrounding enterprise infrastructure, use the genai-factory blueprints, installed as an extension with agents-cli extension add GoogleCloudPlatform/genai-factory.
Once a gateway exists, agents-cli deploy binds an agent to it with --agent-gateway-egress
and/or --agent-gateway-ingress, each taking a full resource name
(projects/PROJECT/locations/REGION/agentGateways/GATEWAY). Only Agent Runtime deployment is
supported, and the agent must have Agent Identity.
An egress gateway performs TLS decryption and inspection on outbound agent communications,
so the image must trust the gateway's root CA. That setup is opt-in at scaffold time. If you're
creating a new project, pass --agent-gateway flag to agents-cli create:
agents-cli create my-agent --agent adk_python -d agent_runtime --agent-gateway
Alternatively, you can pass the same flag to agents-cli scaffold enhance to upgrade an
existing project:
agents-cli scaffold enhance . --agent-gateway
Either writes a Dockerfile that consumes the AGENT_GATEWAY_ROOT_CERTIFICATES build arg the
platform injects, and records agent_gateway: true under create_params so scaffold upgrade
keeps it. Deploying with --agent-gateway-egress against a Dockerfile that lacks the build arg
fails with a pointer to the command above; --no-agent-gateway removes the setup again.
Background: Agent Gateway overview.
Customer-managed encryption (CMEK)
An Agent Runtime agent can be encrypted with your Cloud KMS key. The key is fixed at creation,
so set it where the agent is created: deploy --key for dev deployments, or the Terraform files
for staging/prod (infra cicd) and infra single-project; --key cannot add a key to an agent
Terraform created. Required key grants and the Terraform edits: references/cmek.md.
Semantic Governance
Semantic Governance Policies (SGP) add a natural-language security/compliance layer that keeps an agent's tool invocations aligned with user intent and organizational constraints.
- Overview: https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/policies/semantic-governance-overview
- Configure: https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/policies/configure-semantic-governance
Related Skills
/google-agents-cli-workflow— Development workflow, coding guidelines, and operational rules/google-agents-cli-adk-code— ADK API quick reference for writing agent code/google-agents-cli-eval— Evaluation methodology, dataset schema, and the eval-fix loop/google-agents-cli-scaffold— Project creation and enhancement withagents-cli scaffold create/scaffold enhance/google-agents-cli-observability— Cloud Trace, logging, BigQuery Analytics, and third-party integrations/google-agents-cli-publish— Gemini registration
来源与许可
google/agents-cli 提供此 Skill,适用 Apache-2.0。本版本追加了安装和访问入口,并将相对文档链接解析为 GitHub 地址;原始文件可从下方原文入口获取。
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.