此页面由 Cloud Translation API 翻译。

注册和管理在 Vertex AI Agent Engine 上托管的 ADK 代理

本页面介绍了 Gemini Enterprise 管理员如何注册在 Vertex AI Agent Engine 上托管的智能体开发套件 (ADK) 智能体，以便在 Gemini Enterprise Web 应用中向用户提供这些智能体。

准备工作

请确保您已备好：

Discovery Engine Admin 角色。
启用 Discovery Engine API。如需为 Google Cloud项目启用 Discovery Engine API，请在 Google Cloud 控制台中前往 Discovery Engine API 页面。

前往 Discovery Engine API
现有的 Gemini Enterprise 应用。如需创建应用，请参阅创建应用。
托管在 Vertex AI Agent Engine 上的 ADK 代理。如需了解详情，请参阅智能体开发套件概览。

配置授权详细信息

为代理创建 OAuth 2.0 凭证，以便代理能够代表用户访问 Google Cloud 资源（例如 BigQuery 表）。

获取授权详细信息

请按照以下步骤获取授权详细信息。

在 Google Cloud 控制台的 API 和服务页面上，前往凭证页面。

转到“凭据”页面
选择您希望代理能够访问的数据源所在的 Google Cloud 项目。例如，选择您希望代理能够查询的 BigQuery 数据集所在的项目。
点击创建凭据并选择 OAuth 客户端 ID。
在应用类型中，选择 Web 应用。
在已获授权的重定向 URI 部分中，添加以下 URI：
- https://vertexaisearch.cloud.google.com/oauth-redirect
- https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
点击创建。
在 OAuth 客户端已创建面板中，点击下载 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 客户端标识符。
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 控制台或 API 向 Gemini Enterprise 注册 ADK 代理。这样一来，用户就可以在 Gemini Enterprise 应用中使用该代理。

控制台

如需使用 Google Cloud 控制台注册 ADK 代理，请按以下步骤操作：

在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。

Gemini Enterprise
点击要向其注册代理的应用的名称。
依次点击代理 > 添加代理。
在选择代理类型部分，对于通过 Agent Engine 构建的自定义代理，点击添加。
如果您希望代理代表您访问 Google Cloud 资源，请按以下步骤操作：
1. 点击添加授权。
2. 为“授权名称”输入一个唯一值。系统会根据名称生成 ID，且该 ID 以后无法更改。
3. 输入您在获取授权详细信息部分生成的客户端 ID、客户端密钥、授权 URI 和令牌 URI。
4. 点击添加授权。
点击下一步。
如需配置代理，请按以下步骤操作：
1. 在代理名称字段中输入一个名称。此值将显示在 Gemini Enterprise Web 应用中，作为您的代理的显示名称。
2. 在描述您的代理字段中输入相关说明。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. 在输入参数说明字段中输入相关说明。此参数说明向 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 应用的唯一标识符。
DESCRIPTION：在 Gemini Enterprise 中显示的代理说明。
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.
```

列出已关联到应用的代理

以下代码示例演示了如何获取与您的应用关联的所有代理的详细信息：

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 代理

您可以使用 Google Cloud 控制台或 REST API 修改已向 Gemini Enterprise 注册的现有代理的详细信息。

控制台

如需使用 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
}

推理引擎位置

如需向正确的推理引擎位置发出 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 代理