將 A2A 代理部署至 Cloud Run

本文說明如何將 A2A 代理程式部署至 Cloud Run。這些步驟可確保雲端環境中的作業安全、有效率且可擴充。

事前準備

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. 如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

  6. 如要初始化 gcloud CLI，請執行下列指令： 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. 如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

  11. 如要初始化 gcloud CLI，請執行下列指令： 

    gcloud init
  12. 前往包含 A2A 代理程式原始碼的目錄：

      cd PATH_TO_YOUR_AGENT_DIRECTORY

  13. 如需必要的 IAM 角色和權限，請參閱 Cloud Run A2A 代理程式的 IAM 角色和權限。

    14. 設定 Cloud Run 服務驗證

    A2A 代理程式開發完成並準備好部署環境後，您必須設定驗證，並使用 gcloud run deploy 指令將代理程式部署至 Cloud Run。

    請使用下列任一選項，為 A2A Cloud Run 服務設定存取權和驗證：

    • 內部 Google Cloud 用戶端的 IAM 驗證： 對於在 Google Cloud內運作的用戶端 (例如 Agentspace 等內部服務)，建議採用 IAM 驗證這種安全做法。這些用戶端會使用服務帳戶，且需要 Cloud Run 叫用者 (roles/run.invoker) 角色，才能叫用 Cloud Run 服務。詳情請參閱Cloud Run 服務對服務驗證。

      如要為 Cloud Run 服務啟用 IAM 驗證，請按照下列步驟操作：

      • 部署時必須使用 --no-allow-unauthenticated 旗標。

    • 公開曝光的代理程式層級驗證：如果您的 A2A 伺服器是專為公開存取而設計，則會處理代理程式層級驗證。

      如要允許公開存取 Cloud Run 服務，請按照下列步驟操作：

    將 A2A 代理程式部署至 Cloud Run

    使用現有的 ADK 範例部署 A2A 代理程式。使用 gcloud run deploy 指令時，請指定下列參數：

    • 存取權設定：
      • 如要使用以 IAM 為基礎的服務驗證，請使用 --no-allow-unauthenticated 旗標。
      • 如要在網際網路上公開服務，請使用 --allow-unauthenticated 旗標。
    • 記憶體：容器執行個體執行的最低記憶體需求為 1Gi。
    • 密鑰：如要使用密鑰，請指定 DB_USER 和 DB_PASS 參數。
    • 服務帳戶：如要指定服務帳戶，請使用 a2a-service-account 參數。
    • 環境變數：如要指定環境變數，請使用下列變數：
      • APP_URL
      • DB_INSTANCE
      • DB_NAME
      • GOOGLE_GENAI_USE_VERTEXAI = true

    如要進行本機測試，請使用記憶體內 TaskStore 設定。 如要將服務部署至正式環境，您必須為正式版 A2A 伺服器使用持續性儲存空間。請參閱「AlloyDB for PostgreSQL 部署作業」一節中的範例。

    使用記憶體內 TaskStore 設定進行部署

    如要使用記憶體內 TaskStore 設定部署 A2A 代理程式，請使用下列 gcloud run deploy 指令：

    gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=a2a-service-account \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,\
      GOOGLE_CLOUD_PROJECT="PROJECT_ID",\
      GOOGLE_CLOUD_LOCATION="REGION",\
      APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app"

    如果您不在包含 A2A 代理程式原始碼的目錄中，請使用代理程式程式碼的完整路徑更新 --source 標記。

    更改下列內容：

    • REGION：要部署服務的 Google Cloud 區域。例如 europe-west1。
    • PROJECT_ID：您的專案 ID。
    • PROJECT_NUMBER：您的專案編號。

    使用 PostgreSQL 適用的 AlloyDB 部署

    如要保留 A2A 工作，請使用 PostgreSQL 適用的 AlloyDB。如要使用 AlloyDB for PostgreSQL 部署 A2A 代理程式，以永久儲存工作，請使用下列 gcloud run deploy 指令：

    gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --update-secrets=DB_USER=alloy_db_user:latest,DB_PASS=alloy_db_pass:latest \
    --service-account=a2a-service-account \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,\
      GOOGLE_CLOUD_PROJECT="PROJECT_ID",\
      GOOGLE_CLOUD_LOCATION="REGION",\
      APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app",\
      USE_ALLOY_DB="True",\
      DB_INSTANCE="projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/instances/primary-instance",\
      DB_NAME="postgres"

    如果您不在包含 A2A 代理程式原始碼的目錄中，請使用代理程式程式碼的完整路徑更新 --source 標記。

    更改下列內容：

    • REGION：要部署服務的 Google Cloud 區域。例如 europe-west1。
    • PROJECT_ID：您的專案 ID。
    • PROJECT_NUMBER：您的專案編號。
    • ：PostgreSQL 適用的 AlloyDB 叢集名稱。CLUSTER_NAME

    瞭解 Cloud Run 應用程式網址

    成功部署後，Cloud Run 會自動提供 run.app 網址，做為查詢有效 A2A 服務的端點。如果服務名稱夠短，網址就會是確定且可預測的。

    • Cloud Run 網址格式： https://TAG---SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
    • 範例網址： https://sample-a2a-agent-1234.europe-west1.run.app

    偵錯部署失敗問題

    如要偵錯 Cloud Run 部署作業失敗問題，請考慮下列事項：

    • 詳細記錄：如要查看詳細的部署記錄，請在 gcloud run deploy 指令中設定 --verbosity=info 旗標。

    • 網址不符：如果部署指令傳回的 run.app 網址與預期的確定性網址不同，請更新 Cloud Run 服務的 APP_URL 環境變數：

      1. 請使用下列指令更新 APP_URL 環境變數：

        gcloud run services update SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION" \
    --update-env-vars=APP_URL="CLOUD_RUN_SERVICE_URL"

        更改下列內容：

        • SERVICE_NAME：Cloud Run 服務名稱。
        • PROJECT_ID：您的專案 ID。
        • REGION：要部署服務的 Google Cloud 區域。例如 europe-west1。
        • CLOUD_RUN_SERVICE_URL：Cloud Run 服務的網址。

      2. 說明服務，確認 APP_URL 是否已正確更新：

        gcloud run services describe SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION"