Configurar el entorno

Antes de trabajar con Vertex AI Agent Engine, debes asegurarte de que tu entorno esté configurado. Debes tener un Google Cloud proyecto con la facturación habilitada, disponer de los permisos necesarios, configurar un segmento de Cloud Storage e instalar el SDK de Vertex AI para Python. Consulta los siguientes temas para asegurarte de que estás listo para empezar a trabajar con Vertex AI Agent Engine.

Para ver un ejemplo de referencia de Terraform que agilice la configuración y la implementación del entorno de Vertex AI Agent Engine, consulta el paquete de inicio de agente.

Configurar un Google Cloud proyecto

Cada proyecto se puede identificar de dos formas: mediante el número o el ID del proyecto. El PROJECT_NUMBER se crea automáticamente al crear el proyecto, mientras que el PROJECT_ID lo creas tú o la persona que lo haya creado. Para configurar un proyecto, sigue estos pasos:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Nota: Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si no tienes este permiso, pide a tu administrador que te conceda el rol Administrador de uso de servicios (roles/serviceusage.serviceUsageAdmin).

Obtener los roles necesarios

Para obtener los permisos que necesitas para usar Vertex AI Agent Engine, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

• Usuario de Vertex AI (roles/aiplatform.user)
• Administrador de almacenamiento (roles/storage.admin)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Configurar la identidad y los permisos del agente

Los agentes que despliegues en Vertex AI Agent Engine se ejecutan con cuentas de servicio como identidad.

Tienes dos opciones para la cuenta de servicio:

• Agente de servicio predeterminado: de forma predeterminada, los agentes usan el agente de servicio del motor de razonamiento de AI Platform. Esta cuenta de servicio gestionada por Google tiene el rol Agente de servicio de Vertex AI Reasoning Engine (roles/aiplatform.reasoningEngineServiceAgent), que incluye los permisos predeterminados necesarios para los agentes implementados.
• Cuenta de servicio personalizada: puedes especificar tu propia cuenta de servicio para que la usen los agentes. De esta forma, tendrás un control más detallado sobre los permisos concedidos a los agentes.

Usar el agente de servicio predeterminado

El agente de servicio de AI Platform Reasoning Engine se usa de forma predeterminada. Puedes consultar la lista completa de permisos predeterminados en la documentación de gestión de identidades y accesos.

Si tu agente requiere permisos que no están incluidos en el conjunto predeterminado, puedes asignarle roles adicionales:

1. Ve a la página Gestión de identidades y accesos y marca la casilla "Incluir concesiones de roles proporcionadas por Google".

   Ir a IAM

2. Busca la entidad de seguridad que coincida con [e-mail].

3. Añade los roles necesarios a la cuenta principal haciendo clic en el botón de edición y, a continuación, en el botón de guardar.

Generar manualmente el agente de servicio predeterminado

Aunque el agente de servicio de Reasoning Engine se aprovisiona automáticamente durante la implementación de Vertex AI Agent Engine, puede haber casos en los que necesites generarlo manualmente de antemano. Esto es especialmente importante cuando necesitas asignar roles específicos al agente de servicio para asegurarte de que el proceso de implementación tenga los permisos necesarios y evitar posibles fallos.

Para generar manualmente un agente de servicio de Reasoning Engine, sigue estos pasos:

1. Genera el agente de servicio de Reasoning Engine con la CLI de Google Cloud.

   gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT-ID-OR-PROJECT-NUMBER

   Nota: La respuesta al comando de Google Cloud CLI puede mostrar solo el agente de servicio de Vertex AI. Sin embargo, también se crea el agente de servicio de Reasoning Engine.

2. Ve a la página Gestión de identidades y accesos y haz clic en Conceder acceso.

   Ir a IAM

3. En la sección Add principals (Añadir principales), en el campo New principals (Nuevos principales), introduce [e-mail].

4. En la sección Asignar roles, busca y selecciona los roles que necesites.

5. Haz clic en el botón Save (Guardar).

Usar una cuenta de servicio personalizada

Para usar tu propia cuenta de servicio, debes concederle los permisos necesarios para ejecutar el agente. Es probable que tu cuenta de servicio personalizada necesite el rol Usuario de Vertex AI (roles/aiplatform.user).

1. Si no tienes una cuenta de servicio, crea una. Consulta Crear cuentas de servicio.

2. Asigna a la cuenta de servicio el rol Usuario de Vertex AI (roles/aiplatform.user).

3. Asigna a la cuenta de servicio cualquier otro rol que requiera el código de tu agente.

4. Para desplegar tu agente con esta cuenta de servicio, asígnate el rol Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en esta cuenta de servicio personalizada.

5. Cuando implementes tu agente, especifica la dirección de correo de tu cuenta de servicio personalizada. Para obtener más información, consulta el artículo Configurar una cuenta de servicio personalizada.

Cuenta de servicio personalizada entre proyectos

Si tu cuenta de servicio personalizada pertenece a otro proyecto, debes realizar configuraciones adicionales tanto en el proyecto en el que se encuentra la cuenta de servicio como en el proyecto en el que implementes el agente.

1. Inhabilita la política de organización de uso de cuentas de servicio entre proyectos: en el proyecto en el que se encuentra la cuenta de servicio, comprueba que la política de organización iam.disableCrossProjectServiceAccountUsage NO esté aplicada. Consulta más información en el artículo sobre cómo inhabilitar la aplicación del uso de cuentas de servicio entre proyectos.

2. Concede permisos al agente de servicio de Vertex AI: en el proyecto en el que se encuentra la cuenta de servicio, concede el rol Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) al agente de servicio de Vertex AI ([e-mail]) del proyecto en el que vas a implementar el agente.

3. Concede permisos a la cuenta de servicio personalizada: en el proyecto en el que quieras implementar el agente, concede los roles necesarios a la cuenta de servicio personalizada, tal como se describe en Usar una cuenta de servicio personalizada. Normalmente, esto incluye el rol Usuario de Vertex AI (roles/aiplatform.user) y cualquier otro rol que requiera el código de tu agente.

Crea un segmento de Cloud Storage

Vertex AI Agent Engine almacena en área de stage los artefactos de los agentes desplegados en un segmento de Cloud Storage como parte del proceso de despliegue. Asegúrate de que la entidad autenticada para usar Vertex AI (tú o una cuenta de servicio) tenga acceso Storage Admin a este bucket. Esto es necesario porque el SDK de Vertex AI para Python escribe tu código en este bucket.

Si ya tienes un contenedor configurado, puedes saltarte este paso. De lo contrario, puedes seguir las instrucciones estándar para crear un segmento.

Nota: Te recomendamos que crees un bucket de Cloud Storage en el mismo proyecto en el que implementes tus agentes en Vertex AI Agent Engine. Si usas un segmento de otro proyecto, debes conceder manualmente permisos de lectura a tu segmento de Cloud Storage al agente de servicio de Vertex AI ([e-mail]).
1. In the Google Cloud console, go to the Cloud Storage Buckets page.

   Go to Buckets

2. Click Create.
3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
   1. In the Get started section, do the following:
      • Enter a globally unique name that meets the bucket naming requirements.
      • To add a bucket label, expand the Labels section (), click Add label, and specify a key and a value for your label.
   2. In the Choose where to store your data section, do the following:
      1. Select a Location type.
      2. Choose a location where your bucket's data is permanently stored from the Location type drop-down menu.
         • If you select the dual-region location type, you can also choose to enable turbo replication by using the relevant checkbox.
      3. To set up cross-bucket replication, select Add cross-bucket replication via Storage Transfer Service and follow these steps:

         Set up cross-bucket replication

         1. In the Bucket menu, select a bucket.

         2. In the Replication settings section, click Configure to configure settings for the replication job.

            The Configure cross-bucket replication pane appears.

            • To filter objects to replicate by object name prefix, enter a prefix that you want to include or exclude objects from, then click Add a prefix.
            • To set a storage class for the replicated objects, select a storage class from the Storage class menu. If you skip this step, the replicated objects will use the destination bucket's storage class by default.
            • Click Done.
   3. In the Choose how to store your data section, do the following:
      1. Select a default storage class for the bucket or Autoclass for automatic storage class management of your bucket's data.
      2. To enable hierarchical namespace, in the Optimize storage for data-intensive workloads section, select Enable hierarchical namespace on this bucket.
         Note: You cannot enable hierarchical namespace in existing buckets.
   4. In the Choose how to control access to objects section, select whether or not your bucket enforces public access prevention, and select an access control method for your bucket's objects.
      Note: You cannot change the Prevent public access setting if this setting is enforced at an organization policy.
   5. In the Choose how to protect object data section, do the following:
      • Select any of the options under Data protection that you want to set for your bucket.
        • To enable soft delete, click the Soft delete policy (For data recovery) checkbox, and specify the number of days you want to retain objects after deletion.
        • To set Object Versioning, click the Object versioning (For version control) checkbox, and specify the maximum number of versions per object and the number of days after which the noncurrent versions expire.
        • To enable the retention policy on objects and buckets, click the Retention (For compliance) checkbox, and then do the following:
          • To enable Object Retention Lock, click the Enable object retention checkbox.
          • To enable Bucket Lock, click the Set bucket retention policy checkbox, and choose a unit of time and a length of time for your retention period.
      • To choose how your object data will be encrypted, expand the Data encryption section (), and select a Data encryption method.
4. Click Create.

Instalar e inicializar el SDK de Vertex AI para Python

En esta sección se da por hecho que has configurado un entorno de desarrollo de Python o que usas Colab (o cualquier otro entorno de ejecución adecuado que lo haya configurado por ti).

(Opcional) Configurar un entorno virtual

También te recomendamos que configures un entorno virtual para aislar tus dependencias.

Instalación

Para minimizar el conjunto de dependencias que tienes que instalar, hemos separado las dependencias en:

• agent_engines: el conjunto de paquetes necesarios para la implementación en Vertex AI Agent Engine.
• adk: el conjunto de paquetes de Agent Development Kit compatibles.
• langchain: el conjunto de paquetes compatibles de LangChain y LangGraph.
• ag2: el conjunto de paquetes de AG2 compatibles.
• llama_index: el conjunto de paquetes de LlamaIndex compatibles.

Al instalar el SDK de Vertex AI para Python, puede especificar las dependencias necesarias (separadas por comas). Para instalarlos todos, sigue estos pasos:

pip install google-cloud-aiplatform[agent_engines,adk,langchain,ag2,llama_index]>=1.88.0

Autenticación

Colab

Ejecuta el siguiente código:

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

No tienes que hacer nada.

Shell local

Ejecuta el siguiente comando:

gcloud auth application-default login

Importar e inicializar el SDK

Ejecuta el siguiente código para importar e inicializar el SDK de Vertex AI Agent Engine:

import vertexai
from vertexai import agent_engines

vertexai.init(
    project="PROJECT_ID",
    location="LOCATION",
    staging_bucket="gs://BUCKET_NAME",
)

donde

• PROJECT_ID es el Google Cloud ID de proyecto en el que desarrollarás y desplegarás agentes.
• LOCATION es una de las regiones admitidas.
• BUCKET_NAME es el nombre del segmento de Cloud Storage para organizar los artefactos al implementar agentes.

Siguientes pasos

• Desarrolla un agente.
• Solucionar problemas al configurar un entorno
• Obtener asistencia