注意：這份文件適用於 Gemini Enterprise 的 Standard、Plus 和 Frontline 版本。如要瞭解 Business 版，請參閱 Gemini Enterprise - Business 版說明中心。

註冊及管理託管於 Vertex AI Agent Engine 的 ADK 代理

本頁說明 Gemini Enterprise 管理員如何註冊託管於 Vertex AI Agent Engine 的 Agent Development Kit (ADK) 代理，讓使用者在 Gemini Enterprise 網頁應用程式中使用這些代理。

事前準備

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

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

前往 Discovery Engine API
現有的 Gemini Enterprise 應用程式。如要建立應用程式，請參閱「建立應用程式」。
託管於 Vertex AI Agent Engine 的 ADK 代理。詳情請參閱「Agent 開發套件總覽」。

提示： 您必須在 Vertex AI Agent Engine 上代管及維護 ADK 代理，才能在 Gemini Enterprise 中使用這些代理。

設定授權詳細資料

Google Cloud

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

取得授權詳細資料

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

在 Google Cloud 控制台中，前往「APIs & Services」(API 與服務) 頁面，然後前往「Credentials」(憑證) 頁面。

前往「憑證」
選取 Google Cloud 專案，該專案包含您要代理程式存取的資料來源。舉例來說，選取包含您要代理程式查詢的 BigQuery 資料集的專案。
按一下「建立憑證」，然後選取「OAuth 用戶端 ID」。
在「應用程式類型」中，選取「網頁應用程式」。
在「已授權的重新導向 URI」部分，新增下列 URI：
- https://vertexaisearch.cloud.google.com/oauth-redirect
- https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
點選「建立」。
在「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：授權 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

參數細目

為確保 URI 正常運作，請檢查下列欄位：

參數	值或動作
`client_id`	將 `client_id` 替換為您下載的 JSON 檔案中找到的內容。
`redirect_uri`	請勿變更。必須為 `https://vertexaisearch.cloud.google.com/static/oauth/oauth.html`。
`scope`	請採取行動：列出應用程式需要的 Google API 範圍 (例如 `https://www.googleapis.com/auth/bigquery`)。如果使用多個範圍，請以空格分隔，網址中會顯示為 `%20`。
`include_granted_scopes`	必須為 `true`。
`response_type`	必須年滿 `code` 才能取得授權碼。
`access_type`	設為 `offline`，確保您收到更新權杖。
`prompt`	設為 `consent`，確保系統一律會向使用者顯示同意畫面。

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

向 Gemini Enterprise 註冊 ADK 代理

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

控制台

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

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

Gemini Enterprise
按一下要向代理程式註冊的應用程式名稱。
按一下「代理人」。系統隨即會顯示「代理程式」頁面。
按一下「新增代理」。系統會顯示「新增代理程式」面板。
按一下「透過 Agent Engine 建立的自訂代理」的「新增」。系統隨即會顯示「授權」頁面。
如要讓服務專員代表您存取 Google Cloud 資源，請為每項資源授權。如要為單一資源設定授權，請按照下列步驟操作：
1. 點選「新增授權」。
2. 輸入「授權名稱」的專屬值。系統會根據名稱產生 ID，且 ID 設定後即無法變更。
3. 在下列欄位中輸入「取得授權詳細資料」一節中產生的值：
  1. 在「Client ID」(用戶端 ID) 欄位中輸入值。
  2. 在「Client secret」(用戶端密鑰) 欄位中輸入值。
  3. 在「權杖 URI」欄位中輸入值。
  4. 按一下 [完成]。
點選「下一步」。
如要設定代理程式，請按照下列步驟操作：
1. 在「服務專員名稱」欄位中輸入名稱。這個值會顯示於 Gemini Enterprise 網頁應用程式，做為代理程式的顯示名稱。
2. 在「Describe your agent」(說明你的代理程式) 欄位中輸入說明。LLM 會依據這個值，判斷是否叫用代理來回覆使用者查詢。
3. 輸入 Agent Engine 推論引擎資源路徑。資源路徑的格式如下：
```
    https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID
 
```
  如要進一步瞭解如何列出 Vertex AI Agent Engine 託管的代理程式並取得資源路徑，請參閱「列出已部署的代理程式」。
4. 點選「建立」。

REST

這個程式碼範例示範如何註冊 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"
      },
      "adk_agent_definition": {
         "provisioned_reasoning_engine": {
            "reasoning_engine":
            "projects/PROJECT_ID/locations/REASONING_ENGINE_LOCATION/reasoningEngines/ADK_RESOURCE_ID"
         }
      },
   "authorization_config": {


   "tool_authorizations": [
   "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。
：代理程式的說明，會顯示在 Gemini Enterprise 中。DESCRIPTION
ICON_URI：要顯示在代理程式名稱附近的圖示公開 URI。或者，您也可以傳送 Base64 編碼的圖片檔案內容，在這種情況下，請使用 icon.content。
ADK_RESOURCE_ID：ADK 代理部署所在的推理引擎端點 ID。如要進一步瞭解如何列出 Vertex AI Agent Engine 託管的代理程式並取得資源 ID，請參閱「列出已部署的代理程式」。
REASONING_ENGINE_LOCATION：推理引擎的雲端位置。詳情請參閱「推理引擎位置」。
authorizationConfig：如果您已取得授權詳細資料，並希望代理程式代表使用者存取 Google Cloud 資源，請將 authorization_config 欄位新增至 JSON 資源。
```
 * <code><var>AUTH_ID</var></code>: the value that you used for
    <var>AUTH_ID</var> in the [Configure authorization details](#authorize-your-adk-agent)
    section.
```

新增具備權限的使用者

如要使用 Google Cloud 控制台將具備權限的使用者新增至 ADK 代理程式，請參閱新增或修改使用者及其權限。

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

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

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",
...
}

查看 ADK 代理的詳細資料

下列程式碼範例說明如何擷取向 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，請列出連結至應用程式的代理程式。

更新 ADK 代理程式

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

控制台

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

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

Gemini Enterprise
找出要更新代理程式的應用程式，然後按一下其名稱。
按一下「代理」。
按一下要更新的 Agent engine 代理程式名稱，然後按一下「編輯」。
更新「顯示名稱」、「說明」或「Agent Engine 推理引擎」。

資源路徑的格式如下：
```
  https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID
```
如要進一步瞭解如何列出 Vertex AI Agent Engine 託管的代理程式並取得資源路徑，請參閱「列出已部署的代理程式」。
按一下 [儲存]。

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/REASONING_ENGINE_LOCATION/reasoningEngine
            s/ADK_RESOURCE_ID"
         },
      }
}'

將變數替換為值：

ENDPOINT_LOCATION：API 要求的適用多區域。指定下列其中一個值：
- 美國多區域的 us
- eu 適用於歐盟多區域
- global 全球位置
詳情請參閱「為資料儲存庫指定多區域」。
PROJECT_ID： Google Cloud 專案的 ID。
AGENT_RESOURCE_NAME：要更新的代理程式註冊資源名稱。
DISPLAY_NAME：必要。代理的易記名稱，會顯示在 Gemini Enterprise 中。
DESCRIPTION：必填。簡要說明代理程式的功能，這項資訊會向 Gemini Enterprise 使用者顯示。
REASONING_ENGINE_LOCATION：必填。您要建立代理程式的推理引擎雲端位置。詳情請參閱「推理引擎位置」。
ADK_RESOURCE_ID：ADK 代理部署所在的推理引擎端點 ID。如要進一步瞭解如何列出 Vertex AI Agent Engine 託管的代理程式並取得資源 ID，請參閱「列出已部署的代理程式」。

刪除 ADK 代理程式

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

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，請列出連結至應用程式的代理程式。

指令與結果範例

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890/operations/delete-agent-12345678901234567890",
  "done": true
}

推論引擎位置

註冊或更新 ADK 代理時，基礎推理引擎資源的位置必須與代理的位置相容。推理引擎的位置取決於代理程式的位置，如下所示：

全球代理程式：如果代理程式位於 global 位置，您可以使用部署在任何支援區域的推理引擎。
多地區代理商：
- 如果代理程式位於 us 多區域，推論引擎必須部署在美國境內區域，例如 us-central1、us-east1 或 us-west1。
- 如果代理程式位於eu多個區域，則推理引擎必須部署在歐洲區域，例如 europe-west1、europe-west2 或 europe-central2。摘要表格如下：

服務專員位置	允許的推理引擎位置
`global`	任何支援的 Google Cloud 區域
`us`	以 `us-` 開頭的任何區域，例如 `us-central1` 或 `us-east4`
`eu`	以 `europe-` 開頭的任何區域，例如 `europe-west1` 或 `europe-west3`

如果位置不符，在註冊或更新代理程式時會發生錯誤。

註冊及管理託管於 Vertex AI Agent Engine 的 ADK 代理 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

設定授權詳細資料

取得授權詳細資料

將授權資源新增至 Gemini Enterprise

REST

向 Gemini Enterprise 註冊 ADK 代理

控制台

REST

新增具備權限的使用者

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

REST

查看 ADK 代理的詳細資料

REST

更新 ADK 代理程式

控制台

REST

刪除 ADK 代理程式

REST

指令與結果範例

推論引擎位置

註冊及管理託管於 Vertex AI Agent Engine 的 ADK 代理