AI Skills
google-agents-cli-deploy

google-agents-cli-deploy

熱門

當使用者想要「部署代理」、「部署我的 ADK 代理」、「設定 CI/CD」、「設定機密」或「疑難排解部署」，或需要 Agent Runtime、Cloud Run 或 GKE 部署目標的指引時，應使用此技能。涵蓋部署工作流程、服務帳戶、回滾和生產基礎架構。屬於 Google ADK（代理開發套件）技能套件的一部分。請勿用於 API 程式碼模式（請使用 google-agents-cli-adk-code）、評估（請使用 google-agents-cli-eval）或專案架構（請使用 google-agents-cli-scaffold）。

3081星標
487分支
更新於 2026/6/22
獲取技能源代碼

相關技能

cmux-backend2.5萬sherpa-onnx-tts39萬sherpa-onnx-tts38萬
SKILL.md
唯讀
名稱
google-agents-cli-deploy
描述

當使用者想要「部署代理」、「部署我的 ADK 代理」、「設定 CI/CD」、「設定機密」或「疑難排解部署」，或需要 Agent Runtime、Cloud Run 或 GKE 部署目標的指引時，應使用此技能。涵蓋部署工作流程、服務帳戶、回滾和生產基礎架構。屬於 Google ADK（代理開發套件）技能套件的一部分。請勿用於 API 程式碼模式（請使用 google-agents-cli-adk-code）、評估（請使用 google-agents-cli-eval）或專案架構（請使用 google-agents-cli-scaffold）。

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 設定、部署、驗證）。使用任務清單來追蹤這些步驟的進度 — 跳過某一步驟通常會導致後續步驟失敗，且難以追溯原因。

  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。

單一專案基礎架構設定（選用 — 進階）

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。

相關技能

  • /google-agents-cli-workflow — 開發工作流程、編碼指南和操作規則
  • /google-agents-cli-adk-code — ADK Python API 快速參考，用於編寫代理程式碼
  • /google-agents-cli-eval — 評估方法、資料集架構和評估-修正循環
  • /google-agents-cli-scaffold — 使用 agents-cli scaffold create / scaffold enhance 建立和增強專案
  • /google-agents-cli-observability — Cloud Trace、記錄、BigQuery Analytics 和第三方整合
  • /google-agents-cli-publish — Gemini Enterprise 註冊