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 obtener un ejemplo de referencia de Terraform que agilice la configuración y la implementación del entorno de Vertex AI Agent Engine, explora el agent-starter-pack.

Configurar con Google Cloud

Para configurar Google Cloud para Vertex AI Agent Engine, crea un proyecto de Google Cloud o regístrate en Vertex AI en modo express:

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.

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 role (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, Telemetry, 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 role (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, Telemetry, 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, pídele a tu administrador que te otorgue el rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin).

Modo Exprés

Sigue las instrucciones en Vertex AI en modo exprés para configurar Vertex AI Agent Engine en modo exprés.

Una vez que configures Vertex AI Agent Engine en modo rápido, puedes omitir el paso Instala e inicializa el SDK de Vertex AI para Python.

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 el rol de IAM de Usuario de Vertex AI (roles/aiplatform.user) en tu proyecto. 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

Tienes las siguientes opciones cuando configuras la identidad y los permisos:

• Identidad del agente (recomendado) (vista previa): Usa la identidad del agente de Identity and Access Management (IAM) para proporcionar funciones de seguridad y administración de acceso cuando uses agentes en el entorno de ejecución de Vertex AI Agent Engine. La identidad del agente está vinculada a cada agente individual.

• Cuentas de servicio: Las cuentas de servicio se comparten entre los agentes que implementas en Vertex AI Agent Engine. 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.

Identidad del agente

Versión preliminar

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Para configurar políticas de IAM antes de implementar el agente, puedes crear una identidad del agente sin implementar el código del agente. Para ello, crea una instancia de Agent Engine solo con el campo identity_type:

remote_app = agent_engines.create(
      agent=app,
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
      },
)

Una vez que crees la instancia de Agent Engine con la identidad del agente, podrás hacer lo siguiente:

1. Aprovisiona la identidad del agente con los siguientes roles recomendados:

   • roles/aiplatform.expressUser: Otorga acceso a la ejecución de inferencias, sesiones y memoria.

   • roles/serviceusage.serviceUsageConsumer: Otorga permiso al agente para usar la cuota del proyecto y el SDK de Vertex AI.

2. Otorga a la identidad del agente roles adicionales según sea necesario para tu caso de uso.

3. Agrega código del agente con agent_engine.update(...).

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.

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 planeas implementar 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. Por lo general, esto incluye el rol de usuario de Vertex AI (roles/aiplatform.user) y cualquier otro rol que requiera el código de tu agente.

(Opcional) Crea un bucket de Cloud Storage

La necesidad de un bucket de Cloud Storage depende de si el SDK de Vertex AI para Python necesita un lugar para almacenar en etapa intermedia el código del agente antes de la implementación:

• Implementación desde archivos fuente: El agente existe como archivos. El SDK de Vertex AI para Python puede empaquetar y subir estos archivos directamente al servicio de implementación, por lo que no se necesita un bucket de Cloud Storage de etapa intermedia.

• Deploy from agent object: El agente existe en la memoria. El SDK de Vertex AI para Python empaqueta este objeto y lo sube a un bucket de Cloud Storage, que actúa como área de etapa de pruebas para el servicio de implementación.

Implementa desde archivos fuente

Si implementas un agente a partir de archivos fuente, no se requiere un bucket de Cloud Storage.

Implementa desde el objeto

Cuando realizas la implementación desde un objeto de agente, 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.

Pídele a tu administrador que te otorgue el rol de IAM de Administrador de almacenamiento (roles/storage.admin) en tu proyecto.

In the Google Cloud console, go to the Cloud Storage Buckets page.

Go to Buckets

Click Create.

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.

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 compatibles del Kit de desarrollo de agentes.
• 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.112.0

Para usar Agent2Agent (A2A) en Agent Engine, también debes instalar el paquete a2a-sdk:

pip install a2a-sdk>=0.3.4

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 comando siguiente:

gcloud auth application-default login

Modo Exprés

Si usas Vertex AI en modo exprés, no es necesario que realices ninguna acción.

Importa e inicializa el SDK

Ejecuta el siguiente código para importar y, luego, inicializar el SDK para Vertex AI Agent Engine:

Proyecto de Google Cloud

import vertexai
from vertexai import agent_engines # For the prebuilt templates

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

donde

• PROJECT_ID es el Google Cloud ID del proyecto en el que desarrollas y despliegas agentes.
• LOCATION es una de las regiones admitidas.

Modo Exprés

Si usas Vertex AI en modo express, ejecuta el siguiente código:

import vertexai
from vertexai import agent_engines # For the prebuilt ADK template

client = vertexai.Client(  # For service interactions via client.agent_engines
    api_key="API_KEY"
)

donde API_KEY es la clave de API que usas para autenticar el agente.

¿Qué sigue?

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