註冊及管理託管於 Agent Runtime 的 ADK 代理

控制台

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

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

   Gemini Enterprise

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

3. 按一下「Agents」。系統隨即會顯示「Agents」(代理) 頁面。

4. 按一下「add 新增代理」。「Add an agent」(新增代理) 面板隨即顯示。

5. 在「透過 Agent Runtime 建立的自訂代理」部分，點選「新增」。系統隨即會顯示「Authorizations」(授權) 頁面。

6. 如要讓代理代表您存取 Google Cloud 資源，則每項資源都需要授權。如要為單一資源設定授權，請按照下列步驟操作：

   1. 按一下「新增授權」。

   2. 在「Authorization name」(授權名稱) 中輸入不重複的值。系統會根據名稱產生 ID，且日後無法變更。

   3. 在下列欄位中，輸入您在「設定授權詳細資料 (選用)」中產生的值：

      1. 在「Client ID」欄位中輸入值。

      2. 在「Client secret」(用戶端密鑰) 欄位中輸入值。

      3. 在「權杖 URI」欄位中輸入值。

      4. 在「Authorization URI」欄位中輸入值。使用 OAuth 憑證 JSON 檔案中的詳細資料，建構授權 URI。複製下列範本，並將預留位置替換為您的特定值。

         https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_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
         

      5. 按一下「完成」。

7. 點選「下一步」。

8. 如要設定代理，請按照下列步驟操作：

   1. 在「Agent name」(代理名稱) 欄位中輸入名稱。這個值會顯示在 Gemini Enterprise 網頁應用程式，做為代理的顯示名稱。

   2. 在「描述您的代理」欄位輸入說明。LLM 會依據這個值，判斷是否叫用代理來回覆使用者查詢。

   3. 輸入 Agent Runtime 資源路徑。資源路徑的格式如下：

       projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID
       

      如要進一步瞭解如何列出託管於 Agent Runtime 的代理，以及取得資源路徑，請參閱「列出已部署的代理」。

   4. 點選「建立」。

REST

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

• 在 Gemini Enterprise 新增授權資源 (選用)
• 註冊 ADK 代理

將授權資源新增至 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。

註冊 ADK 代理

以下程式碼範例說明如何註冊 ADK 代理。

   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/global/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
      -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "icon": {
            "uri": "ICON_URI"
         },
         "adkAgentDefinition": {
            "provisionedReasoningEngine": {
               "reasoningEngine": "projects/PROJECT_ID/locations/RESOURCE_LOCATION/reasoningEngines/RESOURCE_ID"
            }
         },
         "authorizationConfig": {
            "toolAuthorizations": [
               "projects/PROJECT_NUMBER/locations/global/authorizations/AUTH_ID"
            ]
         }
      }'

將變數替換為值：

• ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：

  • us 適用於美國多區域
  • eu 代表歐盟多區域
  • global 適用於全域位置
  詳情請參閱「為資料儲存庫指定多區域」。

• PROJECT_ID： Google Cloud 專案的 ID。

• PROJECT_NUMBER： Google Cloud 專案的編號。

• APP_ID：Gemini Enterprise 應用程式的專屬 ID。

• DESCRIPTION：Gemini Enterprise 中顯示的代理說明。

• ICON_URI：圖示的公開 URI，會顯示在服務專員名稱附近。或者，您也可以傳送以 Base64 編碼的圖片檔案內容，在這種情況下，請使用 icon.content。

  • RESOURCE_ID：部署 ADK 代理的 Agent Runtime 端點 ID。如要進一步瞭解如何列出託管於 Agent Runtime 的代理，以及取得資源 ID，請參閱「列出已部署的代理」。

  • RESOURCE_LOCATION：Agent Runtime 端點的雲端位置。詳情請參閱「Agent Runtime 位置」。

  • authorization_config：如果您已取得授權詳細資料，並希望代理能代表使用者存取 Google Cloud 資源，請在 JSON 資源中新增 authorization_config 欄位。

    • AUTH_ID：您在「設定授權詳細資料」一節中用於 AUTH_ID 的值。

控制台

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

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

   Gemini Enterprise

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

3. 按一下「代理」。

4. 按一下要更新的 Agent Runtime 代理名稱，然後點選「Edit」(編輯)。

5. 更新「Display name」(顯示名稱)、「Description」(說明) 或「Agent Runtime reasoning engine」(Agent Runtime 推論引擎)。

   資源路徑的格式如下：

   projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID
   

   如要進一步瞭解如何列出託管於 Agent Runtime 的代理，並取得資源路徑，請參閱「列出已部署的代理」。

6. 按一下 [儲存]。

REST

您可以在註冊代理時更新所有欄位。不過，您必須更新下列欄位：

• displayName
• description

• reasoningEngine

  以下程式碼範例示範如何更新現有 ADK 代理程式的註冊資訊：

  curl -X PATCH \
     -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/AGENT_RESOURCE_NAME" \
     -d '{
           "displayName": "DISPLAY_NAME",
           "description": "DESCRIPTION",
           "adkAgentDefinition": {
           "provisionedReasoningEngine": {
              "reasoningEngine":
              "projects/PROJECT_ID/locations/RESOURCE_LOCATION/reasoningEngine
              s/RESOURCE_ID"
           },
        }
     }'
  

  將變數替換為值：

• ENDPOINT_LOCATION：API 要求適用的多區域。請指定下列其中一個值：

  • us 適用於美國多區域
  • eu 代表歐盟多區域
  • global 適用於全域位置
  詳情請參閱「為資料儲存庫指定多區域」。

• PROJECT_ID： Google Cloud 專案的 ID。

• AGENT_RESOURCE_NAME：要更新的代理程式註冊資源名稱。

• DISPLAY_NAME：必要。Gemini Enterprise 中顯示的代理易記名稱。

• DESCRIPTION：必填。簡短說明代理的功能，Gemini Enterprise 使用者會看到這項資訊。

• RESOURCE_LOCATION：Agent Runtime 端點的雲端位置。詳情請參閱「Agent Runtime 位置」。

• RESOURCE_ID：部署 ADK 代理的 Agent Runtime 端點 ID。如要進一步瞭解如何列出託管於 Agent Runtime 的代理，以及取得資源 ID，請參閱「列出已部署的代理」。