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

控制台

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

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

   Gemini Enterprise

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

3. 按一下「代理人」。系統隨即會顯示「代理程式」頁面。

4. 按一下「新增代理」add。系統會顯示「新增代理程式」面板。

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

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

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

   2. 輸入「授權名稱」的專屬值。系統會根據名稱產生 ID，且 ID 設定後即無法變更。

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

      1. 在「Client ID」(用戶端 ID) 欄位中輸入值。

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

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

      4. 在「授權 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. 在「代理程式名稱」欄位中輸入名稱。這個值會顯示於 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：專案的 ID。 Google Cloud

• 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：如果您已取得授權詳細資料，並希望代理程式代表使用者存取資源，請將 authorization_config 欄位新增至 JSON 資源。 Google Cloud

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

控制台

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

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

   Gemini Enterprise

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

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

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

5. 更新「顯示名稱」、「說明」或「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：專案的 ID。 Google Cloud

• 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，請參閱「列出已部署的代理程式」。