本頁面由 Cloud Translation API 翻譯而成。

註冊及管理託管於 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 開發套件總覽」。

設定授權詳細資料

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：您在建立 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 註冊 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，且設定完成後即無法變更。
3. 輸入在「取得授權詳細資料」部分產生的「Client ID」(用戶端 ID)、「Client secret」(用戶端密鑰)、「Authorization URI」(授權 URI) 和「Token URI」(權杖 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. 設定工具設定：
  1. 在「工具說明」欄位中輸入說明。LLM 會依據這段說明瞭解工具的用途，並判斷使用時機。
  2. 在「輸入參數名稱」欄位中輸入名稱。這是函式呼叫的參數名稱。這個參數名稱會提示 LLM 預期的輸入類型，例如 question、command 或 search_query。
  3. 在「Input parameter description」(輸入參數說明) 欄位中輸入說明。這項參數說明可讓 LLM 進一步瞭解參數，例如預期內容和要執行的動作。
5. 點選「建立」。

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_ID/locations/global/authorizations/AUTH_ID"
   ]
   }
   }'

將變數替換為值：

ENDPOINT_LOCATION-：API 要求的適用多區域。指派下列其中一個值：
- 美國多區域：us-
- eu- 適用於歐盟多區域
- global- 全球位置
詳情請參閱「為資料儲存庫指定多區域」。
PROJECT_ID： Google Cloud 專案的 ID。
APP_ID：Gemini Enterprise 應用程式的專屬 ID。
：代理程式的說明，會顯示在 Gemini Enterprise 中。DESCRIPTION
ICON_URI：要顯示在代理程式名稱附近的圖示公開 URI。或者，您也可以傳送 Base64 編碼的圖片檔案內容，在這種情況下，請使用 icon.content。
ADK_RESOURCE_ID：ADK 代理程式部署所在的 Reasoning Engine 端點 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.
```

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

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

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 代理程式部署所在的 Reasoning Engine 端點 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
}

推論引擎位置

如要向正確的推理引擎位置發出 API 呼叫，請使用下表：

您要撥打電話的雲端位置	推理引擎位置
`us`	`us-central1`
`eu`	`europe-west1`
其他 (包括 `global`)	`us-central1`

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

事前準備

設定授權詳細資料

取得授權詳細資料

將授權資源新增至 Gemini Enterprise

REST

向 Gemini Enterprise 註冊 ADK 代理

控制台

REST

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

REST

查看 ADK 代理的詳細資料

REST

更新 ADK 代理程式

控制台

REST

刪除 ADK 代理程式

REST

指令與結果範例

推論引擎位置

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