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 avec Google Cloud pour Vertex AI Agent Engine en créant un Google Cloud projet.

Google Cloud Projet

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 :

Connectez-vous à votre Google Cloud compte. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $de crédits sans frais pour exécuter, tester et déployer des charges de travail.

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, 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.

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, 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

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

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

Vous disposez des options suivantes pour configurer l'identité et les autorisations :

• Identité de l'agent (recommandé) (preview) : utilisez l'identité de l'agent Identity Access Management (IAM) pour fournir des fonctionnalités de sécurité et de gestion des accès lorsque vous utilisez des agents sur l'environnement d'exécution Vertex AI Agent Engine. L'identité de l'agent est liée à chaque agent.

• Comptes de service : les comptes de service sont partagés entre les agents que vous déployez sur Vertex AI Agent Engine. Vous disposez de deux options 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 Reasoning Engine Vertex AI (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 pour que les agents l'utilisent. Cela vous permet de contrôler plus précisément les autorisations accordées aux agents.

Identité de l'agent

Preview : interface Private Service Connect

Cette fonctionnalité est soumise 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 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 stratégies IAM avant de déployer l'agent, vous pouvez créer une identité d'agent sans déployer le code de votre agent. Pour ce faire, créez une instance Agent Engine avec uniquement le champ identity_type :

remote_app = client.agent_engines.create(
      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/serviceusage.serviceUsageConsumer: accordez à l'agent l'autorisation d'utiliser le quota du projet et le SDK Vertex AI.

2. Accordez à l'identité de l'agent des rôles supplémentaires selon vos besoins.

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 au-delà de 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ôle 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, dans le champ Nouveaux comptes principaux, saisissez [e-mail].

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 la section 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 le code de votre agent.

4. Pour déployer votre agent avec ce compte de service, accordez-vous le rôle Utilisateur du 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 la section 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 le projet où vous déployez l'agent.

1. Désactivez la règle d'administration concernant 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 la section Désactiver l'application de l'utilisation des comptes de service multiprojets.

2. Accordez des autorisations à l'agent de service Vertex AI : dans le projet où se trouve le compte de service, accordez le rôle Créateur de jetons de 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. Accordez 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é. Cela inclut généralement le rôle Utilisateur Vertex AI (roles/aiplatform.user) et tous les autres rôles requis par le code de votre agent.

(Facultatif) Créer un bucket Cloud Storage

La nécessité d'un bucket Cloud Storage dépend du fait que le SDK Vertex AI pour Python ait besoin d'un emplacement pour préproduire 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 d'un 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 de préproduction pour le service de déploiement.

Déployer à partir de fichiers sources

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

Déployer à partir d'un objet

Lorsque vous déployez à partir d'un objet 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]) des 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.

Google Cloud Console

1. Dans la Google Cloud console, accédez à la page Buckets de Cloud Storage.

   Accéder à la page "Buckets"

2. Cliquez sur Créer.
3. Sur la page Créer un bucket, saisissez les informations concernant votre bucket. Pour passer à l'étape suivante, cliquez sur Continuer.
   1. Dans la section Premiers pas, procédez comme suit :
      • Saisissez un nom unique qui répond aux exigences relatives aux noms des buckets.
      • Pour ajouter une étiquette de bucket, développez la section Étiquettes (), cliquez sur Ajouter une étiquette, puis spécifiez un élément key et un élément value pour votre étiquette.
   2. Dans la section Choisir l'emplacement de stockage de vos données, procédez comme suit :
      1. Sélectionnez un type d'emplacement.
      2. Choisissez un emplacement où les données de votre bucket seront stockées de manière permanente dans le menu déroulant Type d'emplacement.
         • Si vous sélectionnez le type d'emplacement birégional, vous pouvez également choisir d'activer la réplication turbo à l'aide de la case à cocher correspondante.
      3. Pour configurer la réplication entre buckets, sélectionnez Ajouter une réplication entre buckets via le service de transfert de stockage , puis procédez comme suit :

         Configurer la réplication entre buckets

         1. Dans le menu Bucket, sélectionnez un bucket.

         2. Dans la section Paramètres de réplication , cliquez sur Configurer pour configurer les paramètres du job de réplication.

            Le volet Configurer la réplication entre buckets s'affiche.

            • Pour filtrer les objets à répliquer en fonction du préfixe de leur nom, saisissez le préfixe avec lequel vous souhaitez inclure ou exclure des objets, puis cliquez sur Ajouter un préfixe.
            • Pour définir une classe de stockage pour les objets répliqués, sélectionnez-en une dans le menu Classe de stockage. Si vous ignorez cette étape, les objets répliqués utiliseront la classe de stockage par défaut du bucket de destination.
            • Cliquez sur OK.
   3. Dans la section Choisir comment stocker vos données, procédez comme suit :
      1. Sélectionnez une classe de stockage par défaut pour le bucket ou bien classe automatique pour gérer automatiquement les classes de stockage des données de votre bucket.
      2. Pour activer l'espace de noms hiérarchique, dans la section Optimiser le stockage pour les charges de travail utilisant beaucoup de données, sélectionnez Activer l'espace de noms hiérarchique sur ce bucket.
         Remarque : Vous ne pouvez pas activer l'espace de noms hiérarchique dans les buckets existants.
   4. Dans la section Choisir comment contrôler l'accès aux objets, indiquez si votre bucket applique ou non la protection contre l'accès public, et sélectionnez une méthode de contrôle des accès pour les objets de votre bucket.
      Remarque : Vous ne pouvez pas modifier le paramètre Empêcher l'accès public si ce paramètre est appliqué au niveau d'une règle d'administration.
   5. Dans la section Choisir comment protéger les données d'objet, procédez comme suit :
      • Sous Protection des données , sélectionnez les options que vous voulez définir pour votre bucket.
        • Pour activer la suppression réversible, cochez la case Règle de suppression réversible (pour la récupération de données), puis spécifiez le nombre de jours pendant lesquels vous souhaitez conserver les objets après leur suppression.
        • Pour définir la gestion des versions d'objets, cochez la case Gestion des versions d'objets (pour le contrôle des versions), puis spécifiez le nombre maximal de versions par objet et le nombre de jours après lesquels les versions obsolètes expirent.
        • Pour activer la règle de conservation sur les objets et les buckets, cochez la case Conservation (pour la conformité), puis procédez comme suit :
          • Pour activer le verrouillage de la conservation des objets, cochez la case Activer la conservation des objets.
          • Pour activer le verrouillage de bucket, cochez la case Définir une règle de conservation de bucket, puis choisissez une unité de temps et une durée pour votre période de conservation.
      • Pour choisir comment vos données d'objet seront chiffrées, développez la section Chiffrement des données (), puis sélectionnez une méthode de chiffrement des données.
4. Cliquez sur Créer.

Ligne de commande

Créez un bucket Cloud Storage et configurez-le comme suit :
• Remplacez STORAGE_CLASS par la classe de stockage de votre choix .
• Remplacez LOCATION par l'emplacement de votre choix (ASIA, EU, ou US)
• Remplacez BUCKET_NAME par un nom qui répond aux conditions requises pour le nom des buckets.

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

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

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' Google Cloud ID de projet sous lequel vous développez et déployez des agents.
• LOCATION désigne l'une des régions compatibles.

Étape suivante

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