在 Cloud Run 託管 A2A 代理程式總覽

本指南提供總覽，說明如何準備及設定 Agent2Agent (A2A) 代理程式，以便在 Cloud Run 上部署。內容涵蓋重要步驟，例如設定雲端環境、設定必要的 Identity and Access Management (IAM) 角色，以及準備部署代理程式。

事前準備

開始開發及部署 A2A 代理程式前，請先熟悉下列概念和資源：

A2A 代理程式部署藍圖

如要部署代理程式，請完成下列步驟：

整體架構

A2A 代理程式的核心是服務和自動化調度管理層，例如 Cloud Run。這個層級會透過 API 管理與 AI 模型 (例如 Gemini 和 Vertex AI)、記憶體儲存空間 (例如 AlloyDB 和 A2A TaskStore) 和外部工具的互動。用戶端會傳送「取得服務專員卡片」或「傳送訊息」等要求，與服務專員互動，並接收工作更新。

下圖說明 A2A 代理程式系統的架構，顯示 A2A 用戶端 (使用者或代理程式) 與 A2A 代理程式互動。

A2A 代理程式架構，顯示用戶端透過服務和協調層與代理程式互動。
A2A 代理程式架構

如要瞭解 A2A 要求生命週期，請參閱「A2A 要求生命週期」一節。

Cloud Run A2A 代理程式的 IAM 角色和權限

正確設定 IAM 角色，是確保 Cloud Run 服務與其他服務安全互動的重要步驟。 Google Cloud建立專屬服務帳戶，並授予下列各節列出的特定權限，確保作業安全和效率。

建立 Cloud Run 服務帳戶

執行任何 gcloud 指令前，請務必先完成驗證。執行下列指令，登入 Google Cloud 帳戶：

gcloud auth login

為已部署的 A2A 服務執行個體建立專用服務帳戶。使用 gcloud iam service-accounts create 指令。

gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="Service account for A2A Cloud Run service" \
  --display-name="A2A Cloud Run Service Account"

將 A2A_SERVICE_ACCOUNT_NAME 改為服務帳戶名稱。

為 A2A 代理程式設定 IAM 角色

根據 A2A 代理程式互動的服務，將下列 IAM 角色指派給服務帳戶： Google Cloud

安全憑證的 Secret Manager 存取權

  • 角色： Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

  • 用途：允許 Cloud Run 服務帳戶從 Secret Manager 安全地擷取密鑰，例如資料庫憑證。

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

AI 功能的 Vertex AI 模型存取權

  • 角色： Vertex AI User (roles/aiplatform.user)

  • 用途：Cloud Run 服務帳戶必須具備這項權限，才能在 Vertex AI 模型上叫用預測 API。

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

永久儲存空間的 AlloyDB 執行個體存取權 (如適用)

  • 角色： AlloyDB Client (roles/alloydb.client) 和 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

  • 用途：允許 Cloud Run 服務身分與 AlloyDB 叢集互動，以儲存持續性工作，這對正式版 A2A 代理程式至關重要。

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

準備 A2A 代理程式，以便部署至 Cloud Run

本節說明將 A2A 代理程式部署至 Cloud Run 時所需的設定，確保雲端作業安全、有效率且可擴充。

設定 Cloud Run 服務的密鑰

使用安全機制，將所有機密憑證 (例如 API 金鑰和資料庫密碼) 提供給 A2A 伺服器。Cloud Run 支援以環境變數或動態掛接磁碟區的形式提供密鑰。詳情請參閱「在 Cloud Run 中設定密鑰」。

舉例來說，您可以使用 gcloud CLI 在 Google Secret Manager 中建立及管理資料庫使用者和密碼密鑰。詳情請參閱「建立密鑰」。

gcloud secrets create alloy_db_user --replication-policy="automatic"
# Create a file user.txt with contents of secret value
gcloud secrets versions add alloy_db_user --data-file="user.txt"

gcloud secrets create alloy_db_pass --replication-policy="automatic"
# Create a file pass.txt with contents of secret value
gcloud secrets versions add alloy_db_pass --data-file="pass.txt"

建立 Dockerfile 以進行容器化

Cloud Run 可以從已代管的容器映像檔部署服務，也可以直接從原始碼部署服務。從原始碼進行部署作業時，如果專案的根目錄中存在 Dockerfile，Cloud Run 就會自動建構容器映像檔。

以下是 A2A 代理程式部署作業的 Dockerfile 範例：

FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
EXPOSE 8080
WORKDIR /app
COPY . ./
RUN uv sync
ENTRYPOINT ["uv", "run", ".", "--host", "0.0.0.0", "--port", "8080"]

透過原始碼部署，無須 Dockerfile

如果原始碼存放區沒有 Dockerfile，Cloud Run 會內建支援某些熱門程式設計語言，簡化容器化程序。

後續步驟