Configura 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, tener los permisos necesarios, configurar un bucket de Cloud Storage e instalar el SDK de Vertex AI para Python. Usa los siguientes temas para asegurarte de que estés listo para comenzar 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, explora el paquete de inicio de agentes.

Configura tu Google Cloud proyecto

Cada proyecto se puede identificar de dos maneras: con el número o con el ID del proyecto. El PROJECT_NUMBER se crea automáticamente cuando creas el proyecto, mientras que el PROJECT_ID lo creas tú o la persona que haya creado el proyecto. Sigue estos pasos para configurar un proyecto:

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.

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.

Enable the APIs

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

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.

Enable the APIs

Nota: Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si no tienes este permiso, pídele a tu administrador que te otorgue el rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin).

Obtén los roles necesarios

Para obtener los permisos que necesitas para usar Vertex AI Agent Engine, pídele a tu administrador que te otorgue los siguientes roles de IAM 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 otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Configura la identidad y los permisos de tu agente

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

Tienes dos opciones para la cuenta de servicio:

• Agente de servicio predeterminado: De forma predeterminada, los agentes usan el agente de servicio de AI Platform Reasoning Engine. Esta cuenta de servicio administrada por Google tiene el rol de 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. Esto te brinda un control más detallado sobre los permisos que se otorgan a los agentes.

Usa el agente de servicio predeterminado

El agente de servicio de AI Platform Reasoning Engine se usa de forma predeterminada. Puedes ver la lista completa de permisos predeterminados en la documentación de IAM.

Si tu agente requiere permisos más allá del conjunto predeterminado, puedes otorgar roles adicionales a este agente de servicio:

1. Ve a la página IAM y marca la casilla de verificación “Incluir asignaciones de roles proporcionados por Google”.

   Ir a IAM

2. Busca el principal que coincide con [e-mail].

3. Para agregar los roles necesarios a la principal, haz clic en el botón Editar y, luego, en el botón Guardar.

Genera manualmente el agente de servicio predeterminado

Si bien el agente de servicio de Reasoning Engine se aprovisiona automáticamente durante la implementación de Vertex AI Agent Engine, puede haber situaciones en las que debas generarlo manualmente de antemano. Esto es especialmente importante cuando necesitas otorgar roles específicos al agente de servicio para garantizar que el proceso de implementación tenga los permisos necesarios y evitar posibles errores de implementación.

Sigue estos pasos para generar manualmente un agente de servicio de Reasoning Engine:

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

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

   Nota: Es posible que la respuesta al comando de Google Cloud CLI solo muestre 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 de IAM y haz clic en Otorgar acceso.

   Ir a IAM

3. En la sección Agregar principales, en el campo Principales nuevas, ingresa [e-mail].

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

5. Haz clic en el botón Guardar.

Usa una cuenta de servicio personalizada

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

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

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

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

4. Para implementar tu agente con esta cuenta de servicio, otórgate el rol de 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 electrónico de tu cuenta de servicio personalizada. Consulta Configura una cuenta de servicio personalizada para obtener más detalles.

Cuenta de servicio personalizada entre proyectos

Si tu cuenta de servicio personalizada pertenece a un proyecto diferente, necesitas configuraciones adicionales tanto en el proyecto en el que reside la cuenta de servicio como en el proyecto en el que implementas el agente.

1. Política de la organización para inhabilitar el uso de cuentas de servicio entre proyectos: En el proyecto en el que se encuentra la cuenta de servicio, asegúrate de que la política de la organización iam.disableCrossProjectServiceAccountUsage NO se aplique. Consulta Inhabilita la aplicación del uso de cuentas de servicio entre proyectos para obtener más detalles.

2. Otorga permisos al agente de servicio de Vertex AI: En el proyecto en el que se encuentra la cuenta de servicio, otorga el rol de Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) al agente de servicio de Vertex AI ([e-mail]) del proyecto en el que implementarás el agente.

3. Otorga permisos a la cuenta de servicio personalizada: En el proyecto en el que planeas implementar el agente, otorga los roles necesarios a la cuenta de servicio personalizada, como se describe en Usa una cuenta de servicio personalizada. Por lo general, esto incluye el rol de usuario de Vertex AI (roles/aiplatform.user) y cualquier otro rol que requiera el código del agente.

Cree un bucket de Cloud Storage

Vertex AI Agent Engine almacena en etapa intermedia los artefactos de los agentes implementados en un bucket de Cloud Storage como parte del proceso de implementación. Asegúrate de que la principal que esté autenticada para usar Vertex AI (ya sea 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 bucket configurado, puedes omitir este paso. De lo contrario, puedes seguir las instrucciones estándar para crear un bucket.

Nota: Te recomendamos que crees un bucket de Cloud Storage en el mismo proyecto en el que implementas tus agentes en Vertex AI Agent Engine. Si usas un bucket en un proyecto diferente, debes otorgar manualmente permisos de lectura al agente de servicio de Vertex AI ([e-mail]) en tu bucket de Cloud Storage.
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.

Instala e inicializa el SDK de Vertex AI para Python

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

Configura un entorno virtual (opcional)

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

Instalación

Para minimizar el conjunto de dependencias que debes instalar, las separamos en las siguientes categorías:

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

Cuando instales el SDK de Vertex AI para Python, puedes especificar las dependencias requeridas (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 se requiere ninguna acción.

Shell local

Ejecuta el siguiente comando:

gcloud auth application-default login

Importa e inicializa el SDK

Ejecuta el siguiente código para importar y, luego, inicializar el SDK para 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 del proyecto en el que desarrollarás y desplegarás los agentes.
• LOCATION es una de las regiones admitidas.
• BUCKET_NAME es el nombre del bucket de Cloud Storage para la etapa de pruebas de los artefactos cuando se implementan agentes.

¿Qué sigue?

• Desarrolla un agente.
• Soluciona problemas relacionados con la configuración de un entorno.
• Obtén asistencia.