Back to Details

google-agents-cli-deploy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ADK Deployment Guide

ADK部署指南

Requires: 
agents-cli
(
uv tool install google-agents-cli
) — install uv first if needed.
Prefer using the 
agents-cli
commands throughout this guide — they wrap Terraform, Docker, and deployment into a tested pipeline. If your project isn't scaffolded yet, see 
/google-agents-cli-scaffold
to add deployment support first.
依赖要求： 
agents-cli
（安装命令：
uv tool install google-agents-cli
）—— 若未安装uv，请先安装uv。
本指南优先推荐使用
agents-cli
命令——它们将Terraform、Docker和部署流程封装为经过验证的流水线。如果你的项目尚未搭建脚手架，请查看
/google-agents-cli-scaffold
以先添加部署支持。

Reference Files

参考文件

For deeper details, consult these reference files in 
references/
:
  • cloud-run.md
     — Scaling defaults, Dockerfile, session types, networking
  • agent-runtime.md
     — deploy.py CLI, AdkApp pattern, Terraform resource, deployment metadata, CI/CD differences
  • gke.md
     — GKE Autopilot cluster, Kubernetes manifests, Workload Identity, session types, networking
  • terraform-patterns.md
     — Custom infrastructure, IAM, state management, importing resources
  • batch-inference.md
     — BigQuery Remote Function trigger; for Pub/Sub / Eventarc see 
    /google-agents-cli-adk-code
  • cicd-pipeline.md
     — Full CI/CD pipeline setup, 
    infra cicd
    flags, runner comparison, WIF auth, pipeline stages
  • testing-deployed-agents.md
     — Testing instructions per deployment target, curl examples, load tests
Observability: See the 
/google-agents-cli-observability
skill for Cloud Trace, prompt-response logging, BigQuery Analytics, and third-party integrations.
如需深入了解细节，请查阅
references/
目录下的以下参考文件：
  • cloud-run.md
     — 弹性伸缩默认配置、Dockerfile、会话类型、网络配置
  • agent-runtime.md
     — deploy.py CLI、AdkApp模式、Terraform资源、部署元数据、CI/CD差异
  • gke.md
     — GKE Autopilot集群、Kubernetes清单、工作负载身份、会话类型、网络配置
  • terraform-patterns.md
     — 自定义基础设施、IAM、状态管理、资源导入
  • batch-inference.md
     — BigQuery远程函数触发器；Pub/Sub / Eventarc相关内容请查看
    /google-agents-cli-adk-code
  • cicd-pipeline.md
     — 完整CI/CD流水线搭建、
    infra cicd
    参数、运行器对比、WIF认证、流水线阶段
  • testing-deployed-agents.md
     — 各部署目标的测试说明、curl示例、负载测试
可观测性： Cloud Trace、提示响应日志、BigQuery分析及第三方集成相关内容，请查看
/google-agents-cli-observability
技能。

Deployment Target Decision Matrix

部署目标决策矩阵

Choose the right deployment target based on your requirements:
CriteriaAgent RuntimeCloud RunGKE
LanguagesPythonPythonPython (+ others via custom containers)
ScalingManaged auto-scaling (configurable min/max, concurrency)Fully configurable (min/max instances, concurrency, CPU allocation)Full Kubernetes scaling (HPA, VPA, node auto-provisioning)
NetworkingVPC-SC and PSC supportedFull VPC support, direct VPC egress, IAP, ingress rulesFull Kubernetes networking
Session stateNative 
VertexAiSessionService
(persistent, managed)		In-memory (dev), Cloud SQL, or Agent Platform Sessions backendIn-memory (dev), Cloud SQL, or Agent Platform Sessions backend
Batch/event processingNot supportedNative trigger endpoints (Pub/Sub, Eventarc); see 
/google-agents-cli-adk-code
Custom (Kubernetes Jobs, Pub/Sub)
Cost modelvCPU-iours + memory-iours (not billed when idle)Per-instance-second + min instance costsNode pool costs (always-on or auto-provisioned)
Setup complexityLower (managed, purpose-built for agents)Medium (Dockerfile, Terraform, networking)Higher (Kubernetes expertise required)
Best forManaged infrastructure, minimal opsCustom infra, event-driven workloadsFull Kubernetes control
Ask the user which deployment target fits their needs. Each is a valid production choice with different trade-offs.
Product name mapping: "Agent Engine" / "Vertex AI Agent Engine" is now Agent Runtime. Use 
--deployment-target agent_runtime
.
Ambient / scheduled / event-driven agents: Agent Runtime does not support Pub/Sub, Eventarc, or Cloud Scheduler triggers. Use Cloud Run (recommended) or GKE for these workloads. See 
/google-agents-cli-adk-code
Section 12 for the 
trigger_sources
pattern.
OAuth / user consent agents: Use Agent Runtime with Gemini Enterprise for agents that need OAuth 2.0 user consent (e.g., accessing Google Drive, Calendar, or other user-scoped APIs). Cloud Run does not currently support managed OAuth flows. See the 
adk-ae-oauth
sample in 
/google-agents-cli-workflow
Phase 2.
根据你的需求选择合适的部署目标：
评估标准Agent RuntimeCloud RunGKE
支持语言PythonPythonPython（自定义容器可支持其他语言）
弹性伸缩托管式自动伸缩（可配置最小/最大实例数、并发数）完全可配置（最小/最大实例数、并发数、CPU分配）完整Kubernetes伸缩能力（HPA、VPA、节点自动配置）
网络配置支持VPC-SC和PSC完整VPC支持、直接VPC出站、IAP、入站规则完整Kubernetes网络能力
会话状态原生
VertexAiSessionService
（持久化、托管式）		内存存储（开发环境）、Cloud SQL或Agent Platform Sessions后端内存存储（开发环境）、Cloud SQL或Agent Platform Sessions后端
批量/事件处理不支持原生触发器端点（Pub/Sub、Eventarc）；详情请查看
/google-agents-cli-adk-code
自定义实现（Kubernetes Jobs、Pub/Sub）
计费模式vCPU时长 + 内存时长（空闲时不计费）按实例秒数计费 + 最小实例成本节点池成本（持续运行或自动配置）
搭建复杂度较低（托管式、专为Agent打造）中等（Dockerfile、Terraform、网络配置）较高（需具备Kubernetes专业知识）
适用场景托管式基础设施、最小化运维自定义基础设施、事件驱动型工作负载完全Kubernetes控制能力
请询问用户哪种部署目标符合他们的需求。每个选项都是有效的生产环境选择，各有不同的权衡。
产品名称映射： "Agent Engine" / "Vertex AI Agent Engine"现更名为Agent Runtime。请使用
--deployment-target agent_runtime
参数。
后台/定时/事件驱动型Agent： Agent Runtime不支持Pub/Sub、Eventarc或Cloud Scheduler触发器。此类工作负载请使用Cloud Run（推荐）或GKE。
trigger_sources
模式详情请查看
/google-agents-cli-adk-code
第12节。
OAuth / 用户授权Agent： 需要OAuth 2.0用户授权（例如访问Google Drive、Calendar或其他用户范围API）的Agent，请使用Agent Runtime搭配Gemini Enterprise。Cloud Run目前不支持托管式OAuth流程。示例请查看
/google-agents-cli-workflow
第2阶段的
adk-ae-oauth
样本。

Deploying to Dev

部署到开发环境

Deploy Workflow

部署工作流

Task tracking: Deployment involves multiple sequential steps (infra setup, CI/CD configuration, deploy, verification). Use a task list to track progress through these steps — skipping one often causes failures in later steps that are hard to trace back.
  1. If prototype (no deployment target), first enhance: 
    agents-cli scaffold enhance . --deployment-target <target>
  2. Notify the human: "Eval scores meet thresholds and tests pass. Ready to deploy to dev?"
  3. Wait for explicit approval
  4. Once approved: 
    agents-cli deploy
Agent Runtime timeout recovery: Agent Runtime deploys can take 5-10 minutes and may exceed command timeouts. If the deploy command is cancelled or times out, the deployment continues server-side. Run 
agents-cli deploy --status
to check progress — poll every 60 seconds until it reports completion or failure.
IMPORTANT: Never run 
agents-cli deploy
without explicit human approval.
Do NOT run 
agents-cli infra single-project
before deploying. It is not a prerequisite — 
agents-cli deploy
works on its own. Run it separately if the user needs observability features (prompt-response logging, BigQuery analytics) — see 
/google-agents-cli-observability
.
任务跟踪： 部署涉及多个连续步骤（基础设施搭建、CI/CD配置、部署、验证）。请使用任务列表跟踪这些步骤的进度——跳过某一步通常会导致后续步骤出现难以追溯的故障。
  1. 如果是原型项目（无部署目标），先增强项目配置：
    agents-cli scaffold enhance . --deployment-target <target>
  2. 告知用户："评估分数已达阈值且测试通过。是否准备部署到开发环境？"
  3. 等待明确的批准
  4. 获得批准后执行：
    agents-cli deploy
Agent Runtime超时恢复： Agent Runtime部署可能需要5-10分钟，可能会超出命令超时时间。如果部署命令被取消或超时，部署仍会在服务器端继续进行。运行
agents-cli deploy --status
检查进度——每60秒轮询一次，直到显示完成或失败。
重要提示：未经用户明确批准，切勿运行
agents-cli deploy
命令。
部署前请勿运行
agents-cli infra single-project
。这不是部署的前置条件——
agents-cli deploy
可独立运行。如果用户需要可观测性功能（提示响应日志、BigQuery分析），可单独运行该命令——详情请查看
/google-agents-cli-observability
。

Single-Project Infrastructure Setup (Optional — Advanced)

单项目基础设施搭建（可选——高级功能）

agents-cli infra single-project
runs 
terraform apply
in 
deployment/terraform/single-project/
. Use this to provision single-project GCP infrastructure without CI/CD (service accounts, IAM bindings, telemetry resources, Artifact Registry). Also useful to test things in a single project before going to production. It is NOT required for deploying.
bash
undefined
agents-cli infra single-project
会在
deployment/terraform/single-project/
目录下执行
terraform apply
。使用此命令可在单个GCP项目中搭建无CI/CD的基础设施（服务账号、IAM绑定、遥测资源、Artifact Registry）。也可用于在进入生产环境前在单个项目中进行测试。此命令并非部署的必需步骤。
bash
undefined

Optional — provision infrastructure in a single GCP project

可选——在单个GCP项目中搭建基础设施

agents-cli infra single-project

> **Note:** `agents-cli deploy` doesn't automatically use the Terraform-created `app_sa`. Pass the service account via `agents-cli deploy --service-account SA_EMAIL` or `uv run -m app.app_utils.deploy --service-account SA_EMAIL` for Agent Runtime targets.
agents-cli infra single-project

> **注意：** `agents-cli deploy`不会自动使用Terraform创建的`app_sa`。对于Agent Runtime目标，请通过`agents-cli deploy --service-account SA_EMAIL`或`uv run -m app.app_utils.deploy --service-account SA_EMAIL`参数传入服务账号。

Deploy Flag Reference

部署参数参考

FlagDescriptionTargets
--project
GCP project IDAll
--region
GCP regionAll
--service-account
Service account email for the deployed agentAll
--secrets
Comma-separated 
ENV=SECRET
or 
ENV=SECRET:VERSION
pairs		Agent Runtime
--update-env-vars
Comma-separated 
KEY=VALUE
environment variables		Agent Runtime, Cloud Run
--agent-identity
Enable agent identity (Preview)Agent Runtime
--memory
Memory limit (default: 
4Gi
)		Cloud Run
--port
Container portCloud Run
--iap
Enable Identity-Aware ProxyCloud Run
--image
Container image URI (skips source build)Cloud Run, GKE
--no-wait
Start deployment and return immediatelyAgent Runtime, Cloud Run
--status
Check the status of a pending 
--no-wait
deployment		Agent Runtime, Cloud Run
--list
List existing deployments and exitAll
--dry-run
/ 
-n
Print what would be executed without running itAll
--no-confirm-project
Skip project confirmation promptAll
Run 
agents-cli deploy --help
for the full flag reference. Cloud Run also accepts extra 
gcloud
flags after 
--
(e.g., 
-- --timeout=600
).
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.
参数描述适用目标
--project
GCP项目ID所有
--region
GCP区域所有
--service-account
部署后Agent使用的服务账号邮箱所有
--secrets
逗号分隔的
ENV=SECRET
或
ENV=SECRET:VERSION
键值对		Agent Runtime
--update-env-vars
逗号分隔的
KEY=VALUE
环境变量		Agent Runtime、Cloud Run
--agent-identity
启用Agent身份（预览版）Agent Runtime
--memory
内存限制（默认：
4Gi
）		Cloud Run
--port
容器端口Cloud Run
--iap
启用Identity-Aware ProxyCloud Run
--image
容器镜像URI（跳过源码构建）Cloud Run、GKE
--no-wait
启动部署后立即返回，不等待完成Agent Runtime、Cloud Run
--status
检查
--no-wait
模式下的待处理部署状态		Agent Runtime、Cloud Run
--list
列出现有部署并退出所有
--dry-run
/ 
-n
打印将要执行的操作但不实际运行所有
--no-confirm-project
跳过项目确认提示所有
运行
agents-cli deploy --help
查看完整参数参考。Cloud Run还支持在
--
后添加额外的
gcloud
参数（例如：
-- --timeout=600
）。
项目确认： 如果项目是自动解析的（未通过
--project
参数传入），命令在交互模式下会提示确认。由于Agent通常运行在非交互模式下，若依赖自动项目解析，必须传入
--no-confirm-project
参数才能继续执行。

Production Deployment — CI/CD Pipeline

生产环境部署——CI/CD流水线

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
.
完整CI/CD流水线搭建指南（前置条件、
infra cicd
参数、运行器对比、WIF认证、流水线阶段、生产环境批准流程）请查看
references/cicd-pipeline.md
。

Cloud Run Specifics

Cloud Run专属配置

For detailed infrastructure configuration (scaling defaults, Dockerfile, FastAPI endpoints, session types, networking), see 
references/cloud-run.md
. For ADK docs on Cloud Run deployment, fetch 
https://adk.dev/deploy/cloud-run/index.md
.
For event-driven / ambient agent deployment on Cloud Run, see the 
ambient-expense-agent
 sample and 
/google-agents-cli-adk-code
for the 
trigger_sources
pattern.
详细基础设施配置（弹性伸缩默认值、Dockerfile、FastAPI端点、会话类型、网络配置）请查看
references/cloud-run.md
。ADK官方Cloud Run部署文档请访问
https://adk.dev/deploy/cloud-run/index.md
。
Cloud Run上的事件驱动/后台Agent部署示例，请查看
ambient-expense-agent
样本及
/google-agents-cli-adk-code
中的
trigger_sources
模式。

Agent Runtime Specifics

Agent Runtime专属配置

Agent Runtime is a managed Vertex AI service for deploying Python ADK agents. Uses source-based deployment (no Dockerfile) via 
deploy.py
and the 
AdkApp
class.
No 
gcloud
CLI exists for Agent Runtime. Deploy via 
agents-cli deploy
or 
deploy.py
. Query via the Python 
vertexai.Client
SDK.
Deployments can take 5-10 minutes. Use 
--no-wait
to start a deployment and return immediately, then check on it later with 
--status
:
bash
undefined
Agent Runtime是用于部署Python ADK Agent的托管式Vertex AI服务。通过
deploy.py
和
AdkApp
类实现基于源码的部署（无需Dockerfile）。
Agent Runtime没有
gcloud
CLI命令。请通过
agents-cli deploy
或
deploy.py
进行部署。通过Python 
vertexai.Client
SDK进行查询。
部署可能需要5-10分钟。使用
--no-wait
参数启动部署后立即返回，之后通过
--status
检查进度：
bash
undefined

Start deployment without blocking

启动部署，不阻塞当前进程

agents-cli deploy --no-wait
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` and prints the same success output as a normal deploy.

For detailed infrastructure configuration (deploy.py flags, AdkApp pattern, Terraform resource, deployment metadata, session/artifact services, CI/CD differences), see `references/agent-runtime.md`. For ADK docs on Agent Runtime deployment, fetch `https://adk.dev/deploy/agent-engine/index.md`.

---
agents-cli deploy --status

当`--status`检测到操作完成时，会写入`deployment_metadata.json`并打印与正常部署相同的成功输出。

详细基础设施配置（deploy.py参数、AdkApp模式、Terraform资源、部署元数据、会话/工件服务、CI/CD差异）请查看`references/agent-runtime.md`。ADK官方Agent Runtime部署文档请访问`https://adk.dev/deploy/agent-engine/index.md`。

---

GKE Specifics

GKE专属配置

For detailed infrastructure configuration (Kubernetes manifests, Terraform resources, Workload Identity, session types, networking), see 
references/gke.md
. For ADK docs on GKE deployment, fetch 
https://adk.dev/deploy/gke/index.md
.
详细基础设施配置（Kubernetes清单、Terraform资源、工作负载身份、会话类型、网络配置）请查看
references/gke.md
。ADK官方GKE部署文档请访问
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 in 
    deployment/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_sa
    missing deployment role in the target project
  • "Cannot act as service account" → Missing 
    iam.serviceAccountUser
    binding on 
    app_sa
  • "Secret access denied" → 
    app_sa
    missing 
    secretmanager.secretAccessor
  • "Artifact Registry read denied" → Cloud Run service agent missing read access in CI/CD project
脚手架生成的项目使用两个服务账号：
  • app_sa
    （按环境区分）—— 部署后Agent的运行时身份。角色定义在
    deployment/terraform/iam.tf
    中。
  • cicd_runner_sa
    （CI/CD项目）—— CI/CD流水线身份（GitHub Actions / Cloud Build）。位于CI/CD项目中（默认是生产环境项目），需要同时拥有 staging 和生产环境项目的权限。
请查看
deployment/terraform/iam.tf
获取确切的角色绑定。跨项目权限（Cloud Run服务代理、Artifact Registry访问）也在此文件中配置。
常见403错误：
  • "Cloud Run权限被拒绝" → 
    cicd_runner_sa
    缺少目标项目的部署角色
  • "无法扮演服务账号" → 
    app_sa
    缺少
    iam.serviceAccountUser
    绑定
  • "密钥访问被拒绝" → 
    app_sa
    缺少
    secretmanager.secretAccessor
    角色
  • "Artifact Registry读取被拒绝" → Cloud Run服务代理缺少CI/CD项目的读取权限

Required Permissions for CI/CD Setup

CI/CD搭建所需权限

  • roles/secretmanager.admin
     granted to the Cloud Build service account (
    service-<PROJECT_NUMBER>@gcp-sa-cloudbuild.iam.gserviceaccount.com
    ) in the CI/CD project. This allows Cloud Build to access the GitHub token stored in Secret Manager.
  • roles/secretmanager.admin
     — 授予CI/CD项目中的Cloud Build服务账号（
    service-<PROJECT_NUMBER>@gcp-sa-cloudbuild.iam.gserviceaccount.com
    ）。此权限允许Cloud Build访问存储在Secret Manager中的GitHub令牌。

Required APIs

必需启用的API

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:
bash
gcloud services enable cloudbuild.googleapis.com secretmanager.googleapis.com run.googleapis.com --project=YOUR_PROJECT_ID
为确保技能和部署正常工作，你的项目必须启用以下Google Cloud API：
  • cloudbuild.googleapis.com
     — 构建容器镜像和运行CI/CD流水线必需。
  • secretmanager.googleapis.com
     — 管理密钥和API密钥必需。
  • run.googleapis.com
     — 部署到Cloud Run必需。
在运行部署或CI/CD搭建命令前，请确保这些API已启用：
bash
gcloud services enable cloudbuild.googleapis.com secretmanager.googleapis.com run.googleapis.com --project=YOUR_PROJECT_ID

Secret Manager (for API Credentials)

Secret Manager（用于API凭证）

Instead of passing sensitive keys as environment variables, use GCP Secret Manager.
bash
undefined
请勿将敏感密钥作为环境变量传递，请使用GCP Secret Manager。
bash
undefined

Create a secret

创建密钥

echo -n "YOUR_API_KEY" | gcloud secrets create MY_SECRET_NAME --data-file=-
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 `app_sa`. For Agent Runtime, grant it to the platform-managed SA (`service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com`). For GKE, grant `secretmanager.secretAccessor` to `app_sa`. Access secrets via Kubernetes Secrets or directly via the Secret Manager API with Workload Identity.

**Pass secrets at deploy time (Agent Runtime):**
```bash
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). Access in code via 
os.environ.get("API_KEY")
.
echo -n "NEW_API_KEY" | gcloud secrets versions add MY_SECRET_NAME --data-file=-

**授权访问：** 对于Cloud Run，授予`app_sa` `secretmanager.secretAccessor`角色。对于Agent Runtime，授予平台托管的服务账号（`service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com`）该角色。对于GKE，授予`app_sa` `secretmanager.secretAccessor`角色。可通过Kubernetes Secrets或使用工作负载身份直接调用Secret Manager API访问密钥。

**部署时传入密钥（Agent Runtime）：**
```bash
agents-cli deploy --secrets "API_KEY=my-api-key,DB_PASS=db-password:2"
格式：
ENV_VAR=SECRET_ID
或
ENV_VAR=SECRET_ID:VERSION
（默认使用最新版本）。在代码中通过
os.environ.get("API_KEY")
访问。

Observability

可观测性

See the agents-cli-observability skill for observability configuration (Cloud Trace, prompt-response logging, BigQuery Analytics, third-party integrations).
可观测性配置（Cloud Trace、提示响应日志、BigQuery分析、第三方集成）请查看agents-cli-observability技能。

Testing Your Deployed Agent

测试已部署的Agent

The quickest way to test a deployed agent is 
agents-cli run --url <service-url> --mode <a2a|adk> "your prompt"
— it handles auth, sessions, and streaming automatically (supports Agent Runtime and Cloud Run).
For advanced testing (custom headers, session reuse, scripting, load tests), see 
references/testing-deployed-agents.md
.
测试已部署Agent的最快方式是
agents-cli run --url <service-url> --mode <a2a|adk> "your prompt"
——它会自动处理认证、会话和流式传输（支持Agent Runtime和Cloud Run）。
高级测试（自定义请求头、会话复用、脚本、负载测试）请查看
references/testing-deployed-agents.md
。

Deploying with a UI (IAP)

带UI的部署（IAP）

IAP (Identity-Aware Proxy) secures a Cloud Run service so only authorized Google accounts can access it. Support for IAP deployment via 
agents-cli deploy
is planned for a future release.
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.
IAP（Identity-Aware Proxy）可保护Cloud Run服务，仅允许授权的Google账号访问。
agents-cli deploy
对IAP部署的支持计划在未来版本中推出。
对于带有自定义前端的Agent Runtime，请使用解耦部署——将前端单独部署到Cloud Run或Cloud Storage，连接到Agent Runtime后端API。
Cloud Run搭配IAP的更多信息，请查看Cloud Console IAP设置。

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:
bash
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
:
bash
kubectl rollout undo deployment/DEPLOYMENT_NAME -n NAMESPACE
kubectl rollout status deployment/DEPLOYMENT_NAME -n NAMESPACE
主要的回滚机制是基于Git：修复问题、提交并推送到
main
分支。CI/CD流水线会自动构建并将新版本通过staging → 生产环境的流程部署。
无需新提交即可立即回滚Cloud Run版本，可使用修订版流量切换：
bash
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不支持基于修订版的回滚——修复问题后通过
agents-cli deploy
重新部署。
GKE回滚请使用
kubectl rollout undo
：
bash
kubectl rollout undo deployment/DEPLOYMENT_NAME -n NAMESPACE
kubectl rollout status deployment/DEPLOYMENT_NAME -n NAMESPACE

Custom Infrastructure (Terraform)

自定义基础设施（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
关键提示：当你的Agent需要自定义基础设施（Cloud SQL、Pub/Sub、Eventarc、BigQuery等）时，必须在Terraform中定义——切勿通过
gcloud
命令手动创建资源。例外情况：使用
gcloud
或控制台进行快速实验是可行的，但生产环境基础设施必须通过Terraform管理。
自定义基础设施模式请查看
references/terraform-patterns.md
，内容包括：
  • 自定义Terraform文件的存放位置（单项目 vs CI/CD）
  • 资源示例（Pub/Sub、BigQuery、Eventarc触发器）
  • 自定义资源的IAM绑定
  • Terraform状态管理（远程 vs 本地、资源导入）
  • 常见基础设施模式

Troubleshooting

故障排查

IssueSolution
Terraform state locked
terraform force-unlock -force LOCK_ID
in deployment/terraform/
GitHub Actions auth failedRe-run 
terraform apply
in CI/CD terraform dir; verify WIF pool/provider
Cloud Build authorization pendingUse 
github_actions
runner instead
Resource already exists
terraform import
(see 
references/terraform-patterns.md
)
Agent Runtime deploy timeout / hangsDeployments take 5-10 min; check if engine was created (see Agent Runtime Specifics)
Secret not availableVerify 
secretAccessor
granted to 
app_sa
(not the default compute SA)
403 on deployCheck 
deployment/terraform/iam.tf
— 
cicd_runner_sa
needs deployment + SA impersonation roles in the target project
403 when testing Cloud RunDefault is 
--no-allow-unauthenticated
; include 
Authorization: Bearer $(gcloud auth print-identity-token)
header
Cold starts too slowSet 
min_instance_count > 0
in Cloud Run Terraform config
Cloud Run 503 errorsCheck resource limits (memory/CPU), increase 
max_instance_count
, or check container crash logs
403 right after granting IAM roleIAM 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 itRun 
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 respondingCheck 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 deployOpen Cloud Logging in Console → filter by service name (Cloud Run) or reasoning engine resource (Agent Runtime) → look for Python tracebacks or permission errors in recent log entries
问题解决方案
Terraform状态锁定在deployment/terraform/目录下执行
terraform force-unlock -force LOCK_ID
GitHub Actions认证失败在CI/CD Terraform目录下重新运行
terraform apply
；验证WIF池/提供者配置
Cloud Build授权等待中改用
github_actions
运行器
资源已存在使用
terraform import
（详情请查看
references/terraform-patterns.md
）
Agent Runtime部署超时/挂起部署需要5-10分钟；检查引擎是否已创建（请查看Agent Runtime专属配置部分）
密钥不可用确认
secretAccessor
角色已授予
app_sa
（而非默认计算服务账号）
部署时出现403错误检查
deployment/terraform/iam.tf
——
cicd_runner_sa
需要目标项目的部署+服务账号模拟角色
测试Cloud Run时出现403错误默认配置为
--no-allow-unauthenticated
；请添加
Authorization: Bearer $(gcloud auth print-identity-token)
请求头
冷启动过慢在Cloud Run Terraform配置中设置
min_instance_count > 0
Cloud Run出现503错误检查资源限制（内存/CPU）、增加
max_instance_count
或查看容器崩溃日志
授予IAM角色后立即出现403错误IAM权限生效并非即时——等待几分钟后重试。请勿重复授予相同角色
Terraform已创建资源但似乎缺失运行
terraform state list
查看Terraform实际管理的资源。通过
null_resource
+ 
local-exec
创建的资源（例如BQ关联数据集）不会出现在
gcloud
CLI输出中
部署失败或Agent无响应查看Cloud Logging：Cloud Run执行
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE" --project=PROJECT --limit=50 --format="table(timestamp,severity,textPayload)"
；Agent Runtime执行
gcloud logging read "resource.type=aiplatform.googleapis.com/ReasoningEngine" --project=PROJECT --limit=50
部署后Agent返回错误在控制台打开Cloud Logging → 按服务名称（Cloud Run）或推理引擎资源（Agent Runtime）过滤 → 查找最近日志中的Python回溯信息或权限错误

Platform Registration

平台注册

For registering deployed agents with Gemini Enterprise, see 
/google-agents-cli-publish
.
将已部署的Agent注册到Gemini Enterprise，请查看
/google-agents-cli-publish
。

Related Skills

相关技能

  • /google-agents-cli-workflow
    — Development workflow, coding guidelines, and operational rules
  • /google-agents-cli-adk-code
    — ADK Python API quick reference for writing agent code
  • /google-agents-cli-eval
    — Evaluation methodology, evalset schema, and the eval-fix loop
  • /google-agents-cli-scaffold
    — Project creation and enhancement with 
    agents-cli scaffold create
    / 
    scaffold enhance
  • /google-agents-cli-observability
    — Cloud Trace, logging, BigQuery Analytics, and third-party integrations
  • /google-agents-cli-publish
    — Gemini Enterprise registration
  • /google-agents-cli-workflow
    — 开发工作流、编码规范及操作规则
  • /google-agents-cli-adk-code
    — ADK Python API快速参考，用于编写Agent代码
  • /google-agents-cli-eval
    — 评估方法论、评估集 schema 及评估-修复循环
  • /google-agents-cli-scaffold
    — 通过
    agents-cli scaffold create
    / 
    scaffold enhance
    创建和增强项目
  • /google-agents-cli-observability
    — Cloud Trace、日志、BigQuery分析及第三方集成
  • /google-agents-cli-publish
    — Gemini Enterprise注册