本頁面由 Cloud Translation API 翻譯而成。

將 A2A 代理部署至 Cloud Run

準備及設定 Agent2Agent (A2A) 代理程式，以便在 Cloud Run 上部署。

本指南涵蓋部署 A2A 代理的必要步驟：

設定專案
建立 IAM 角色
設定雲端環境
部署代理程式
偵錯部署作業失敗問題
測試及監控

查看 A2A 規格和範例代理

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

如要瞭解代理程式通訊，請參閱官方 A2A 規格和代理程式通訊概念。
探索現有的範例代理程式。
查看 ADK Cloud Run 範例。

事前準備

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.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

如要建立服務帳戶，請執行下列指令：

gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="DISPLAY_NAME"

替換下列值：

A2A_SERVICE_ACCOUNT_NAME：服務帳戶名稱
DESCRIPTION：服務帳戶的選填說明
DISPLAY_NAME：要在 Google Cloud 控制台中顯示的服務帳戶名稱

授予服務帳戶角色

如要在專案中授予帳戶所需的 IAM 角色，請按照下列步驟操作：

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
         --role="ROLE"

取代：

PROJECT_ID：專案 ID
A2A_SERVICE_ACCOUNT_NAME：服務帳戶名稱
ROLE：要新增至服務帳戶的角色

必要的角色

如要取得部署 A2A 代理程式所需的權限，請要求管理員授予下列 IAM 角色：

專案的「Cloud Run 原始碼開發人員」 (roles/run.sourceDeveloper)
專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) 專案
專案的 Secret Manager 管理員 (roles/secretmanager.admin)
服務帳戶使用者 (roles/iam.serviceAccountUser) 服務身分
Secret Manager 密鑰存取者 (roles/secretmanager.secretAccessor) 服務帳戶
Vertex AI 使用者 (roles/aiplatform.user) 服務帳戶
如果您要使用 AlloyDB for PostgreSQL 部署，請授予下列角色：
- PostgreSQL 適用的 AlloyDB 用戶端 (roles/alloydb.client) 服務帳戶
- 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) 服務帳戶

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

授予角色

控制台

前往 Google Cloud 控制台的「IAM」頁面。
前往 IAM
選取專案。
點按「 Grant access」(授予存取權)。
在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。這通常是部署 Cloud Run 服務時使用的電子郵件地址。
在「Select a role」(選取角色) 清單中，選取角色。
如要授予其他角色，請按一下「Add another role」(新增其他角色)，然後新增角色。
按一下 [儲存]。

gcloud

如要在專案中授予帳戶必要的 IAM 角色，請按照下列步驟操作：

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=PRINCIPAL \
         --role=ROLE

取代：

將 PROJECT_NUMBER 改成您的 Google Cloud 專案編號。
將 PROJECT_ID 改成您的 Google Cloud 專案 ID。
PRINCIPAL，並使用您要新增繫結的帳戶。這通常是部署 Cloud Run 服務時使用的電子郵件地址。
ROLE，並將角色新增至部署者帳戶。

準備部署 Cloud Run

本節說明準備將 A2A 代理程式部署至 Cloud Run 時，Python 程式碼範例所需的設定。

準備 A2A 代理

將範例應用程式存放區複製到本機電腦，即可擷取程式碼範例：
```
git clone https://github.com/a2aproject/a2a-samples
```

變更為包含範例程式碼的目錄：

cd a2a-samples/samples/python/agents/adk_cloud_run

設定 Cloud Run 服務的密鑰

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

代理程式需要存取外部服務才能完成工作。密鑰是授予這類存取權的安全機制。使用 AlloyDB for PostgreSQL 部署時，您需要使用者名稱和密碼。在 gcloud CLI 中執行下列指令，在 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 會自動建構容器映像檔。

Dockerfile 會決定容器映像檔的詳細資料。以下是您先前複製的範例 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 內建支援特定熱門程式設計語言，可簡化容器化程序。

Cloud Run 上的 Python 應用程式：Cloud Run 會尋找 main.py 檔案，以建構及部署 Python 服務。詳情請參閱「在 Cloud Run 上部署 Python 服務快速入門」。
Cloud Run 上的 Node.js 應用程式：Cloud Run 會尋找 index.js 檔案，以便建構及部署 Node.js 服務。請參閱將 Node.js 服務部署至 Cloud Run 快速入門導覽課程。

將 A2A 代理程式部署至 Cloud Run

使用記憶體內 TaskStore 設定或 AlloyDB for PostgreSQL 部署 A2A 應用程式。

記憶體內 TaskStore 設定會將所有資料專門儲存在 Cloud Run 容器執行個體中。也就是說，容器執行個體關閉、縮減或重新啟動時，所有工作資料都會遺失。
PostgreSQL 適用的 AlloyDB 提供資料持久性，可讓代理程式水平擴充，並確保工作在容器重新啟動、擴充事件和部署作業後仍能繼續執行。

記憶體內 TaskStore 設定適合在本地環境開發 A2A 代理程式，而 AlloyDB for PostgreSQL 則適合在正式環境中擴充 A2A 代理程式。

下列指令說明如何為 Cloud Run 服務使用以 IAM 為基礎的驗證。建議您在部署時使用 --no-allow-unauthenticated 標記，為內部 Google Cloud 用戶端 (例如 Gemini Enterprise) 設定驗證。

如果 A2A 伺服器是為公開存取而設計，且需要處理代理程式層級的驗證，您可以在部署期間指定 --allow-unauthenticated 標記。詳情請參閱「Cloud Run 公開存取驗證」。如要允許公開存取 Cloud Run 服務，您也必須使用 securitySchemes 和 security 參數，在 A2A 代理程式的資訊卡中提供重要驗證資訊。詳情請參閱「A2A 規格：SecurityScheme 物件詳細資料」。

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

如要使用記憶體內 TaskStore 設定部署 A2A 代理程式，請在包含 A2A 代理程式原始碼的目錄中執行下列指令：

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --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"

更改下列內容：

REGION：要部署服務的 Google Cloud 區域，例如 europe-west1。
PROJECT_ID：您的專案 ID。
PROJECT_NUMBER：您的專案編號。
A2A_SERVICE_ACCOUNT_NAME：A2A 服務帳戶的名稱。

使用 PostgreSQL 適用的 AlloyDB 部署

如要保留 A2A 工作，請使用 PostgreSQL 適用的 AlloyDB。如要使用 AlloyDB for PostgreSQL 部署 A2A 代理程式，做為持續性工作儲存空間，請使用下列指令：

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_NAME \
    --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"

更改下列內容：

REGION：要部署服務的 Google Cloud 區域，例如 europe-west1。
PROJECT_ID：您的專案 ID。
PROJECT_NUMBER：您的專案編號。
CLUSTER_NAME：AlloyDB for PostgreSQL 叢集的名稱。
A2A_SERVICE_ACCOUNT_NAME：A2A 服務帳戶的名稱。

偵錯部署失敗問題

如果發生錯誤或 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"
```

瞭解 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

測試及監控 A2A 代理部署作業

將 A2A 代理程式成功部署至 Cloud Run 後，請徹底測試其功能。建立完善的監控做法，確保效能和穩定性。

A2A 檢查工具：驗證代理程式是否符合規定

使用 a2a-inspector 工具檢查、偵錯及驗證已部署的 Google A2A 代理程式。這項工具可確保代理程式完全符合 A2A 規格，且運作正常。

連線成功後，檢查員會執行下列動作：

顯示代理資訊卡：自動顯示代理的資訊卡。
驗證是否符合規定：檢查資訊卡是否符合 A2A 規格。
啟用即時通訊：可與服務專員互傳訊息。
顯示原始資料：在主控台中顯示原始 JSON-RPC 2.0 訊息，以利偵錯。

透過 CLI 與已部署的 A2A 代理互動

使用A2A 範例存放區的指令列介面 (CLI) 工具，與已部署的服務互動。這個 CLI 支援以不記名權杖為基礎的驗證。

如果服務使用 IAM 驗證，請匯出 gcloud 權杖，確保互動順利進行：

export A2A_CLI_BEARER_TOKEN=$(gcloud auth print-identity-token)
# From CLI directory
uv run . --agent CLOUD_RUN_SERVICE_URL

將 CLOUD_RUN_SERVICE_URL 替換為已部署的 Cloud Run 服務網址。

注意： 成功部署及叫用後，系統會顯示代理程式資訊卡，啟動新工作並提示您輸入內容。CLI 中的每個事件都包含詳細資料，例如工作 ID、狀態和時間戳記。

在本機測試已部署的 A2A 服務

您可以在本機測試已部署的 Cloud Run 服務。實作以 IAM 為基礎的驗證時，這項功能特別實用。

測試 Cloud Run 代理程式的 IAM 驗證

與受 Identity and Access Management (IAM) 保護的 Cloud Run 服務互動的用戶端，必須具備 roles/run.invoker IAM 角色。

使用 gcloud auth print-identity-token 指令在本機測試已部署服務的驗證流程：

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" CLOUD_RUN_SERVICE_URL/.well-known/agent.json

將 CLOUD_RUN_SERVICE_URL 替換為已部署的 Cloud Run 服務網址。

將 A2A 代理部署至 Cloud Run 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

查看 A2A 規格和範例代理

事前準備

授予服務帳戶角色

必要的角色

授予角色

控制台

gcloud

準備部署 Cloud Run

準備 A2A 代理

設定 Cloud Run 服務的密鑰

用於容器化的 Dockerfile

透過原始碼部署，無須 Dockerfile

將 A2A 代理程式部署至 Cloud Run

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

使用 PostgreSQL 適用的 AlloyDB 部署

偵錯部署失敗問題

瞭解 Cloud Run 應用程式網址

測試及監控 A2A 代理部署作業

A2A 檢查工具：驗證代理程式是否符合規定

透過 CLI 與已部署的 A2A 代理互動

在本機測試已部署的 A2A 服務

測試 Cloud Run 代理程式的 IAM 驗證

將 A2A 代理部署至 Cloud Run

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