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 con Google Cloud

Puedes configurar Google Cloud para Vertex AI Agent Engine Google Cloud creando un proyecto o registrándote en Vertex AI en modo exprés:

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 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, pide a tu administrador que te conceda el rol Administrador de uso de servicios (roles/serviceusage.serviceUsageAdmin).

Modo Exprés

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

Una vez que hayas configurado Vertex AI Agent Engine en modo exprés, puedes saltar al paso Instalar e inicializar el SDK de Vertex AI para Python.

Obtener los roles necesarios

Para obtener los permisos que necesitas para usar Vertex AI Agent Engine, pide a tu administrador que te asigne el rol de gestión de identidades y accesos Usuario de Vertex AI (roles/aiplatform.user) en tu proyecto. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar 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

Al configurar la identidad y los permisos, tiene las siguientes opciones:

• Identidad del agente (recomendado) (Vista previa): usa la identidad del agente de gestión de identidades y accesos (IAM) para proporcionar funciones de seguridad y gestión de accesos al usar agentes en el tiempo de ejecución de Vertex AI Agent Engine. La identidad del agente está vinculada a cada agente.

• Cuentas de servicio: las cuentas de servicio se comparten entre los agentes que despliegues 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 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.

Identidad del agente

Vista previa

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

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

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

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

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

   • roles/aiplatform.expressUser: concede acceso para ejecutar inferencias, sesiones y memoria.

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

2. Asigna a la identidad del agente los roles adicionales que necesites para tu caso práctico.

3. Añade el 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 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 tengas que 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).

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 los demás roles 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 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, asegúrate de 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 quieras 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. Normalmente, esto incluye el rol Usuario de Vertex AI (roles/aiplatform.user) y cualquier otro rol que requiera el código de tu agente.

(Opcional) Crear un segmento de Cloud Storage

La necesidad de un segmento de Cloud Storage depende de si el SDK de Vertex AI para Python necesita un lugar para almacenar el código de tu agente antes de la implementación:

• Implementar desde archivos de origen: 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 ningún segmento de almacenamiento provisional de Cloud Storage.

• Implementar desde el objeto del agente: el agente existe en la memoria. El SDK de Vertex AI para Python empaqueta este objeto y lo sube a un segmento de Cloud Storage, que actúa como área de almacenamiento temporal para el servicio de implementación.

Desplegar desde archivos de origen

Si implementas un agente a partir de archivos de origen, no es necesario que tengas un segmento de Cloud Storage.

Implementar desde un objeto

Cuando despliegas desde un objeto de agente, Vertex AI Agent Engine almacena los artefactos de los agentes desplegados en un bucket 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]).

Pide a tu administrador que te conceda el rol de gestión de identidades y accesos Administrador de Storage (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.

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 las siguientes categorías:

• 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.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 tienes que hacer nada.

Shell local

Ejecuta el siguiente comando:

gcloud auth application-default login

Modo Exprés

Si usas Vertex AI en modo exprés, no tienes que hacer nada.

Importar e inicializar el SDK

Ejecuta el siguiente código para importar e inicializar el SDK de 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 de proyecto en el que desarrollas y despliegas agentes.
• LOCATION es una de las regiones admitidas.

Modo Exprés

Si usas Vertex AI en modo exprés, 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.

Siguientes pasos

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