ADK部署指南

依赖要求：
agents-cli
（安装命令：
uv tool install google-agents-cli
）—— 若未安装uv，请先安装uv。

本指南优先推荐使用
agents-cli
命令——它们将Terraform、Docker和部署流程封装为经过验证的流水线。如果你的项目尚未搭建脚手架，请查看
/google-agents-cli-scaffold
以先添加部署支持。

参考文件

如需深入了解细节，请查阅

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
技能。

部署目标决策矩阵

根据你的需求选择合适的部署目标：

评估标准	Agent Runtime	Cloud Run	GKE
支持语言	Python	Python	Python（自定义容器可支持其他语言）
弹性伸缩	托管式自动伸缩（可配置最小/最大实例数、并发数）	完全可配置（最小/最大实例数、并发数、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
样本。

部署到开发环境

部署工作流

任务跟踪： 部署涉及多个连续步骤（基础设施搭建、CI/CD配置、部署、验证）。请使用任务列表跟踪这些步骤的进度——跳过某一步通常会导致后续步骤出现难以追溯的故障。

如果是原型项目（无部署目标），先增强项目配置：
```
agents-cli scaffold enhance . --deployment-target <target>
```
告知用户："评估分数已达阈值且测试通过。是否准备部署到开发环境？"
等待明确的批准
获得批准后执行：
```
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
。

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

agents-cli infra single-project

会在

deployment/terraform/single-project/

目录下执行

terraform apply

。使用此命令可在单个GCP项目中搭建无CI/CD的基础设施（服务账号、IAM绑定、遥测资源、Artifact Registry）。也可用于在进入生产环境前在单个项目中进行测试。此命令并非部署的必需步骤。

bash

# 可选——在单个GCP项目中搭建基础设施
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
参数传入服务账号。

部署参数参考

参数	描述	适用目标
`--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 Proxy	Cloud 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
参数才能继续执行。

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

完整CI/CD流水线搭建指南（前置条件、

infra cicd

参数、运行器对比、WIF认证、流水线阶段、生产环境批准流程）请查看

references/cicd-pipeline.md

。

Cloud Run专属配置

详细基础设施配置（弹性伸缩默认值、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专属配置

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

# 启动部署，不阻塞当前进程
agents-cli deploy --no-wait

# 稍后检查进度
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专属配置

详细基础设施配置（Kubernetes清单、Terraform资源、工作负载身份、会话类型、网络配置）请查看

references/gke.md

。ADK官方GKE部署文档请访问

https://adk.dev/deploy/gke/index.md

。

服务账号架构

脚手架生成的项目使用两个服务账号：

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项目的读取权限

CI/CD搭建所需权限

roles/secretmanager.admin
— 授予CI/CD项目中的Cloud Build服务账号（
```
service-<PROJECT_NUMBER>@gcp-sa-cloudbuild.iam.gserviceaccount.com
```
）。此权限允许Cloud Build访问存储在Secret Manager中的GitHub令牌。

必需启用的API

为确保技能和部署正常工作，你的项目必须启用以下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（用于API凭证）

请勿将敏感密钥作为环境变量传递，请使用GCP Secret Manager。

bash

# 创建密钥
echo -n "YOUR_API_KEY" | gcloud secrets create MY_SECRET_NAME --data-file=-

# 更新现有密钥
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")

访问。

可观测性

可观测性配置（Cloud Trace、提示响应日志、BigQuery分析、第三方集成）请查看agents-cli-observability技能。

测试已部署的Agent

测试已部署Agent的最快方式是

agents-cli run --url <service-url> --mode <a2a|adk> "your prompt"

——它会自动处理认证、会话和流式传输（支持Agent Runtime和Cloud Run）。

高级测试（自定义请求头、会话复用、脚本、负载测试）请查看

references/testing-deployed-agents.md

。

带UI的部署（IAP）

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设置。

回滚与恢复

主要的回滚机制是基于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

自定义基础设施（Terraform）

关键提示：当你的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 本地、资源导入）
常见基础设施模式

故障排查

问题	解决方案
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回溯信息或权限错误

平台注册

将已部署的Agent注册到Gemini Enterprise，请查看

/google-agents-cli-publish

。

google-agents-cli-deploy

NPX安装

标签

SKILL.md 内容（中文）

ADK部署指南

参考文件

部署目标决策矩阵

部署到开发环境

部署工作流

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

部署参数参考

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

Cloud Run专属配置

Agent Runtime专属配置

GKE专属配置

服务账号架构

CI/CD搭建所需权限

必需启用的API

Secret Manager（用于API凭证）

可观测性

测试已部署的Agent

带UI的部署（IAP）

回滚与恢复

自定义基础设施（Terraform）

故障排查

平台注册

相关技能