google-agents-cli-deploy

Name: google-agents-cli-deploy
Author: google

ADK 部署指南

需求： agents-cli（uv tool install google-agents-cli）— 如有需要，請先安裝 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 清單、Workload Identity、工作階段類型、網路
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 範例、負載測試

可觀測性： 請參閱 /google-agents-cli-observability 技能以了解 Cloud Trace、提示-回應記錄、BigQuery Analytics 和第三方整合。

部署目標決策矩陣

根據您的需求選擇合適的部署目標：

條件	Agent Runtime	Cloud Run	GKE
語言	Python	Python	Python（+ 其他語言透過自訂容器）
擴展	受管自動擴展（可設定最小/最大、並行數）	完全可設定（最小/最大執行個體、並行數、CPU 配置）	完整的 Kubernetes 擴展（HPA、VPA、節點自動佈建）
網路	支援 VPC-SC 和 PSC-I（透過網路附加元件實現私有 VPC 連線）	完整 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-小時 + 記憶體-小時（閒置時不計費）	每執行個體-秒 + 最小執行個體成本	節點池成本（永遠開啟或自動佈建）
設定複雜度	較低（受管、專為代理設計）	中等（Dockerfile、Terraform、網路）	較高（需要 Kubernetes 專業知識）
最適合	受管基礎架構、最少維運	自訂基礎架構、事件驅動工作負載	完整的 Kubernetes 控制

詢問使用者哪個部署目標符合他們的需求。每個都是有效的生產選擇，但有不同的取捨。

產品名稱對應：「Agent Engine」/「Vertex AI Agent Engine」現在是 Agent Runtime。使用 --deployment-target agent_runtime。

環境/排程/事件驅動代理： Agent Runtime 不支援 Pub/Sub、Eventarc 或 Cloud Scheduler 觸發。對於這些工作負載，請使用 Cloud Run（建議）或 GKE。請參閱 /google-agents-cli-adk-code（references/adk-python.md，第 12 節「事件驅動/環境代理」）以了解 trigger_sources 模式。

OAuth / 使用者同意代理： 對於需要 OAuth 2.0 使用者同意（例如存取 Google Drive、日曆或其他使用者範圍 API）的代理，請使用 Agent Runtime 搭配 Gemini Enterprise。Cloud Run 目前不支援受管 OAuth 流程。請參閱 /google-agents-cli-workflow 第一階段的 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）。也可用於在單一專案中測試，然後再進入生產環境。這不是部署的必要條件。

# 選用 — 在單一 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`	已部署代理的服務帳戶電子郵件	全部
`--service-name`	覆寫已部署的服務名稱（Cloud Run 服務或 Agent Runtime 顯示名稱）；預設為專案名稱。如果覆寫，請考慮更新您的 Terraform 和 CI（如果有的話）— 它們會根據專案名稱命名資源。不支援 GKE，其名稱完全由 Terraform 擁有。	Agent Runtime、Cloud Run
`--secrets`	逗號分隔的 `ENV=SECRET` 或 `ENV=SECRET:VERSION` 配對	Agent Runtime、Cloud Run
`--update-env-vars`	逗號分隔的 `KEY=VALUE` 環境變數	Agent Runtime、Cloud Run
`--agent-identity`	啟用代理身分（預覽版）	Agent Runtime
`--network-attachment`	PSC 介面的網路附加元件資源名稱（啟用私有 VPC 連線）	Agent Runtime
`--dns-peering-domain`	DNS 對等網域後綴，例如 `my-internal.corp.`（需要 `--network-attachment`）	Agent Runtime
`--dns-peering-project`	託管 DNS 對等 Cloud DNS 受管區域的專案 ID（需要 `--network-attachment`）	Agent Runtime
`--dns-peering-network`	目標專案中用於 DNS 對等的 VPC 網路名稱（需要 `--network-attachment`）	Agent Runtime
`--memory`	記憶體限制（預設：`4Gi`）	Agent Runtime、Cloud Run
`--cpu`	CPU 限制（預設：`1`）	Agent Runtime、Cloud Run
`--min-instances`	最小執行個體數（預設：`1`）	Agent Runtime、Cloud Run
`--max-instances`	最大執行個體數（預設：`10`）	Agent Runtime、Cloud Run
`--concurrency`	每個容器的並行請求數（預設：`8`；請參閱調整部署規模）	Agent Runtime、Cloud Run
`--num-workers`	每個容器的工作者處理程序數（預設：`1`）	Agent Runtime
`--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 部署： 如果您需要 agents-cli 旗標未公開的功能，請使用 --dry-run（或 -n）來列印完整的 gcloud 指令，複製它，並根據需要新增其他引數。

專案確認： 如果專案是自動解析的（未透過 --project 傳遞），則指令會在互動模式下提示確認。由於代理通常以非互動模式執行，如果您依賴自動專案解析，則必須傳遞 --no-confirm-project 才能繼續。

調整部署規模

預設值（在 Agent Runtime、Cloud Run 和產生的 service.tf 上相同）：--cpu 1、--memory 4Gi、--num-workers 1、--concurrency 8、--min-instances 1、--max-instances 10。

這些參數是耦合的 — 應一起調整：

工作者 = vCPU。 每個工作者是一個 GIL 綁定的處理程序，會耗盡一個核心，因此請將 --num-workers 與 --cpu 一起提高（例如 --cpu 4 → --num-workers 4），否則您將為閒置的核心付費。
記憶體限制並行數。 每個並行請求在等待模型時，會將其完整的工作集（上下文視窗、歷史記錄、RAG 區塊、回應緩衝區）保留在記憶體中，因此峰值 ≈ 基礎 + concurrency × per-request memory。記憶體（而非 CPU）是第一個限制，因此在沒有 --memory 的情況下提高 --concurrency 是主要的 OOM 原因。
並行預設值較保守。 非同步工作者在等待模型時可以服務許多並行請求，但每個請求的記憶體因代理而異，因此 8 可以保護記憶體密集型（RAG/多模態）代理。輕量代理可以在負載測試後將其提高到 16-32+。請參閱未充分利用的非同步工作者。

# 4 倍吞吐量：調整每個參數，而不僅僅是一個
agents-cli deploy --cpu 4 --num-workers 4 --concurrency 16 --memory 16Gi

使用架構化的負載測試進行調整（tests/load_test/，在本地或 CI/CD 暫存管道中執行）：驅動負載，觀察最大延遲和記憶體/OOM 重新啟動，然後進行調整 — 高最大延遲 → 提高並行數（+ 工作者/cpu）；OOM → 提高記憶體或降低並行數。

--num-workers 僅限 Agent Runtime（Cloud Run 執行一個 uvicorn 處理程序）。在 GKE 上，這些旗標會被拒絕 — 透過 deployment/terraform/ 下的 Terraform 清單和 HorizontalPodAutoscaler 來調整規模。

生產部署 — 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 上部署事件驅動/環境代理，請參閱 ambient-expense-agent 範例和 /google-agents-cli-adk-code（references/adk-python.md，第 12 節「事件驅動/環境代理」）以了解 trigger_sources 模式。

Agent Runtime 特定說明

Agent Runtime 是一項受管的 Vertex AI 服務，用於部署 Python ADK 代理。使用基於原始碼的部署（無 Dockerfile），透過 deploy.py 和 AdkApp 類別。

Agent Runtime 沒有 gcloud CLI。 透過 agents-cli deploy 或 deploy.py 進行部署。透過 Python vertexai.Client SDK 進行查詢。

部署可能需要 5-10 分鐘。使用 --no-wait 啟動部署並立即返回，然後稍後使用 --status 檢查：

# 啟動部署而不阻塞
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-runtime/index.md。

GKE 特定說明

如需詳細的基礎架構設定（Kubernetes 清單、Terraform 資源、Workload Identity、工作階段類型、網路），請參閱 references/gke.md。如需 ADK 關於 GKE 部署的文件，請擷取 https://adk.dev/deploy/gke/index.md。

服務帳戶架構

已建立架構的專案使用兩個服務帳戶：

app_sa（每個環境）— 已部署代理的執行時期身分。角色定義在 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 錯誤：

「Cloud Run 權限遭拒」→ cicd_runner_sa 在目標專案中缺少部署角色
「無法扮演服務帳戶」→ app_sa 缺少 iam.serviceAccountUser 綁定
「機密存取遭拒」→ app_sa 缺少 secretmanager.secretAccessor
「Cloud SQL 連線失敗/未授權」→ 執行時期服務帳戶缺少 roles/cloudsql.client
「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：

gcloud services enable cloudbuild.googleapis.com secretmanager.googleapis.com run.googleapis.com --project=YOUR_PROJECT_ID

Secret Manager（用於 API 憑證）

與其將敏感金鑰作為環境變數傳遞，不如使用 GCP Secret Manager。

# 建立機密
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，將 secretmanager.secretAccessor 授予 app_sa。對於 Agent Runtime，將其授予平台管理的 SA（service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com）。對於 GKE，將 secretmanager.secretAccessor 授予 app_sa。透過 Kubernetes Secrets 或直接透過 Secret Manager API 搭配 Workload Identity 來存取機密。

在部署時傳遞機密（Agent Runtime、Cloud Run）：

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 SQL 權限（手動部署）

在手動部署中將 Cloud SQL 與 Cloud Run 搭配使用時（例如在非 Terraform 設定中新增 --add-cloudsql-instances），您必須手動將 Cloud SQL Client 角色授予執行時期服務帳戶。

如果沒有此角色，部署可能會成功，但在執行時期會因 cloudsql.instances.get 授權錯誤而失敗。

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:YOUR_RUNTIME_SA_EMAIL" \
  --role="roles/cloudsql.client"

注意： 在完整的 Terraform 管理設定（infra cicd / infra single-project）中，此角色會自動設定和管理。

可觀測性

請參閱 agents-cli-observability 技能以了解可觀測性設定（Cloud Trace、提示-回應記錄、BigQuery Analytics、第三方整合）。

測試已部署的代理

測試已部署代理的最快方法是 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 帳戶才能存取。透過在部署時新增 --iap 旗標來啟用它（僅限 Cloud Run）：agents-cli deploy --iap。

對於具有自訂前端的 Agent Runtime，請使用解耦部署 — 將前端單獨部署到 Cloud Run 或 Cloud Storage，連接到 Agent Runtime 後端 API。

如需有關 IAP 與 Cloud Run 的更多資訊，請參閱 Cloud Console IAP 設定。

回滾與復原

主要的回滾機制是基於 git：修正問題、提交並推送到 main。CI/CD 管道會自動建置並透過暫存 → 生產部署新版本。

如需在沒有新提交的情況下立即回滾 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 Runtime 不支援基於修訂版的回滾 — 請透過 agents-cli deploy 修正並重新部署。

對於 GKE 回滾，請使用 kubectl rollout undo：

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

自訂基礎架構（Terraform）

重要事項：當您的代理需要自訂基礎架構（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`（而非預設的運算 SA）
Cloud SQL 連線失敗 / 403	使用手動部署時，將 `roles/cloudsql.client` 授予執行時期服務帳戶
部署時出現 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 輸出中
部署失敗或代理無回應	檢查 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`
部署後代理傳回錯誤	開啟主控台中的 Cloud Logging → 依服務名稱（Cloud Run）或推理引擎資源（Agent Runtime）篩選 → 在最近的日誌項目中尋找 Python 回溯或權限錯誤

平台註冊

如需將已部署的代理註冊到 Gemini Enterprise，請參閱 /google-agents-cli-publish。

您可能也喜歡

import-infrastructure-as-code

37Kdevops-cloud

Import existing Azure resources into Terraform using Azure CLI discovery and Azure Verified Modules (AVM). Use when asked to reverse-engineer live Azure infrastructure, generate Infrastructure as Code from existing subscriptions/resource groups/resource IDs, map dependencies, derive exact import addresses from downloaded module source, prevent configuration drift, and produce AVM-based Terraform files ready for validation and planning across any Azure resource type.

github

獲取

sandbox-sdk

2Kdevops-cloud

建立沙箱應用程式以安全執行程式碼。當建置 AI 程式碼執行、程式碼直譯器、CI/CD 系統、互動式開發環境或執行不受信任的程式碼時載入。涵蓋 Sandbox SDK 生命週期、指令、檔案、程式碼直譯器和預覽網址。傾向從 Cloudflare 文件檢索而非預先訓練的知識。

cloudflare

獲取

deployment-patterns

230Kdevops-cloud

Deployment workflows, CI/CD pipeline patterns, Docker containerization, health checks, rollback strategies, and production readiness checklists for web applications.

affaan-m

獲取

繼續探索

瀏覽 devops-cloud 熱門 Skills 最近更新