Se usó la API de Cloud Translation para traducir esta página.

Registra y administra agentes del ADK alojados en Vertex AI Agent Engine

En esta página, se describe cómo los administradores de Gemini Enterprise pueden registrar agentes del Kit de desarrollo de agentes (ADK) alojados en Agent Engine de Vertex AI para que estén disponibles para los usuarios en la app web de Gemini Enterprise.

Antes de comenzar

Asegúrate de tener lo siguiente:

El rol de administrador de Discovery Engine
Habilita la API de Discovery Engine. Para habilitar la API de Discovery Engine para el proyecto Google Cloud, en la consola de Google Cloud, ve a la página de la API de Discovery Engine. Google Cloud

Ir a la API de Discovery Engine
Una app de Gemini Enterprise existente. Para crear una app, consulta Cómo crear una app.
Es un agente del ADK alojado en Vertex AI Agent Engine. Para obtener más información, consulta Descripción general del Agent Development Kit.

Configura los detalles de autorización

Crea credenciales de OAuth 2.0 para que el agente acceda a los recursos de Google Cloud , como las tablas de BigQuery, en nombre de un usuario.

Obtén detalles de la autorización

Sigue estos pasos para obtener los detalles de la autorización.

En la consola de Google Cloud , en la página APIs y servicios, ve a la página Credenciales.

Ir a Credenciales
Selecciona el proyecto Google Cloud que tiene la fuente de datos a la que quieres que acceda el agente. Por ejemplo, selecciona el proyecto que contiene el conjunto de datos de BigQuery que deseas que consulte el agente.
Haz clic en Crear credenciales y, luego, selecciona ID de cliente OAuth.
En Tipo de aplicación, selecciona Aplicación web.
En la sección URIs de redireccionamiento autorizados, agrega los siguientes URIs:
- https://vertexaisearch.cloud.google.com/oauth-redirect
- https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
Haz clic en Crear.
En el panel Se creó el cliente de OAuth, haz clic en Descargar JSON. El archivo JSON descargado incluye Client ID, Authorization URI, Token URI y Client secret para el proyectoGoogle Cloud seleccionado. Necesitas estos detalles para crear un recurso de autorización:

Agrega un recurso de autorización a Gemini Enterprise

Ejecuta el siguiente comando para registrar un recurso de autorización con 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"
      }
   }'

Reemplaza lo siguiente:

PROJECT_ID: el ID de tu proyecto.
ENDPOINT_LOCATION: Es la región múltiple para tu solicitud a la API. Asigna uno de los siguientes valores:
- us- para la multirregión de EE.UU.
- eu- para la multirregión de la UE
- global- para la ubicación global
Para obtener más información, consulta Cómo especificar una región múltiple para tu almacén de datos.
LOCATION: Es la multirregión de tu almacén de datos: global, us o eu.
AUTH_ID: Es el ID del recurso de autorización. Es un ID alfanumérico arbitrario que defines. Deberás hacer referencia a este ID más adelante cuando registres un agente que requiera compatibilidad con OAuth.
OAUTH_CLIENT_ID: Es el identificador de cliente de OAuth 2.0 que obtuviste cuando creaste las credenciales de OAuth.
OAUTH_CLIENT_SECRET: Es el secreto del cliente de OAuth 2.0 que obtuviste cuando creaste las credenciales de OAuth.
OAUTH_AUTH_URI: Es el URI de autorización que obtuviste cuando creaste las credenciales de OAuth. Tiene el siguiente formato: 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: Es el URI del token que obtuviste cuando creaste las credenciales de OAuth.

Registra un agente del ADK en Gemini Enterprise

Puedes registrar tu agente del ADK en Gemini Enterprise con la consola deGoogle Cloud o la API de REST. Esto hace que el agente esté disponible para los usuarios dentro de una app de Gemini Enterprise.

Console

Para registrar un agente de ADK con la consola de Google Cloud , sigue estos pasos:

En la consola de Google Cloud , ve a la página de Gemini Enterprise.

Gemini Enterprise
Haz clic en el nombre de la app en la que quieres registrar el agente.
Haz clic en Agentes > Agregar agentes.
En la sección Elige un tipo de agente, haz clic en Agregar para Agente personalizado a través de Agent Engine.
Si quieres que el agente acceda a Google Cloud recursos en tu nombre, sigue estos pasos:
1. Haz clic en Agregar autorización.
2. Ingresa un valor único para el Nombre de autorización. Se genera un ID basado en el nombre, y no se puede cambiar más adelante.
3. Ingresa el ID de cliente, el secreto de cliente, el URI de autorización y el URI de token que generaste en la sección Obtén detalles de autorización.
4. Haz clic en Agregar autorización.
Haz clic en Siguiente.
Para configurar tu agente, sigue estos pasos:
1. Ingresa un nombre en el campo Nombre del agente. Este valor aparece en la app web de Gemini Enterprise como el nombre visible de tu agente.
2. Ingresa una descripción en el campo Describe your agent. Un LLM usa este valor para determinar si debe invocar tu agente en respuesta a una consulta del usuario.
3. Ingresa la ruta del recurso del motor de razonamiento de Agent Engine. La ruta de acceso al recurso tiene el siguiente formato:
```
    https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID
 
```
  Para obtener más información sobre cómo enumerar los agentes alojados en Vertex AI Agent Engine y obtener la ruta de acceso al recurso, consulta Cómo enumerar los agentes implementados.
4. Configura los parámetros de configuración de la herramienta:
  1. Ingresa una descripción en el campo Tool description. El LLM usa esta descripción para comprender el propósito de la herramienta y decidir cuándo usarla.
  2. Ingresa el nombre en el campo Nombre del parámetro de entrada. Este es el nombre del parámetro para la llamada a función. El nombre de este parámetro le da una pista al LLM sobre el tipo de entrada esperado, como question, command o search_query.
  3. Ingresa la descripción en el campo Input parameter description. Esta descripción del parámetro le proporciona al LLM más información sobre el parámetro, como el contenido esperado y las acciones que se deben realizar.
5. Haz clic en Crear.

REST

En esta muestra de código, se muestra cómo puedes registrar tus agentes del 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"
   ]
   }
   }'

Reemplaza las variables por valores:

ENDPOINT_LOCATION-: Es la región múltiple para tu solicitud a la API. Asigna uno de los siguientes valores:
- us- para la multirregión de EE.UU.
- eu- para la multirregión de la UE
- global- para la ubicación global
Para obtener más información, consulta Cómo especificar una región múltiple para tu almacén de datos.
PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
APP_ID: Es el identificador único de la app de Gemini Enterprise.
DESCRIPTION : Es la descripción del agente que se muestra en Gemini Enterprise.
ICON_URI: Es el URI público del ícono que se mostrará cerca del nombre del agente. De forma alternativa, puedes pasar el contenido del archivo de imagen codificado en Base64 y, en ese caso, usar icon.content.
ADK_RESOURCE_ID: Es el ID del extremo del motor de razonamiento en el que se implementa el agente del ADK. Para obtener más información sobre cómo enumerar los agentes alojados en Vertex AI Agent Engine y obtener el ID de recurso, consulta Cómo enumerar los agentes implementados.
REASONING_ENGINE_LOCATION: Es la ubicación en la nube del motor de razonamiento. Para obtener más información, consulta Ubicación del motor de inferencia.
authorizationConfig: Si obtuviste los detalles de autorización y quieres que el agente acceda a los recursos de Google Cloud en nombre del usuario, agrega el campo authorization_config a tu recurso 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.
```

Enumera los agentes conectados a una app

En la siguiente muestra de código, se muestra cómo puedes obtener los detalles de todos los agentes conectados a tu app:

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"

Reemplaza las variables por valores:

ENDPOINT_LOCATION-: Es la región múltiple para tu solicitud a la API. Asigna uno de los siguientes valores:
- us- para la multirregión de EE.UU.
- eu- para la multirregión de la UE
- global- para la ubicación global
Para obtener más información, consulta Cómo especificar una región múltiple para tu almacén de datos.
PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
LOCATION: Es la multirregión de tu app: global, us o eu.
APP_ID: Es el ID de tu app de Gemini Enterprise.

Si Google no creó previamente tu agente, la respuesta incluirá un campo name en las primeras líneas. El valor de este campo contiene el ID del agente al final de la ruta. Por ejemplo, en la siguiente respuesta, el ID del agente es 12345678901234567890:

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

Consulta los detalles de un agente del ADK

En el siguiente muestra de código, se muestra cómo puedes recuperar los detalles de un agente que se registró con 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"

Reemplaza las variables por valores:

ENDPOINT_LOCATION-: Es la región múltiple para tu solicitud a la API. Asigna uno de los siguientes valores:
- us- para la multirregión de EE.UU.
- eu- para la multirregión de la UE
- global- para la ubicación global
Para obtener más información, consulta Cómo especificar una región múltiple para tu almacén de datos.
PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
LOCATION: Es la multirregión de tu app: global, us o eu.
APP_ID: Es el ID de tu app de Gemini Enterprise.
AGENT_ID: ID del agente. Puedes encontrar el ID del agente enumerando los agentes conectados a tu app.

Actualiza un agente del ADK

Puedes modificar los detalles de un agente existente registrado en Gemini Enterprise con la consola de Google Cloud o la API de REST.

Console

Para actualizar el agente con la consola de Google Cloud , sigue estos pasos:

En la consola de Google Cloud , ve a la página de Gemini Enterprise.

Gemini Enterprise
Haz clic en el nombre de la app que incluye el agente que deseas actualizar.
Haz clic en Agentes.
Haz clic en el nombre del agente de Agent engine que deseas actualizar y, luego, en Editar.
Actualiza el Nombre visible, la Descripción o el motor de razonamiento de Agent Engine.

La ruta del recurso tiene el siguiente formato:
```
  https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/ADK_RESOURCE_ID
```
Para obtener más información sobre cómo enumerar los agentes alojados en Vertex AI Agent Engine y obtener la ruta de acceso al recurso, consulta Enumera los agentes implementados.
Haz clic en Guardar.

REST

Puedes actualizar todos los campos durante el registro del agente. Sin embargo, se deben actualizar los siguientes campos:

displayName
description

reasoningEngine

En este muestra de código, se muestra cómo puedes actualizar el registro de un agente del ADK existente:

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

Reemplaza las variables por valores:

ENDPOINT_LOCATION-: Es la región múltiple para tu solicitud a la API. Asigna uno de los siguientes valores:
- us- para la multirregión de EE.UU.
- eu- para la multirregión de la UE
- global- para la ubicación global
Para obtener más información, consulta Cómo especificar una región múltiple para tu almacén de datos.
PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
AGENT_RESOURCE_NAME: Es el nombre del recurso del registro del agente que se actualizará.
DISPLAY_NAME: Obligatorio. Es el nombre fácil de usar de tu agente que se muestra en Gemini Enterprise.
DESCRIPTION: Obligatorio. Una breve explicación de lo que hace tu agente, que es visible para los usuarios de Gemini Enterprise.
REASONING_ENGINE_LOCATION: Obligatorio. Ubicación en la nube del motor de inferencia en el que estás creando un agente. Para obtener más información, consulta Ubicación del motor de inferencia.
ADK_RESOURCE_ID: Es el ID del extremo del motor de razonamiento en el que se implementa el agente del ADK. Para obtener más información sobre cómo enumerar los agentes alojados en Vertex AI Agent Engine y obtener el ID de recurso, consulta Cómo enumerar los agentes implementados.

Borra un agente del ADK

En la siguiente muestra de código, se indica cómo borrar un agente conectado a tu app:

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"

Reemplaza las variables por valores:

ENDPOINT_LOCATION-: Es la región múltiple para tu solicitud a la API. Asigna uno de los siguientes valores:
- us- para la multirregión de EE.UU.
- eu- para la multirregión de la UE
- global- para la ubicación global
Para obtener más información, consulta Cómo especificar una región múltiple para tu almacén de datos.
PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
LOCATION: Es la multirregión de tu app: global, us o eu.
APP_ID: Es el ID de tu app de Gemini Enterprise.
AGENT_ID: ID del agente Puedes encontrar el ID del agente enumerando los agentes conectados a tu app.

Ejemplo de comando y resultado

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
}

Ubicación del motor de razonamiento

Para realizar la llamada a la API a la ubicación correcta del motor de inferencia, usa el siguiente gráfico:

Ubicación de Cloud a la que llamas	Ubicación del motor de razonamiento
`us`	`us-central1`
`eu`	`europe-west1`
Otros (incluido `global`)	`us-central1`

Registra y administra agentes del ADK alojados en Vertex AI Agent Engine Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Configura los detalles de autorización

Obtén detalles de la autorización

Agrega un recurso de autorización a Gemini Enterprise

REST

Registra un agente del ADK en Gemini Enterprise

Console

REST

Enumera los agentes conectados a una app

REST

Consulta los detalles de un agente del ADK

REST

Actualiza un agente del ADK

Console

REST

Borra un agente del ADK

REST

Ejemplo de comando y resultado

Ubicación del motor de razonamiento

Registra y administra agentes del ADK alojados en Vertex AI Agent Engine