使用 Cloud Run 託管 A2UI 代理程式

本教學課程說明如何將使用 Google Agent Development Kit (ADK) 和 A2UI 擴充功能建構的 Agent-to-Agent (A2A) 代理部署至 Cloud Run。您也會瞭解如何向 Gemini Enterprise 註冊已部署的代理程式。

本教學課程的程式碼範例具有下列資料夾結構。

教學課程資料夾結構

專案的資料夾結構如下：

檔案/目錄 說明
examples/0.8/ 包含範例設定或資料的目錄。
__init__.py 將目錄標示為 Python 套件。
agent.py 定義代理、技能和行為。
agent_executor.py 管理執行流程和工具互動。
contact_data.json 代理使用的範例資料 (例如模擬聯絡人)。
deploy.sh 用於建構代理程式並部署至 Cloud Run 的指令碼。
main.py 主要應用程式進入點 (FastAPI 應用程式)。
prompt_builder.py 協助建構模型提示。
pyproject.toml 專案設定和依附元件。
tools.py 定義代理程式可使用的工具 (函式)。

事前準備

開始之前，請確認您具備以下項目：

  • Discovery Engine 管理員角色。

  • 現有的 Gemini Enterprise 應用程式。如要建立應用程式，請參閱「建立應用程式」。

  • 複製存放區，然後前往 cloud_run 範例目錄：

    git clone https://github.com/google/A2UI.git
cd A2UI/samples/agent/adk/gemini_enterprise/cloud_run

啟用 API

為專案啟用下列 API：

控制台

啟用下列 API：

  • Agent Platform API
  • Cloud Build API
  • Artifact Registry API
  • Cloud Run API
  • Cloud Logging API
  • Discovery Engine API
  • Cloud Storage API
  • Identity and Access Management (IAM) API

啟用 API

REST

您可以從 Google Cloud 控制台啟用這些 API，也可以使用下列 gcloud CLI 指令：

gcloud services enable aiplatform.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com run.googleapis.com logging.googleapis.com discoveryengine.googleapis.com storage.googleapis.com iam.googleapis.com

授予權限

授予 Cloud Run Invoker (roles/run.invoker) 角色的權限。

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
   --role="roles/run.invoker"

更改下列內容：

  • PROJECT_ID：專案的 ID。
  • PROJECT_NUMBER：您的 Google Cloud 專案編號。

部署代理

deploy.sh 指令碼會自動執行部署程序。如要部署代理程式，請從專案目錄執行指令碼，並提供 Google Cloud ID 和新服務的名稱。您也可以選擇指定要使用的 Gemini 模型。

指令碼會執行下列動作：

  1. 從原始碼建構容器映像檔。
  2. 推送映像檔至 Artifact Registry。
  3. 將映像檔部署至 Cloud Run。
  4. 設定環境變數，包括 MODEL 和服務本身的公開 AGENT_URL。
chmod +x deploy.sh
./deploy.sh YOUR_PROJECT_ID contacts-agent MODEL_NAME

更改下列內容：

  • PROJECT_ID：專案 ID。
  • MODEL_NAME：選用。這是指令碼的第三個引數。支援的值為 gemini-2.5-pro 和 gemini-2.5-flash。 如未提供，指令碼預設會使用 gemini-2.5-flash。

指令碼執行完畢後，會顯示已部署代理程式的服務網址。您會在下一個步驟中用到這個服務網址。

向 Gemini Enterprise 註冊代理

代理程式部署完成後，您需要向 Gemini Enterprise 註冊，才能讓使用者找到該代理程式。

執行下列 curl 指令，並將預留位置替換為您自己的值：

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents -d '{
"name": "contacts-agent",
"displayName": "Contacts Agent",
"description": "This is a test agent which lists the contacts.",
"a2aAgentDefinition": {
  "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"contacts-agent\", \"description\": \"This is a test agent which lists the contacts.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.8\", \"description\": \"Ability to render A2UI\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://a2ui.org/specification/v0_8/standard_catalog_definition.json\"]}}]}, \"skills\": [], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
}
}'

更改下列內容：

  • PROJECT_NUMBER：您的 Google Cloud 專案編號。
  • LOCATION：資料儲存庫的多區域：global、us 或 eu
  • ENGINE_ID：要註冊代理程式的應用程式 ID。
  • AGENT_URL：已部署代理程式的服務網址。

在 Gemini Enterprise 網頁應用程式中使用 Agent

建立並註冊代理程式後，即可在 Gemini Enterprise 網頁應用程式中使用代理程式並與之互動。

取得網頁應用程式網址

如要使用服務專員，請先取得網頁應用程式網址。Gemini Enterprise 管理員可以按照下列步驟取得並分享網頁應用程式網址：

  1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

    Gemini Enterprise

  2. 按一下您向代理程式註冊的應用程式名稱。

  3. 按一下「Integrations」。

  4. 複製「您的網頁應用程式連結：」，並分享給機構中的使用者。

使用代理程式

如要使用及與代理互動，請按照下列步驟操作：

  1. 在新瀏覽器分頁中開啟網頁應用程式網址。
  2. 在網頁應用程式導覽選單中，按一下「代理程式」。
  3. 前往「來自貴機構」部分，然後點選您建立的代理程式。
  4. 系統會開啟代理的對話介面。開始提問並與服務專員互動。

舉例來說，你可以要求列出所有聯絡人。代理程式會使用 list_contacts 工具從 contact_data.json 擷取聯絡人，並使用自訂 UI 元素在對話中顯示清單，如下列範例所示：

Contacts Agent 範例