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

Puedes configurar Google Cloud para Vertex AI Agent Engine creando un proyecto Google Cloud .

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:

Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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.

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, Cloud Trace, and Resource Manager 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.

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, Cloud Trace, and Resource Manager 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

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) (versión preliminar): 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

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 = client.agent_engines.create(
      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:

Aprovisiona la identidad del agente con los siguientes roles recomendados:
- roles/serviceusage.serviceUsageConsumer: Otorga permiso al agente para usar la cuota del proyecto y el SDK de Vertex AI.
Otorga a la identidad del agente roles adicionales según sea necesario para tu caso de uso.
Agrega código del agente con agent_engine.update(...).

Agente de servicio predeterminado

De forma predeterminada, se usa el agente de servicio de AI Platform Reasoning Engine. 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:

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

Ir a IAM
Busca el principal que coincide con service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.
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.

Estos son los pasos para generar manualmente un agente de servicio de Reasoning Engine:

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.
Ve a la página de IAM y haz clic en Otorgar acceso.

Ir a IAM
En la sección Agregar principales, en el campo Principales nuevas, ingresa service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.
En la sección Asignar roles, busca y selecciona los roles que necesitas.
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).

Si no tienes una cuenta de servicio, crea una. Consulta Crea cuentas de servicio.
Otorga a la cuenta de servicio el rol de usuario de Vertex AI (roles/aiplatform.user).
Otorga a la cuenta de servicio cualquier otro rol que requiera el código del agente.
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.
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.

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.
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 (service-RESOURCE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) del proyecto en el que planeas implementar el agente.
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 de tu agente antes de la implementación:

Implementación desde archivos fuente: El agente existe como archivos. El SDK de Vertex AI para Python puede agrupar 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 tus 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.

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

Consola deGoogle Cloud

En la consola de Google Cloud , ve a la página Buckets de Cloud Storage.
Ir a Buckets
Haz clic en Crear.
En la página Crear un bucket, ingresa la información de tu bucket. Para ir al paso siguiente, haz clic en Continuar.
1. En la sección Primeros pasos, haz lo siguiente:
  - Ingresa un nombre único a nivel global que cumpla con los requisitos de nombre de los buckets.
  - Para agregar una etiqueta de bucket, expande la sección Etiquetas (), haz clic en Agregar etiqueta y especifica una key y un value para tu etiqueta.
2. En la sección Elige dónde almacenar tus datos, haz lo siguiente:
  1. Selecciona un tipo de ubicación
  2. Elige una ubicación en la que se almacenen de forma permanente los datos de tu bucket en el menú desplegable Tipo de ubicación.
    - Si seleccionas el tipo de ubicación birregional, también puedes habilitar la replicación turbo con la casilla de verificación correspondiente.
  3. Para configurar la replicación bucket buckets, selecciona Agregar replicación entre bucket a través del Servicio de transferencia de almacenamiento y sigue estos pasos:
    Configura la replicación entre buckets
    
    En el menú Bucket, selecciona un bucket.
    
    En la sección Configuración de replicación, haz clic en Configurar para configurar los parámetros del trabajo de replicación.
    
    Aparecerá el panel Configurar la replicación entre buckets.
    
    Para filtrar los objetos que se replicarán por prefijo de nombre de objeto, ingresa un prefijo con el que quieras incluir o excluir objetos y, luego, haz clic en Agregar un prefijo.
    
    Para establecer una clase de almacenamiento para los objetos replicados, selecciona una clase de almacenamiento en el menú Clase de almacenamiento. Si omites este paso, los objetos replicados usarán la clase de almacenamiento del bucket de destino de forma predeterminada.
    
    Haz clic en Listo.
3. En la sección Elige cómo almacenar tus datos, haz lo siguiente:
  1. Selecciona una clase de almacenamiento predeterminada para el bucket o Autoclass para la administración automática de clases de almacenamiento de los datos de tu bucket.
  2. Para habilitar el espacio de nombres jerárquico, en la sección Optimizar el almacenamiento para cargas de trabajo con uso intensivo de datos, selecciona Habilitar el espacio de nombres jerárquico en este bucket.
    Nota: No puedes habilitar el espacio de nombres jerárquico en buckets existentes.
4. En la sección Elige cómo controlar el acceso a los objetos, selecciona si tu bucket aplica o no la prevención del acceso público y elige un método de control de acceso para los objetos del bucket.
  Nota: No puedes cambiar el parámetro de configuración Impedir el acceso público si este parámetro se aplica en una política de la organización.
5. En la sección Elige cómo proteger los datos de objetos, haz lo siguiente:
  - Selecciona cualquiera de las opciones de Protección de datos que desees configurar para tu bucket.
    - Para habilitar la eliminación no definitiva, haz clic en la casilla de verificación Política de eliminación no definitiva (para la recuperación de datos) y especifica la cantidad de días que deseas conservar los objetos después de la eliminación.
    - Para configurar el control de versiones de objetos, haz clic en la casilla de verificación Control de versiones de objetos (para el control de versión) y especifica la cantidad máxima de versiones por objeto y la cantidad de días después de los cuales vencen las versiones no actuales.
    - Para habilitar la política de retención en objetos y buckets, haz clic en la casilla de verificación Retención (para cumplimiento) y, luego, haz lo siguiente:
      - Para habilitar el bloqueo de retención de objetos, haz clic en la casilla de verificación Habilitar la retención de objetos.
      - Para habilitar el Bloqueo del bucket, haz clic en la casilla de verificación Establecer política de retención del bucket y elige una unidad de tiempo y una duración para tu período de retención.
  - Para elegir cómo se encriptarán los datos de tus objetos, expande la sección Encriptación de datos () y selecciona un método de encriptación de datos.
Haz clic en Crear.

Línea de comandos

Reemplaza STORAGE_CLASS por tu clase de almacenamiento de preferencia.
Reemplaza LOCATION por tu ubicación preferida (ASIA, EU o US).
Reemplaza BUCKET_NAME por un nombre de bucket que cumpla con los requisitos de nombre de buckets.

gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

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

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.

(Opcional) Trae tu propio contenedor (BYOC)

Vertex AI Agent Engine compila un contenedor para ti como parte del proceso de implementación. Si planeas compilar tu propio contenedor para la implementación, deberás seguir las instrucciones de las siguientes subsecciones. En un nivel alto, se reduce a los siguientes pasos:

Compila y envía una imagen de contenedor a Artifact Registry.
Configura las cuentas de servicio para Vertex AI Agent Engine que corresponden al proyecto del usuario (en Configura la identidad y los permisos de tu agente) y al proyecto del arrendatario (en el que se ejecuta el tiempo de ejecución).
Otorga el rol roles/artifactregistry.reader a la cuenta de servicio del proyecto del usuario y a la cuenta de servicio del proyecto del arrendatario.

Compila y envía una imagen de contenedor

Para compilar y enviar una imagen de contenedor, sigue las instrucciones que se indican en Compila y envía una imagen de Docker con Cloud Build.

Configura las cuentas de servicio para Vertex AI Agent Engine

Para configurar las cuentas de servicio, implementa un agente que imprima la cuenta de servicio del arrendatario.

Primero, configura el código fuente del agente:

Abre una ventana de la terminal
Crea un directorio nuevo llamado byoc_setup.
```
mkdir byoc_setup
```

Crea un archivo en el directorio byoc_setup llamado metadata_agent.py con el siguiente contenido:

class MetadataAgent:

  def query(self):
    import requests
    url = "http://metadata.google.internal/computeMetadata/v1/project/numeric-project-id"
    try:
        response = requests.get(url, headers={"Metadata-Flavor": "Google"})
        response.raise_for_status()
        return f"service-{response.text}@serverless-robot-prod.iam.gserviceaccount.com"
    except Exception:
        return None

root_agent = MetadataAgent()

Crea otro archivo en el directorio byoc_setup llamado requirements.txt con el siguiente contenido:
```
google-cloud-aiplatform[agent_engines]
```

Si aún no lo hiciste, instala e inicializa el SDK de Vertex AI para Python. En la misma sesión de Python en la que inicializaste el SDK de Vertex AI para Python, ejecuta el siguiente código para imprimir un TENANT_SERVICE_ACCOUNT:

remote_agent = client.agent_engines.create( # This deploys the agent
    config={
        "source_packages": ["byoc_setup"],
        "entrypoint_module": "byoc_setup.metadata_agent",
        "entrypoint_object": "root_agent",
        "requirements_file": "byoc_setup/requirements.txt",
        "class_methods": [{'api_mode': '', 'name': 'query'}],
    },
)
# This prints the tenant service account
# service-{tenant_project_number}@serverless-robot-prod.iam.gserviceaccount.com
print(remote_agent.query())
# This cleans up the resources
remote_agent.delete(force=True)

Busca el USER_SERVICE_ACCOUNT en Configura la identidad y los permisos de tu agente. Si usas el agente de servicio predeterminado, este valor debe coincidir con service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

Otorga roles de lector de Artifact Registry

Otorga los roles necesarios ejecutando los siguientes comandos:

gcloud projects add-iam-policy-binding <var>PROJECT_NUMBER</var> \
  --member="serviceAccount:USER_SERVICE_ACCOUNT" \
  --role="roles/artifactregistry.reader"
gcloud projects add-iam-policy-binding <var>PROJECT_NUMBER</var> \
  --member="serviceAccount:TENANT_SERVICE_ACCOUNT" \
  --role="roles/artifactregistry.reader"

Configura el entorno Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Configurar con Google Cloud

Google Cloud proyecto

Obtén los roles necesarios

Configura la identidad y los permisos de tu agente

Identidad del agente

Agente de servicio predeterminado

Genera manualmente el agente de servicio predeterminado

Cuenta de servicio personalizada

Cuenta de servicio personalizada entre proyectos

(Opcional) Crea un bucket de Cloud Storage

Implementa desde archivos fuente

Implementa desde el objeto

Consola deGoogle Cloud

Configura la replicación entre buckets

Línea de comandos

Instala e inicializa el SDK de Vertex AI para Python

Configura un entorno virtual (opcional)

Instalación

Autenticación

Colab

Cloud Shell

Shell local

Importa e inicializa el SDK

Proyecto de Google Cloud

(Opcional) Trae tu propio contenedor (BYOC)

Compila y envía una imagen de contenedor

Configura las cuentas de servicio para Vertex AI Agent Engine

Otorga roles de lector de Artifact Registry

¿Qué sigue?

Configura el entorno