adk-deploy-guide

ADK 部署指南

已搭建脚手架的项目？ 请在本指南中使用 make 命令——它们将 Terraform、Docker 和部署整合到经过测试的流水线中。

未搭建脚手架？ 请参阅下方的快速部署，或查看 ADK 部署文档。 对于生产基础设施，请使用 /adk-scaffold 搭建脚手架。

参考文件

如需深入了解，请查阅 references/ 中的这些参考文件：

• cloud-run.md — 扩缩容默认值、Dockerfile、会话类型、网络
• agent-engine.md — deploy.py CLI、AdkApp 模式、Terraform 资源、部署元数据、CI/CD 差异
• gke.md — GKE Autopilot 集群、由 Terraform 管理的 Kubernetes 资源、Workload Identity、会话类型、网络
• terraform-patterns.md — 自定义基础设施、IAM、状态管理、导入资源
• event-driven.md — 通过自定义 fast_api_app.py 端点触发 Pub/Sub、Eventarc、BigQuery Remote Function

可观测性： 有关 Cloud Trace、提示词-响应日志、BigQuery Analytics 和第三方集成，请参阅 adk-observability-guide 技能。

---

部署目标决策矩阵

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

标准	Agent Engine	Cloud Run	GKE
语言	Python	Python	Python（也可通过自定义容器使用其他语言）
扩缩容	托管式自动扩缩容（可配置最小值/最大值、并发数）	完全可配置（最小值/最大值实例数、并发数、CPU 分配）	完整的 Kubernetes 扩缩容（HPA、VPA、节点自动预配）
网络	支持 VPC-SC 和 PSC	完整的 VPC 支持、直接 VPC 出口、IAP、入口规则	完整的 Kubernetes 网络
会话状态	原生 VertexAiSessionService（持久化、托管）	内存中（开发环境）、Cloud SQL 或 Agent Engine 会话后端	内存中（开发环境）、Cloud SQL 或 Agent Engine 会话后端
批处理/事件处理	不支持	用于 Pub/Sub、Eventarc、BigQuery 的 /invoke 端点	自定义（Kubernetes Jobs、Pub/Sub）
成本模型	vCPU 小时 + 内存小时（空闲时不计费）	每实例秒费用 + 最低实例成本	节点池成本（常驻或自动预配）
设置复杂度	较低（托管式，专为 Agent 打造）	中等（Dockerfile、Terraform、网络）	较高（需要 Kubernetes 专业知识）
适用场景	托管基础设施、尽量减少运维	自定义基础设施、事件驱动型工作负载	完整的 Kubernetes 控制

请询问用户哪个部署目标符合其需求。每种方案都是有效的生产环境选择，只是各有取舍。

---

快速部署（ADK CLI）

适用于未使用 Agent Starter Pack 搭建脚手架的项目。无需 Makefile、Terraform 或 Dockerfile。

# Cloud Run
adk deploy cloud_run --project=PROJECT --region=REGION path/to/agent/

# Agent Engine
adk deploy agent_engine --project=PROJECT --region=REGION path/to/agent/

# GKE (requires existing cluster)
adk deploy gke --project=PROJECT --cluster_name=CLUSTER --region=REGION path/to/agent/

所有命令都支持使用 --with_ui 部署 ADK 开发 UI。Cloud Run 还支持在 -- 后添加额外的 gcloud 标志（例如，-- --no-allow-unauthenticated）。

如需查看完整标志参考，请运行 adk deploy --help 或查阅 ADK 部署文档。

对于 CI/CD、可观测性或生产基础设施，请使用 /adk-scaffold 搭建脚手架，并参阅以下章节。

---

开发环境设置与部署（已搭建脚手架的项目）

设置开发基础设施（可选）

make setup-dev-env 会在 deployment/terraform/dev/ 中运行 terraform apply。这会配置支持性基础设施：

• 服务账号（供 Agent 使用的 app_sa，用于运行时权限）
• Artifact Registry 仓库（用于容器镜像）
• IAM 绑定（为应用 SA 授予必要角色）
• 遥测资源（Cloud Logging 存储桶、BigQuery 数据集）
• deployment/terraform/dev/ 中定义的任何自定义资源

此步骤可选——无需此步骤，make deploy 也能正常工作（Cloud Run 会通过 gcloud run deploy --source . 即时创建服务）。不过，运行此步骤可为你配置合适的服务账号、可观测性和 IAM 设置。

make setup-dev-env

注意： make deploy 不会自动使用 Terraform 创建的 app_sa。请显式传入 --service-account，或更新 Makefile。

部署

1. 通知人工审批者：“评估得分达到阈值，测试也已通过。准备好部署到开发环境了吗？”
2. 等待明确批准
3. 获得批准后：make deploy

重要： 未经人工明确批准，切勿运行 make deploy。

---

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

适用场景： 生产应用、需要从预发布环境晋级到生产环境的团队。

前提条件：

1. 项目不得位于被 Git 忽略的文件夹中
2. 用户必须提供预发布环境和生产环境的 GCP 项目 ID
3. GitHub 仓库名称和所有者

步骤：

1. 如果是原型，请先使用 Agent Starter Pack CLI 添加 Terraform/CI-CD 文件（完整选项请参阅 /adk-scaffold）：

   uvx agent-starter-pack enhance . --cicd-runner github_actions -y -s
   

2. 确保已登录 GitHub CLI：

   gh auth login  # (skip if already authenticated)
   

3. 运行 setup-cicd：

   uvx agent-starter-pack setup-cicd \
     --staging-project YOUR_STAGING_PROJECT \
     --prod-project YOUR_PROD_PROJECT \
     --repository-name YOUR_REPO_NAME \
     --repository-owner YOUR_GITHUB_USERNAME \
     --auto-approve \
     --create-repository
   

4. 推送代码以触发部署

setup-cicd 的关键标志

标志	说明
--staging-project	预发布环境的 GCP 项目 ID
--prod-project	生产环境的 GCP 项目 ID
--repository-name / --repository-owner	GitHub 仓库名称和所有者
--auto-approve	跳过 Terraform 计划确认提示
--create-repository	如果 GitHub 仓库不存在，则创建该仓库
--cicd-project	用于 CI/CD 基础设施的独立 GCP 项目。默认为生产项目
--local-state	在本地而非 GCS 中存储 Terraform 状态（参阅 references/terraform-patterns.md）

运行 uvx agent-starter-pack setup-cicd --help 查看完整的标志参考（Cloud Build 选项、开发项目、区域等）。

选择 CI/CD 运行器

运行器	优点	缺点
github_actions（默认）	无需 PAT，使用 gh auth，基于 WIF，完全自动化	需要进行 GitHub CLI 身份验证
google_cloud_build	与 GCP 原生集成	需要交互式浏览器授权（或在程序化模式下使用 PAT + 应用安装 ID）

身份验证的工作原理（WIF）

两个运行器都使用工作负载身份联合（WIF）——GitHub/Cloud Build OIDC 令牌由 GCP 工作负载身份池信任，该身份池授予对 cicd_runner_sa 的模拟权限。无需长期有效的服务账号密钥。setup-cicd 中的 Terraform 会自动创建身份池、提供商和 SA 绑定。如果身份验证失败，请在 CI/CD Terraform 目录中重新运行 terraform apply。

CI/CD 流水线阶段

流水线分为三个阶段：

1. CI（PR 检查） — 在拉取请求时触发。运行单元测试和集成测试。
2. 预发布 CD — 合并到 main 时触发。构建容器、部署到预发布环境并运行负载测试。

   路径筛选器： 预发布 CD 使用 paths: ['app/**']——只有 app/ 下的文件发生变更时才会触发。setup-cicd 后的首次推送不会触发预发布 CD，除非你修改 app/ 中的内容。如果推送后没有任何操作，这就是原因。

3. 生产 CD — 通过 workflow_run 在预发布部署成功后触发。部署到生产环境前可能需要手动批准。

   批准方式： 前往 GitHub Actions → 生产工作流运行记录 → 点击 "Review deployments" → 批准待处理的 production 环境。这是 GitHub 的环境保护规则，不是自定义机制。

重要： setup-cicd 会创建基础设施，但不会自动部署。Terraform 会配置所有必需的 GitHub 密钥和变量（WIF 凭据、项目 ID、服务账号）。推送代码以触发流水线：

git add . && git commit -m "Initial agent implementation"
git push origin main

批准生产部署：

# GitHub Actions: Approve via repository Actions tab (environment protection rules)

# Cloud Build: Find pending build and approve
gcloud builds list --project=PROD_PROJECT --region=REGION --filter="status=PENDING"
gcloud builds approve BUILD_ID --project=PROD_PROJECT

---

Cloud Run 相关说明

有关详细的基础设施配置（扩缩容默认值、Dockerfile、FastAPI 端点、会话类型、网络），请参阅 references/cloud-run.md。有关 Cloud Run 部署的 ADK 文档，请获取 https://adk.dev/deploy/cloud-run/index.md。

---

Agent Engine 相关说明

Agent Engine 是一项托管的 Vertex AI 服务，用于部署 Python ADK Agent。它通过 deploy.py 和 AdkApp 类进行基于源代码的部署（无需 Dockerfile）。

Agent Engine 没有 gcloud CLI。 请通过 deploy.py 或 adk deploy agent_engine 进行部署。请通过 Python vertexai.Client SDK 查询。

部署可能需要 5-10 分钟。如果 make deploy 超时，请检查引擎是否已创建，并手动将引擎资源 ID 填入 deployment_metadata.json（详情请参阅参考文档）。

有关详细的基础设施配置（deploy.py 标志、AdkApp 模式、Terraform 资源、部署元数据、会话/构件服务、CI/CD 差异），请参阅 references/agent-engine.md。有关 Agent Engine 部署的 ADK 文档，请获取 https://adk.dev/deploy/agent-engine/index.md。

---

GKE 相关说明

有关详细的基础设施配置（由 Terraform 管理的 Kubernetes 资源、Workload Identity、会话类型、网络），请参阅 references/gke.md。有关 GKE 部署的 ADK 文档，请获取 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 项目中（默认是生产项目），需要在预发布和生产两个项目中都拥有权限。

请检查 deployment/terraform/iam.tf，了解确切的角色绑定。跨项目权限（Cloud Run 服务代理、Artifact Registry 访问权限）也在此配置。

常见的 403 错误：

• "Permission denied on Cloud Run" → cicd_runner_sa 缺少目标项目中的部署角色
• "Cannot act as service account" → app_sa 缺少 iam.serviceAccountUser 绑定
• "Secret access denied" → app_sa 缺少 secretmanager.secretAccessor
• "Artifact Registry read denied" → Cloud Run 服务代理缺少 CI/CD 项目中的读取权限

---

Secret Manager（用于 API 凭据）

不要将敏感密钥作为环境变量传递，而应使用 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=-

授予访问权限： 对于 Cloud Run，将 secretmanager.secretAccessor 授予 app_sa。对于 Agent Engine，将其授予平台管理的 SA（service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com）。对于 GKE，将 secretmanager.secretAccessor 授予 app_sa。通过 Kubernetes Secrets 或使用 Workload Identity 直接调用 Secret Manager API 来访问密钥。

在部署时传递密钥（Agent Engine）：

make deploy SECRETS="API_KEY=my-api-key,DB_PASS=db-password:2"

格式：ENV_VAR=SECRET_ID 或 ENV_VAR=SECRET_ID:VERSION（默认使用 latest）。在代码中通过 os.environ.get("API_KEY") 访问。

---

可观测性

请参阅 adk-observability-guide 技能，了解可观测性配置（Cloud Trace、提示词-响应日志记录、BigQuery Analytics、第三方集成）。

---

测试已部署的 Agent

Agent Engine 部署

选项 1：测试 Notebook

jupyter notebook notebooks/adk_app_testing.ipynb

选项 2：Python 脚本

import json
import vertexai

with open("deployment_metadata.json") as f:
    engine_id = json.load(f)["remote_agent_engine_id"]

client = vertexai.Client(location="us-central1")
agent = client.agent_engines.get(name=engine_id)

async for event in agent.async_stream_query(message="Hello!", user_id="test"):
    print(event)

选项 3：Playground

make playground

Cloud Run 部署

默认需要身份验证。 Cloud Run 部署时使用 --no-allow-unauthenticated，因此所有请求都需要带有身份令牌的 Authorization: Bearer 标头。收到 403？你很可能缺少此标头。要允许公开访问，请使用 --allow-unauthenticated 重新部署。

SERVICE_URL="https://SERVICE_NAME-PROJECT_NUMBER.REGION.run.app"
AUTH="Authorization: Bearer $(gcloud auth print-identity-token)"

# Test health endpoint
curl -H "$AUTH" "$SERVICE_URL/"

# Step 1: Create a session (required before sending messages)
curl -X POST "$SERVICE_URL/apps/app/users/test-user/sessions" \
  -H "Content-Type: application/json" \
  -H "$AUTH" \
  -d '{}'
# → returns JSON with "id" — use this as SESSION_ID below

# Step 2: Send a message via SSE streaming
curl -X POST "$SERVICE_URL/run_sse" \
  -H "Content-Type: application/json" \
  -H "$AUTH" \
  -d '{
    "app_name": "app",
    "user_id": "test-user",
    "session_id": "SESSION_ID",
    "new_message": {"role": "user", "parts": [{"text": "Hello!"}]}
  }'

常见错误： 使用 {"message": "Hello!", "user_id": "...", "session_id": "..."} 会返回 422 Field required。ADK HTTP 服务器要求使用上方所示的 new_message / parts 架构，并且会话必须已存在。

GKE 部署

GKE LoadBalancer 服务默认公开访问，无需身份验证标头（与 Cloud Run 不同）。请参阅 references/gke.md，查看 curl 示例和端点详情。

负载测试

make load-test

请参阅 tests/load_test/README.md，了解配置、默认设置和 CI/CD 集成详情。

---

使用 UI 部署（IAP）

如需通过受 Google 身份验证保护的 Web UI 暴露 Agent：

# Deploy with IAP (built-in framework UI)
make deploy IAP=true

# Deploy with custom frontend on a different port
make deploy IAP=true PORT=5173

IAP（Identity-Aware Proxy）可保护 Cloud Run 服务，只有经授权的 Google 账号才能访问。部署后，请通过 Cloud Console IAP 设置授予用户访问权限。

对于带有自定义前端的 Agent Engine，请使用解耦部署：将前端单独部署到 Cloud Run 或 Cloud Storage，并连接到 Agent Engine 后端 API。

---

回滚与恢复

主要回滚机制基于 git：修复问题、提交并推送到 main。CI/CD 流水线会自动构建新版本，并按 staging → production 的顺序部署。

若要在不创建新提交的情况下立即回滚 Cloud Run，请使用修订版本流量切换：

gcloud run revisions list --service=SERVICE_NAME --region=REGION
gcloud run services update-traffic SERVICE_NAME \
  --to-revisions=REVISION_NAME=100 --region=REGION

Agent Engine 不支持基于修订版本的回滚；请修复问题并通过 make deploy 重新部署。

对于 GKE 回滚，请使用 kubectl rollout undo：

kubectl rollout undo deployment/DEPLOYMENT_NAME -n NAMESPACE
kubectl rollout status deployment/DEPLOYMENT_NAME -n NAMESPACE

---

自定义基础设施（Terraform）

有关自定义基础设施模式（Pub/Sub、BigQuery、Eventarc、Cloud SQL、IAM），请参阅 references/terraform-patterns.md，了解：

• 自定义 Terraform 文件的存放位置（开发环境与 CI/CD）
• 资源示例（Pub/Sub、BigQuery、Eventarc 触发器）
• 自定义资源的 IAM 绑定
• Terraform 状态管理（远程与本地、导入资源）
• 常见基础设施模式

---

故障排除

问题	解决方案
Terraform 状态已锁定	在 deployment/terraform/ 中运行 terraform force-unlock -force LOCK_ID
GitHub Actions 身份验证失败	在 CI/CD terraform 目录中重新运行 terraform apply；验证 WIF pool/provider
Cloud Build 授权待处理	改用 github_actions runner
资源已存在	使用 terraform import（参见 references/terraform-patterns.md）
Agent Engine 部署超时 / 卡住	部署需要 5-10 分钟；检查是否已创建引擎（参见 Agent Engine Specifics）
Secret 不可用	确认已向 app_sa 授予 secretAccessor（而非默认的 compute SA）
部署时出现 403	检查 deployment/terraform/iam.tf——目标项目中的 cicd_runner_sa 需要部署和 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 输出中