Esta página se ha traducido con Cloud Translation API.

Registrar y gestionar agentes del ADK alojados en Vertex AI Agent Engine

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

Antes de empezar

Asegúrate de que tienes lo siguiente:

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

Ir a la API Discovery Engine
Una aplicación de Gemini Enterprise. Para crear una aplicación, consulta Crear una aplicación.
Un agente del ADK alojado en Vertex AI Agent Engine. Para obtener más información, consulta la descripción general del kit de desarrollo de agentes.

Configurar los detalles de la autorización

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

Obtener detalles de la autorización

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

En la Google Cloud consola, en la página APIs & Services (APIs y servicios), ve a la página Credentials (Credenciales).

Ir a Credenciales
Selecciona el proyecto Google Cloud que contiene 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 quieres que consulte el agente.
Haz clic en Crear credenciales y selecciona ID de cliente de OAuth.
En Tipo de aplicación, selecciona Aplicación web.
En la sección URIs de redirección autorizados, añade 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 Cliente de OAuth creado, haz clic en Descargar JSON. El archivo JSON descargado incluye los campos Client ID, Authorization URI, Token URI y Client secret delGoogle Cloud proyecto seleccionado. Necesitarás estos datos para crear un recurso de autorización:

Añadir 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"
      }
   }'

Haz los cambios siguientes:

PROJECT_ID: el ID de tu proyecto.
ENDPOINT_LOCATION: la multirregión de 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 el artículo sobre cómo especificar una multirregión para tu almacén de datos.
LOCATION: la multirregión de tu almacén de datos: global, us o eu
AUTH_ID: ID del recurso de autorización. Se trata de un ID alfanumérico arbitrario que defines. Necesitarás hacer referencia a este ID más adelante cuando registres un agente que requiera compatibilidad con OAuth.
OAUTH_CLIENT_ID: el identificador de cliente de OAuth 2.0 que obtuviste al crear las credenciales de OAuth.
OAUTH_CLIENT_SECRET: el secreto de cliente de OAuth 2.0 que obtuviste al crear las credenciales de OAuth.
OAUTH_AUTH_URI: 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: el URI del token que has obtenido al crear las credenciales de OAuth.

Registrar un agente de ADK en Gemini Enterprise

Puedes registrar tu agente de ADK en Gemini Enterprise mediante laGoogle Cloud consola o la API REST. De este modo, el agente estará disponible para los usuarios de una aplicación de Gemini Enterprise.

Consola

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

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

Gemini Enterprise
Haz clic en el nombre de la aplicación en la que quieras registrar el agente.
Haz clic en Agentes > Añadir agentes.
En la sección Elige un tipo de agente, haz clic en Añadir para Agente personalizado mediante Agent Engine.
Si quieres que el agente acceda a los recursos en tu nombre, sigue estos pasos: Google Cloud
1. Haz clic en Añadir autorización.
2. Introduce un valor único en el campo Nombre de autorización. Se genera un ID a partir del nombre y no se puede cambiar más adelante.
3. Introduce el ID de cliente, el secreto de cliente, el URI de autorización y el URI de token que has generado en la sección Obtener detalles de autorización.
4. Haz clic en Añadir autorización.
Haz clic en Siguiente.
Para configurar tu agente, sigue estos pasos:
1. Introduce un nombre en el campo Nombre del agente. Este valor aparece en la aplicación web de Gemini Enterprise como el nombre visible de tu agente.
2. Escribe una descripción en el campo Describe tu agente. Un LLM usa este valor para determinar si debe invocar a tu agente en respuesta a una consulta de un usuario.
3. Introduce la ruta del recurso Agent Engine reasoning 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 del recurso, consulta List deployed agents (Enumerar agentes implementados).
4. Configura los ajustes de la herramienta:
  1. Introduce una descripción en el campo Descripción de la herramienta. La LLM usa esta descripción para entender la finalidad de la herramienta y decidir cuándo usarla.
  2. Escribe el nombre en el campo Nombre del parámetro de entrada. Es el nombre del parámetro de la llamada a la función. El nombre de este parámetro indica al LLM el tipo de entrada esperado, como question, command o search_query.
  3. Introduce la descripción en el campo Descripción del parámetro de entrada. Esta descripción del parámetro 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 este ejemplo de código se muestra cómo 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"
   ]
   }
   }'

Sustituye las variables por los valores correspondientes:

ENDPOINT_LOCATION-: la multirregión de 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 el artículo sobre cómo especificar una multirregión para tu almacén de datos.
PROJECT_ID: el ID de tu proyecto de Google Cloud .
APP_ID: identificador único de la aplicación Gemini Enterprise.
DESCRIPTION : la descripción del agente que se muestra en Gemini Enterprise.
ICON_URI: URI público del icono que se mostrará junto al nombre del agente. También puede transferir el contenido del archivo de imagen codificado en Base64. En ese caso, utilice icon.content.
ADK_RESOURCE_ID: el ID del endpoint del motor de razonamiento donde se ha implementado 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 Listar agentes desplegados.
REASONING_ENGINE_LOCATION: la ubicación en la nube del motor de razonamiento. Para obtener más información, consulta la ubicación del motor de razonamiento.
authorizationConfig: Si has obtenido los detalles de autorización y quieres que el agente acceda a los recursos en nombre del usuario, añade el campo authorization_config a tu recurso JSON. Google Cloud
```
 * <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.
```

Mostrar los agentes conectados a una aplicación

En el siguiente ejemplo de código se muestra cómo obtener los detalles de todos los agentes conectados a tu aplicación:

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"

Sustituye las variables por los valores correspondientes:

ENDPOINT_LOCATION-: la multirregión de 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 el artículo sobre cómo especificar una multirregión para tu almacén de datos.
PROJECT_ID: el ID de tu proyecto de Google Cloud .
LOCATION: la multirregión de tu aplicación: global, us o eu.
APP_ID: el ID de tu aplicación de Gemini Enterprise.

Si Google no ha precompilado tu agente, la respuesta incluye 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 de agente es 12345678901234567890:

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

Ver los detalles de un agente de ADK

En el siguiente código de ejemplo se muestra cómo puedes obtener los detalles de un agente que se ha registrado en 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"

Sustituye las variables por los valores correspondientes:

ENDPOINT_LOCATION-: la multirregión de 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 el artículo sobre cómo especificar una multirregión para tu almacén de datos.
PROJECT_ID: el ID de tu proyecto de Google Cloud .
LOCATION: la multirregión de tu aplicación: global, us o eu.
APP_ID: el ID de tu aplicación de Gemini Enterprise.
AGENT_ID: el ID del agente. Puedes encontrar el ID del agente consultando la lista de agentes conectados a tu aplicación.

Actualizar un agente de ADK

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

Consola

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

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

Gemini Enterprise
Haz clic en el nombre de la aplicación que incluye el agente que quieres actualizar.
Haz clic en Agentes.
Haga clic en el nombre del agente de Agent Engine que quiera actualizar y, a continuación, haga clic en Editar.
Actualiza el Nombre visible, la Descripción o el motor de razonamiento del motor de agente.

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 del recurso, consulta List deployed agents (Enumerar agentes implementados).
Haz clic en Guardar.

REST

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

displayName
description

reasoningEngine

En este fragmento de código se muestra cómo puedes actualizar el registro de un agente de 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"
         },
      }
}'

Sustituye las variables por los valores correspondientes:

ENDPOINT_LOCATION-: la multirregión de 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 el artículo sobre cómo especificar una multirregión para tu almacén de datos.
PROJECT_ID: el ID de tu proyecto de Google Cloud .
AGENT_RESOURCE_NAME: nombre del recurso de la inscripción del agente que se va a actualizar.
DISPLAY_NAME: obligatorio. Nombre descriptivo del agente que se muestra en Gemini Enterprise.
DESCRIPTION: obligatorio. Una breve explicación de lo que hace tu agente que pueden ver los usuarios de Gemini Enterprise.
REASONING_ENGINE_LOCATION: obligatorio. Ubicación en la nube del motor de razonamiento en el que vas a crear un agente. Para obtener más información, consulta Ubicación del motor de razonamiento.
ADK_RESOURCE_ID: el ID del endpoint del motor de razonamiento donde se ha implementado 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 Listar agentes desplegados.

Eliminar un agente de ADK

En el siguiente ejemplo de código se muestra cómo puedes eliminar un agente que esté conectado a tu aplicación:

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"

Sustituye las variables por los valores correspondientes:

ENDPOINT_LOCATION-: la multirregión de 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 el artículo sobre cómo especificar una multirregión para tu almacén de datos.
PROJECT_ID: el ID de tu proyecto de Google Cloud .
LOCATION: la multirregión de tu aplicación: global, us o eu
APP_ID: el ID de tu aplicación de Gemini Enterprise.
AGENT_ID: el ID del agente. Puedes encontrar el ID del agente consultando la lista de agentes conectados a tu aplicación.

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 hacer una llamada a la API a la ubicación correcta del motor de razonamiento, usa el siguiente gráfico:

Ubicación en la nube desde la que llamas	Ubicación del motor de razonamiento
`us`	`us-central1`
`eu`	`europe-west1`
Otros (incluidos `global`)	`us-central1`

Registrar y gestionar agentes del ADK alojados en Vertex AI Agent Engine Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Antes de empezar

Configurar los detalles de la autorización

Obtener detalles de la autorización

Añadir un recurso de autorización a Gemini Enterprise

REST

Registrar un agente de ADK en Gemini Enterprise

Consola

REST

Mostrar los agentes conectados a una aplicación

REST

Ver los detalles de un agente de ADK

REST

Actualizar un agente de ADK

Consola

REST

Eliminar un agente de ADK

REST

Ejemplo de comando y resultado

Ubicación del motor de razonamiento

Registrar y gestionar agentes del ADK alojados en Vertex AI Agent Engine