Configurer l'environnement

Avant d'utiliser Vertex AI Agent Engine, vous devez vérifier que votre environnement est configuré. Vous devez avoir un projet Google Cloud avec la facturation activée, disposer des autorisations requises, configurer un bucket Cloud Storage et installer le SDK Vertex AI pour Python. Consultez les sections suivantes pour vous assurer que vous êtes prêt à commencer à utiliser Vertex AI Agent Engine.

Pour obtenir un exemple de référence Terraform permettant d'optimiser la configuration et le déploiement de l'environnement Vertex AI Agent Engine, explorez le pack agent-starter-pack.

Configurer avec Google Cloud

Vous pouvez configurer Google Cloud pour Vertex AI Agent Engine en créant un projet Google Cloud ou en vous inscrivant à Vertex AI en mode express :

Projet Google Cloud

Chaque projet peut être identifié de deux manières : par son numéro ou par son ID. PROJECT_NUMBER est automatiquement généré lorsque vous créez le projet, tandis que PROJECT_ID est défini par vous ou par le créateur du projet. Pour configurer un projet :

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

Remarque : Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous ne disposez pas de cette autorisation, demandez à votre administrateur de vous attribuer le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin).

Mode Express

Suivez les instructions de la section Vertex AI en mode Express pour configurer Vertex AI Agent Engine en mode Express.

Une fois que vous avez configuré Vertex AI Agent Engine en mode express, vous pouvez passer à l'étape Installer et initialiser le SDK Vertex AI pour Python.

Obtenir les rôles requis

Pour obtenir les autorisations nécessaires à l'utilisation de Vertex AI Agent Engine, demandez à votre administrateur de vous accorder le rôle IAM Utilisateur Vertex AI (roles/aiplatform.user) sur votre projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Configurer l'identité et les autorisations de votre agent

Lorsque vous configurez l'identité et les autorisations, vous avez le choix entre les options suivantes :

• Identité de l'agent (recommandé) (Aperçu) : utilisez l'identité de l'agent Identity and Access Management (IAM) pour fournir des fonctionnalités de sécurité et de gestion des accès lorsque vous utilisez des agents sur Vertex AI Agent Engine Runtime. L'identité de l'agent est liée à chaque agent individuel.

• Comptes de service : les comptes de service sont partagés entre les agents que vous déployez sur Vertex AI Agent Engine. Deux options s'offrent à vous pour le compte de service :

  • Agent de service par défaut : par défaut, les agents utilisent l'agent de service AI Platform Reasoning Engine. Ce compte de service géré par Google dispose du rôle Agent de service Vertex AI Reasoning Engine (roles/aiplatform.reasoningEngineServiceAgent), qui inclut les autorisations par défaut requises pour les agents déployés.
  • Compte de service personnalisé : vous pouvez spécifier votre propre compte de service que les agents utiliseront. Cela vous permet de contrôler plus précisément les autorisations accordées aux agents.

Identité de l'agent

Preview

Cette fonctionnalité est soumise(s) aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Pour configurer des règles IAM avant de déployer l'agent, vous pouvez créer une identité d'agent sans déployer votre code d'agent. Pour ce faire, créez une instance Agent Engine avec uniquement le champ identity_type :

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

Une fois que vous avez créé l'instance Agent Engine avec l'identité de l'agent, vous pouvez effectuer les opérations suivantes :

1. Provisionnez l'identité de l'agent avec les rôles recommandés suivants :

   • roles/aiplatform.expressUser : accorde l'accès à l'inférence, aux sessions et à la mémoire en cours d'exécution.

   • roles/serviceusage.serviceUsageConsumer : accordez à l'agent l'autorisation d'utiliser le quota du projet et le SDK Vertex AI.

2. Attribuez à l'identité de l'agent les rôles supplémentaires nécessaires à votre cas d'utilisation.

3. Ajoutez le code de l'agent à l'aide de agent_engine.update(...).

Agent de service par défaut

L'agent de service AI Platform Reasoning Engine est utilisé par défaut. Vous pouvez consulter la liste complète des autorisations par défaut dans la documentation IAM.

Si votre agent nécessite des autorisations supplémentaires par rapport à l'ensemble par défaut, vous pouvez attribuer des rôles supplémentaires à cet agent de service :

1. Accédez à la page IAM et cochez la case "Inclure les attributions de rôles fournies par Google".

   Accéder à IAM

2. Recherchez le compte principal correspondant à [e-mail].

3. Ajoutez les rôles requis au compte principal en cliquant sur le bouton de modification, puis sur le bouton d'enregistrement.

Générer manuellement l'agent de service par défaut

Bien que l'agent de service Reasoning Engine soit provisionné automatiquement lors du déploiement de Vertex AI Agent Engine, il peut arriver que vous deviez le générer manuellement au préalable. Cela est particulièrement important lorsque vous devez attribuer des rôles spécifiques à l'agent de service pour vous assurer que le processus de déploiement dispose des autorisations nécessaires et éviter les échecs de déploiement potentiels.

Voici comment générer manuellement un agent de service Reasoning Engine :

1. Générez l'agent de service Reasoning Engine à l'aide de la Google Cloud CLI.

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

   Remarque : La réponse à la commande Google Cloud CLI peut n'afficher que l'agent de service Vertex AI. Toutefois, l'agent de service Reasoning Engine est également créé.

2. Accédez à la page IAM, puis cliquez sur Accorder l'accès.

   Accéder à IAM

3. Dans la section Ajouter des comptes principaux, saisissez [e-mail] dans le champ Nouveaux comptes principaux.

4. Dans la section Attribuer des rôles, recherchez et sélectionnez les rôles dont vous avez besoin.

5. Cliquez sur le bouton Enregistrer.

Compte de service personnalisé

Pour utiliser votre propre compte de service, vous devez lui accorder les autorisations nécessaires pour exécuter l'agent. Votre compte de service personnalisé a probablement besoin du rôle Utilisateur Vertex AI (roles/aiplatform.user).

1. Si vous ne disposez pas d'un compte de service, créez-en un. Consultez Créer des comptes de service.

2. Attribuez le rôle Utilisateur Vertex AI (roles/aiplatform.user) au compte de service.

3. Attribuez au compte de service tous les autres rôles requis par votre code d'agent.

4. Pour déployer votre agent avec ce compte de service, accordez-vous le rôle Utilisateur de compte de service (roles/iam.serviceAccountUser) sur ce compte de service personnalisé.

5. Lorsque vous déployez votre agent, spécifiez l'adresse e-mail de votre compte de service personnalisé. Pour en savoir plus, consultez Configurer un compte de service personnalisé.

Compte de service personnalisé multiprojet

Si votre compte de service personnalisé provient d'un autre projet, vous devez effectuer des configurations supplémentaires dans le projet où réside le compte de service et dans celui où vous déployez l'agent.

1. Règle d'administration "Désactiver l'utilisation des comptes de service multiprojets" : dans le projet où se trouve le compte de service, assurez-vous que la règle d'administration iam.disableCrossProjectServiceAccountUsage N'EST PAS appliquée. Pour en savoir plus, consultez Désactiver l'application de l'utilisation des comptes de service multiprojets.

2. Attribuez des autorisations à l'agent de service Vertex AI : dans le projet où se trouve le compte de service, attribuez le rôle Créateur de jetons du compte de service (roles/iam.serviceAccountTokenCreator) à l'agent de service Vertex AI ([e-mail]) du projet dans lequel vous prévoyez de déployer l'agent.

3. Accorder des autorisations au compte de service personnalisé : dans le projet où vous prévoyez de déployer l'agent, accordez les rôles nécessaires au compte de service personnalisé. Il s'agit généralement du rôle Utilisateur Vertex AI (roles/aiplatform.user) et de tout autre rôle requis par le code de votre agent.

(Facultatif) Créer un bucket Cloud Storage

La nécessité d'un bucket Cloud Storage dépend de la question de savoir si le SDK Vertex AI pour Python a besoin d'un emplacement pour organiser le code de votre agent avant le déploiement :

• Déployer à partir de fichiers sources : l'agent existe sous forme de fichiers. Le SDK Vertex AI pour Python peut regrouper et importer ces fichiers directement dans le service de déploiement. Aucun bucket de préproduction Cloud Storage n'est donc nécessaire.

• Déployer à partir de l'objet agent : l'agent existe en mémoire. Le SDK Vertex AI pour Python crée un package de cet objet et l'importe dans un bucket Cloud Storage, qui sert de zone intermédiaire pour le service de déploiement.

Déployer à partir de fichiers sources

Si vous déployez un agent à partir de fichiers sources, un bucket Cloud Storage n'est pas nécessaire.

Déployer à partir d'un objet

Lorsque vous déployez à partir d'un objet d'agent, Vertex AI Agent Engine préproduit les artefacts de vos agents déployés dans un bucket Cloud Storage lors du processus de déploiement. Assurez-vous que le compte principal authentifié pour utiliser Vertex AI (vous-même ou un compte de service) dispose d'un accès Storage Admin à ce bucket. Cela est nécessaire, car le SDK Vertex AI pour Python écrit votre code dans ce bucket.

Si vous avez déjà configuré un bucket, vous pouvez ignorer cette étape. Sinon, vous pouvez suivre les instructions standards pour le créer.

Remarque : Nous vous recommandons vivement de créer un bucket Cloud Storage dans le même projet que celui dans lequel vous déployez vos agents sur Vertex AI Agent Engine. Si vous utilisez un bucket dans un autre projet, vous devez accorder manuellement à l'agent de service Vertex AI ([e-mail]) les autorisations de lecture sur votre bucket Cloud Storage.

Demandez à votre administrateur de vous accorder le rôle IAM Administrateur de l'espace de stockage (roles/storage.admin) sur votre projet.

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.

Installer et initialiser le SDK Vertex AI pour Python

Cette section suppose que vous avez configuré un environnement de développement Python ou que vous utilisez Colab (ou tout autre environnement d'exécution approprié qui l'a configuré pour vous).

(Facultatif) Configurer un environnement virtuel

Nous vous recommandons également de configurer un environnement virtuel pour isoler vos dépendances.

Installation

Pour réduire au maximum l'ensemble des dépendances à installer, nous avons séparé les dépendances comme suit :

• agent_engines : ensemble de packages requis pour le déploiement dans Vertex AI Agent Engine.
• adk : ensemble de packages d'Agent Development Kit compatibles.
• langchain : ensemble de packages LangChain et LangGraph compatibles.
• ag2 : ensemble de packages AG2 compatibles.
• llama_index : ensemble de packages LlamaIndex compatibles.

Lorsque vous installez le SDK Vertex AI pour Python, vous pouvez spécifier les dépendances requises (séparées par une virgule). Pour toutes les installer, exécutez la commande suivante :

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

Pour utiliser Agent2Agent (A2A) sur Agent Engine, vous devez également installer le package a2a-sdk :

pip install a2a-sdk>=0.3.4

Authentification

Colab

Exécutez le code suivant :

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

Aucune action n'est requise.

Shell local

Exécutez la commande suivante :

gcloud auth application-default login

Mode Express

Si vous utilisez Vertex AI en mode Express, aucune action n'est requise.

Importer et initialiser le SDK

Exécutez le code suivant pour importer et initialiser le SDK pour Vertex AI Agent Engine :

Projet 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",
)

Où :

• PROJECT_ID correspond à l'ID de projet Google Cloud sous lequel vous développerez et déploierez des agents.
• LOCATION désigne l'une des régions compatibles.

Mode Express

Si vous utilisez Vertex AI en mode Express, exécutez le code suivant :

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"
)

où API_KEY correspond à la clé API que vous utilisez pour authentifier l'agent.

Étapes suivantes

• Développez un agent.
• Résolvez les problèmes de configuration d'un environnement.
• Obtenez de l'aide.