注册和管理托管在 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. 在客户端 ID 字段中输入相应值。

      2. 在客户端密钥字段中输入相应值。

      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 Web 应用中，作为您的代理的显示名称。

   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 客户端标识符。
• 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 应用的唯一标识符。

• 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 资源，请将 authorization_config 字段添加到您的 JSON 资源中。

    • 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：您的 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，请参阅列出已部署的智能体。