註冊及管理 A2A 代理程式

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

事前準備

請確認您已備妥以下項目：

  • Discovery Engine 管理員角色。

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

    前往 Discovery Engine API

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

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

設定授權詳細資料

Google Cloud

為代理程式建立 OAuth 2.0 憑證，代表使用者存取 Google Cloud 資源，例如 BigQuery 資料表。

取得授權詳細資料

請按照下列步驟取得授權詳細資料。

  1. 在 Google Cloud 控制台的「APIs & Services」(API 和服務) 頁面中，前往「Credentials」(憑證) 頁面。

    前往「憑證」

  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

執行下列指令，向 Gemini Enterprise 註冊授權資源：

REST

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_ID/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_ID/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。
  • 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：您在建立 OAuth 憑證時取得的授權 URI。格式如下： https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
  • OAUTH_TOKEN_URI：您在建立 OAuth 憑證時取得的權杖 URI。

向 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": "v1.0",
  "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

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

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

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 資源。

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

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

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： Google Cloud 專案的 ID。
  • 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： Google Cloud 專案的 ID。
  • 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": "v3.0",
  "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： Google Cloud 專案的 ID。
  • LOCATION：應用程式的多區域： global、us 或 eu
  • APP_ID：Gemini Enterprise 應用程式的 ID。
  • AGENT_ID：代理程式的 ID。如要找出代理程式 ID，請列出連結至應用程式的代理程式。

後續步驟

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