註冊及管理 A2A 代理

Agent2Agent (A2A) 通訊協定是開放式通訊協定，也是代理的通用語言。這項通訊協定可讓不同建構工具和平台中的代理互相探索、協作，並安全地委派工作。本文說明 Gemini Enterprise 管理員如何將使用 A2A 建構並託管在任何平台上的代理，連結至 Gemini Enterprise，讓使用者在 Gemini Enterprise 網頁應用程式中使用這些代理。

事前準備

請確認你已具備以下條件：

  • Gemini Enterprise 管理員角色。

  • 啟用 Discovery Engine API。 如要為專案啟用 Discovery Engine API，請前往 Google CloudGoogle Cloud 控制台的「Discovery Engine API」頁面。

    前往 Discovery Engine API

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

  • 使用 A2A 通訊協定的代理。

    Gemini Enterprise 支援 A2A v0.3 串流機制。

    如果您使用 A2A 1.0.0 以上版本，請使用 SDK 提供的相容性套件，確保代理程式能與舊版機制搭配運作 (例如 Go 的 a2acompat/a2av0 套件或 Python 的 a2a.compat.v0_3 套件)。

設定授權詳細資料 (選用)

如果是 A2A 代理，您可以使用 OAuth 2.0 憑證控管使用者對 A2A 代理的存取權。不過，如果代理程式在 Cloud Run 上執行，並使用 Identity and Access Management 控管存取權，則不需要 OAuth 2.0 憑證。

  1. 在 Google Cloud 控制台的「API 與服務」頁面中，前往「憑證」頁面。

    前往「憑證」

  2. 選取 Google Cloud 專案，其中包含您要讓代理程式存取的資料來源。舉例來說，選取要讓代理程式查詢的 BigQuery 資料集所屬專案。

  3. 按一下「建立憑證」，然後選取「OAuth 用戶端 ID」。

  4. 在「應用程式類型」部分，選取「網頁應用程式」。

  5. 在「已授權的重新導向 URI」部分，新增下列 URI：

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

  6. 點選「建立」。

  7. 在「OAuth client created」(已建立 OAuth 用戶端) 面板中，按一下「Download JSON」(下載 JSON)。 下載的 JSON 檔案包含所選Google Cloud 專案的 Client ID、Authorization URI、Token URI 和 Client secret。您需要這些詳細資料才能建立授權資源。

向 Gemini Enterprise 註冊 A2A 代理

您可以透過Google Cloud 控制台或 REST API，將 A2A 代理註冊至 Gemini Enterprise。這樣一來，Gemini Enterprise 應用程式的使用者就能使用該代理。

控制台

如要使用 Google Cloud 控制台註冊 A2A 代理程式，請按照下列步驟操作：

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

    Gemini Enterprise

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

  3. 依序點選「代理程式」>「 新增代理程式」。

  4. 在「選擇代理類型」部分，按一下「透過 A2A 新增自訂代理」的「新增」。

  5. 在「代理程式資訊卡 JSON」欄位中，以 JSON 格式輸入代理程式資訊卡詳細資料。 如需可用欄位的完整清單，請參閱Agent2Agent (A2A) 通訊協定官方規格。 以下範例僅使用必填欄位。

    例如：

    {
  "protocolVersion": "0.3",
  "name": "Hello World Agent",
  "description": "Just a hello world agent",
  "url": "https://example.com/myagent",
  "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
  "version": "1.0.0",
  "capabilities": {
  },
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Data analysis",
      "tags": []
    }
  ],
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

  6. 按一下「預覽代理程式詳細資料」>「下一步」。

  7. 使用下列任一方法完成設定：

    • 如要讓代理程式代表您存取 Google Cloud 資源，請按照下列步驟操作：

      1. 輸入您在「取得授權詳細資料」部分產生的「Client ID」(用戶端 ID)、「Client secret」(用戶端密鑰)、「Authorization URI」(授權 URI) 和「Token URI」(權杖 URI)。

      2. 輸入範圍。

      3. 按一下「完成」。

    • 如果不想讓代理程式代表您存取 Google Cloud 資源，請按一下「略過並完成」。

REST

如要使用 REST API 註冊 A2A 代理程式，請按照下列步驟操作：

將授權資源新增至 Gemini Enterprise (選用)

如果代理程式必須代表使用者存取 Google Cloud 資源，請執行下列指令，向 Gemini Enterprise 註冊您在「設定授權詳細資料 (選用)」一節中建立的授權資源：

curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTH_ID",
      "serverSideOauth2": {
         "clientId": "OAUTH_CLIENT_ID",
         "clientSecret": "OAUTH_CLIENT_SECRET",
         "authorizationUri": "OAUTH_AUTH_URI",
         "tokenUri": "OAUTH_TOKEN_URI"
      }
   }'

更改下列內容：

  • PROJECT_ID：專案的 ID。
  • PROJECT_NUMBER： Google Cloud 專案的編號。
  • ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：
    • us 適用於美國多區域
    • eu 代表歐盟多區域
    • global 適用於全域位置
    詳情請參閱「為資料儲存庫指定多區域」。
  • LOCATION：資料儲存庫的多區域：global、us 或 eu
  • AUTH_ID：授權資源的 ID。這是您定義的任意英數字元 ID。註冊需要 OAuth 支援的代理時，您需要參考這個 ID。
  • OAUTH_CLIENT_ID：您在建立 OAuth 憑證時取得的 OAuth 2.0 用戶端 ID。
  • OAUTH_CLIENT_SECRET：建立 OAuth 憑證時取得的 OAuth 2.0 用戶端密鑰。

  • OAUTH_AUTH_URI：授權 URI。如要授權應用程式，請使用 OAuth 憑證 JSON 檔案中的詳細資料，建構特定的授權 URI。複製下列範本，並將預留位置替換為特定值。

    https://accounts.google.com/o/oauth2/v2/auth?client_id=OAUTH_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

    • YOUR_CUSTOM_SCOPES：您可以新增所需的範圍。舉例來說，下列 OAuth 範圍字串要求取得 Google 雲端硬碟和 Google 文件的唯讀存取權。

      scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly

  • OAUTH_TOKEN_URI：建立 OAuth 憑證時取得的權杖 URI。

進一步瞭解授權 URI 參數。

為確保 URI 正常運作，請驗證下列欄位：

參數 值或動作
client_id 將 client_id 替換為您下載的 JSON 檔案中找到的內容。
redirect_uri 請勿變更。必須為 https://vertexaisearch.cloud.google.com/static/oauth/oauth.html。
scope

列出應用程式需要代表使用者存取的 Google API 範圍。舉例來說，如要授予 BigQuery 存取權，請使用 https://www.googleapis.com/auth/bigquery 範圍；如要授予 Google 文件唯讀存取權，請使用 https://www.googleapis.com/auth/documents.readonly。

如果您使用多個範圍，請以空格分隔，網址中會顯示為 %20。
include_granted_scopes 必須為 true。
response_type 必須年滿 code 歲才能取得授權碼。
access_type 請設為 offline，確保您收到更新權杖。
prompt 設為 consent，確保系統一律會向使用者顯示同意畫面。

註冊 A2A 代理

如要使用 Gemini Enterprise 建立及註冊代理，請使用 agents.create 方法。下列指令只使用必填欄位。如需可用欄位的完整清單，請參閱 Agent2Agent (A2A) 通訊協定官方規格。

執行下列指令，將 A2A 代理註冊至 Gemini Enterprise：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

更改下列內容：

  • ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：
    • us 適用於美國多區域
    • eu 代表歐盟多區域
    • global 適用於全域位置
    詳情請參閱「為資料儲存庫指定多區域」。
  • LOCATION：資料儲存庫的多區域：global、us 或 eu
  • PROJECT_ID：專案的 ID。
  • APP_ID：要註冊代理程式的應用程式 ID。
  • AGENT_NAME：代理程式的專屬 ID。
  • AGENT_DISPLAY_NAME：網頁應用程式上顯示的代理程式名稱。
  • AGENT_DESCRIPTION：代理程式可執行的動作說明。
  • PROTOCOLVERSION：代理支援的 A2A 通訊協定版本。如要進一步瞭解支援的版本，請參閱「A2A 版本資訊」。
  • AGENT_URL：代理程式的端點網址。
  • AGENT_VERSION：代理程式版本。
  • INPUT_MODE：預設輸入媒體類型。例如 application/json 或 text/plain。
  • OUTPUT_MODE：預設輸出媒體類型。例如 text/plain" 或 image/png。
  • CAPABILITIES：包含支援的 A2A 功能的 JSON 物件。例如：\"streaming\": true 或 \"pushNotifications\": false。
  • SKILLS：代理程式提供的AgentSkill 物件清單。
  • authorizationConfig：如果您已取得授權詳細資料，並希望代理程式代表使用者存取 Google Cloud 資源，請將 authorization_config 欄位新增至 JSON 資源。
    • ：您在「將授權資源新增至 Gemini Enterprise」一節中使用的值。AUTH_IDAUTH_ID

列出連結至應用程式的代理程式

下列程式碼範例說明如何取得連線至應用程式的所有代理程式詳細資料：

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

將變數替換為值：

  • ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：
    • us 適用於美國多區域
    • eu 代表歐盟多區域
    • global 適用於全域位置
    詳情請參閱「為資料儲存庫指定多區域」。
  • PROJECT_ID：專案的 ID。 Google Cloud
  • LOCATION：應用程式的多區域：global、us 或 eu。
  • APP_ID：Gemini Enterprise 應用程式的 ID。

如果代理程式不是 Google 預先建構的，回應的前幾行會包含 name 欄位。這個欄位的值包含路徑結尾的代理程式 ID。舉例來說，在下列回應中，服務專員 ID 為 12345678901234567890：

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

查看 A2A 代理的詳細資料

以下程式碼範例說明如何擷取已向 Gemini Enterprise 註冊的代理程式詳細資料：

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

將變數替換為值：

  • ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：
    • us 適用於美國多區域
    • eu 代表歐盟多區域
    • global 適用於全域位置
    詳情請參閱「為資料儲存庫指定多區域」。
  • PROJECT_ID：專案的 ID。 Google Cloud
  • LOCATION：應用程式的多區域：global、us 或 eu。
  • APP_ID：Gemini Enterprise 應用程式的 ID。
  • AGENT_ID：代理程式的 ID。如要找出代理程式 ID，請列出連結至應用程式的代理程式。

更新 A2A 代理

如要修改已向 Gemini Enterprise 註冊的現有 A2A 代理程式詳細資料，可以使用 Google Cloud 控制台或 REST API。

控制台

如要使用 Google Cloud 控制台更新 A2A 代理程式，請按照下列步驟操作：

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

    Gemini Enterprise

  2. 找出要更新代理程式的應用程式，然後按一下其名稱。

  3. 按一下「代理程式」。

  4. 按一下要更新的 A2A (自訂) 代理程式名稱，然後按一下「編輯」。

  5. 在「代理程式資訊卡 JSON」欄位中，以 JSON 格式更新代理程式資訊卡詳細資料。如需可用欄位的完整清單，請參閱Agent2Agent (A2A) 通訊協定官方規格。 以下範例僅使用必填欄位。

    例如：

    {
  "protocolVersion": "0.3",
  "name": "Hello World Agent",
  "description": "Just a hello world agent",
  "url": "https://example.com/myagent",
  "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
  "version": "1.1.0",
  "capabilities": {
  },
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Data analysis",
      "tags": []
    }
  ],
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

  6. 按一下 [儲存]。

REST

如要更新已向 Gemini Enterprise 註冊的 A2A 代理詳細資料，請使用 agents.patch 方法。下列指令只使用必填欄位。如需可用欄位的完整清單，請參閱 Agent2Agent (A2A) 通訊協定官方規格。

請執行以下指令，使用 Gemini Enterprise 更新 A2A 代理：

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

更改下列內容：

  • ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：
    • us 適用於美國多區域
    • eu 代表歐盟多區域
    • global 適用於全域位置
    詳情請參閱「為資料儲存庫指定多區域」。
  • LOCATION：資料儲存庫的多區域：global、us 或 eu。
  • PROJECT_ID：專案的 ID。
  • APP_ID：要註冊代理程式的應用程式 ID。
  • AGENT_ID：代理程式的 ID。如要找出代理程式 ID，請列出連結至應用程式的代理程式。
  • AGENT_NAME：代理程式的專屬 ID。
  • AGENT_DISPLAY_NAME：網頁應用程式上顯示的代理程式名稱。
  • AGENT_DESCRIPTION：代理程式可執行的動作說明。
  • PROTOCOLVERSION：代理程式支援的 A2A 通訊協定版本。如要進一步瞭解支援的版本，請參閱「A2A 版本資訊」。
  • AGENT_URL：代理程式的端點網址。
  • AGENT_VERSION：代理程式版本。
  • INPUT_MODE：預設輸入媒體類型。例如 application/json 或 text/plain。
  • OUTPUT_MODE：預設輸出媒體類型。例如 text/plain 或 image/png。
  • CAPABILITIES：包含支援的 A2A 功能的 JSON 物件。例如：\"streaming\": true 或 \"pushNotifications\": false。
  • SKILLS：代理程式提供的AgentSkill 物件清單。
  • authorizationConfig：如果您已取得授權詳細資料，並希望代理程式代表使用者存取 Google Cloud 資源，請將 authorization_config 欄位新增至 JSON 資源。

刪除 A2A 代理

下列程式碼範例示範如何刪除與應用程式連結的代理程式：

REST

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

將變數替換為值：

  • ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：
    • us 適用於美國多區域
    • eu 代表歐盟多區域
    • global 適用於全域位置
    詳情請參閱「為資料儲存庫指定多區域」。
  • PROJECT_ID：專案的 ID。 Google Cloud
  • LOCATION：應用程式的多區域：global、us 或 eu
  • APP_ID：Gemini Enterprise 應用程式的 ID。
  • AGENT_ID：代理程式的 ID。如要找出代理程式 ID，請列出連結至應用程式的代理程式。

後續步驟

  • 在網頁應用程式中使用註冊至 Gemini Enterprise 的代理。