Configurare l'ambiente

Prima di lavorare con Vertex AI Agent Engine, devi assicurarti che il tuo ambiente sia configurato. Devi avere un Google Cloud progetto con la fatturazione abilitata, disporre delle autorizzazioni richieste, configurare un bucket Cloud Storage e installare l'SDK Vertex AI per Python. Utilizza i seguenti argomenti per assicurarti di essere pronto per iniziare a lavorare con Vertex AI Agent Engine.

Per un esempio di riferimento di Terraform per semplificare la configurazione e il deployment dell'ambiente Vertex AI Agent Engine, valuta la possibilità di esplorare il pacchetto di avvio dell'agente.

Configurazione con Google Cloud

Puoi configurare con Google Cloud per Vertex AI Agent Engine con creando un Google Cloud progetto.

Google Cloud progetto

Ogni progetto può essere identificato in due modi: tramite il numero del progetto o l'ID progetto. Il PROJECT_NUMBER viene creato automaticamente in fase di creazione del progetto, mentre l'PROJECT_ID viene creato da te o da chiunque abbia creato il progetto. Per configurare un progetto:

Accedi al tuo Google Cloud account. Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

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

Nota: per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se non disponi di questa autorizzazione, chiedi all'amministratore di concederti il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin).

Ottieni i ruoli richiesti

Per ottenere le autorizzazioni necessarie per utilizzare Vertex AI Agent Engine, chiedi all'amministratore di concederti il ruolo IAM Utente Vertex AI (roles/aiplatform.user) nel tuo progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura l'identità e le autorizzazioni per l'agente

Quando configuri l'identità e le autorizzazioni, hai le seguenti opzioni:

• Identità dell'agente (consigliata) (anteprima): utilizza l'identità dell'agente Identity Access Management (IAM) per fornire funzionalità di sicurezza e gestione degli accessi quando utilizzi gli agenti su Vertex AI Agent Engine Runtime. L'identità dell'agente è associata a ogni singolo agente.

• Service account: i service account vengono condivisi tra gli agenti di cui esegui il deployment in Vertex AI Agent Engine. Hai due opzioni per il account di servizio:

  • Agente di servizio predefinito: per impostazione predefinita, gli agenti utilizzano l'agente di servizio del motore di ragionamento AI Platform. Questo account di servizio gestito da Google ha il ruolo Agente di servizio del motore di ragionamento Vertex AI (roles/aiplatform.reasoningEngineServiceAgent), che include le autorizzazioni predefinite richieste per gli agenti di cui è stato eseguito il deployment.
  • Service account personalizzato: puoi specificare il tuo account di servizio da utilizzare per gli agenti. In questo modo hai un controllo più granulare sulle autorizzazioni concesse agli agenti.

Identità dell'agente

Anteprima — interfaccia Private Service Connect

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Per configurare le policy IAM prima di eseguire il deployment dell'agente, puoi creare un'identità dell'agente senza eseguire il deployment del codice dell'agente. Per farlo, crea un'istanza di Agent Engine con il solo campo identity_type:

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

Dopo aver creato l'istanza di Agent Engine con l'identità dell'agente, puoi:

1. Esegui il provisioning dell'identità dell'agente con i seguenti ruoli consigliati:

   • roles/serviceusage.serviceUsageConsumer: concedi all'agente l'autorizzazione a utilizzare la quota del progetto e l'SDK Vertex AI.

2. Concedi all'identità dell'agente ruoli aggiuntivi, se necessario per il tuo caso d'uso.

3. Aggiungi il codice dell'agente utilizzando agent_engine.update(...).

Agente di servizio predefinito

Per impostazione predefinita, viene utilizzato l'agente di servizio del motore di ragionamento AI Platform. Puoi visualizzare l'elenco completo delle autorizzazioni predefinite nella documentazione di IAM.

Se il tuo agente richiede autorizzazioni aggiuntive rispetto al set predefinito, puoi concedere a questo agente di servizio ruoli aggiuntivi:

1. Vai alla pagina IAM e seleziona la casella di controllo "Includi concessioni di ruoli fornite da Google".

   Vai a IAM

2. Trova l'entità che corrisponde a [e-mail].

3. Aggiungi i ruoli richiesti all'entità facendo clic sul pulsante Modifica e poi sul pulsante Salva.

Genera manualmente il service agent predefinito

Sebbene il provisioning dell'agente di servizio del motore di ragionamento venga eseguito automaticamente durante il deployment di Vertex AI Agent Engine, potrebbero esistere scenari in cui devi generarlo manualmente in anticipo. Questo è particolarmente importante quando devi concedere ruoli specifici all'agente di servizio per assicurarti che il processo di deployment disponga delle autorizzazioni necessarie ed evitare potenziali errori di deployment.

Ecco i passaggi per generare manualmente un agente di servizio del motore di ragionamento:

1. Genera l'agente di servizio del motore di ragionamento utilizzando Google Cloud CLI.

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

   Nota: la risposta al comando Google Cloud CLI potrebbe mostrare solo l'agente di servizio Vertex AI. Tuttavia, viene creato anche l'agente di servizio del motore di ragionamento.

2. Vai alla pagina IAM e fai clic su Concedi l'accesso.

   Vai a IAM

3. Nella sezione Aggiungi entità, nel campo Nuove entità, inserisci [e-mail].

4. Nella sezione Assegna ruoli, trova e seleziona i ruoli di cui hai bisogno.

5. Fai clic sul pulsante Salva.

Account di servizio personalizzato

Per utilizzare il tuo account di servizio, devi concedergli le autorizzazioni necessarie per eseguire l'agente. Il tuo account di servizio personalizzato probabilmente richiede il ruolo Utente Vertex AI (roles/aiplatform.user).

1. Se non hai un account di servizio, creane uno. Consulta Creare service account.

2. Concedi al account di servizio il ruolo Utente Vertex AI (roles/aiplatform.user).

3. Concedi al account di servizio tutti gli altri ruoli richiesti dal codice dell'agente.

4. Per eseguire il deployment dell'agente con questo account di servizio, concediti il ruolo Utente service account (roles/iam.serviceAccountUser) in questo service account personalizzato.

5. Quando esegui il deployment dell'agente, specifica l'indirizzo email del tuo service account personalizzato. Per i dettagli, consulta Configurare un service account personalizzato.

Account di servizio personalizzato tra progetti

Se il tuo account di servizio personalizzato proviene da un progetto diverso, devi eseguire configurazioni aggiuntive sia nel progetto in cui risiede il account di servizio sia nel progetto in cui esegui il deployment dell'agente.

1. Disattiva la policy dell'organizzazione per l'utilizzo di account di servizio tra progetti: nel progetto in cui si trova il account di servizio, assicurati che la policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage NON sia applicata. Per maggiori dettagli, consulta Disattivare l'applicazione dell'utilizzo di account di servizio tra progetti.

2. Concedi le autorizzazioni all'agente di servizio Vertex AI: nel progetto in cui si trova il account di servizio, concedi il ruolo Creatore token service account (roles/iam.serviceAccountTokenCreator) all'agente di servizio Vertex AI ([e-mail]) del progetto in cui prevedi di eseguire il deployment dell'agente.

3. Concedi le autorizzazioni al account di servizio personalizzato: nel progetto in cui prevedi di eseguire il deployment dell'agente, concedi i ruoli necessari al account di servizio personalizzato. In genere, questo include il ruolo Utente Vertex AI (roles/aiplatform.user) e tutti gli altri ruoli richiesti dal codice dell'agente.

(Facoltativo) Crea un bucket Cloud Storage

La necessità di un bucket Cloud Storage dipende dal fatto che l'SDK Vertex AI per Python abbia bisogno di uno spazio per archiviare in un'area intermedia il codice dell'agente prima del deployment:

• Esegui il deployment dai file di origine: l'agente esiste come file. L'SDK Vertex AI per Python può raggruppare e caricare questi file direttamente nel servizio di deployment, quindi non è necessario un bucket di gestione temporanea di Cloud Storage.

• Esegui il deployment dall'oggetto agente: l'agente esiste in memoria. L'SDK Vertex AI Python pacchettizza questo oggetto e lo carica in un bucket Cloud Storage, che funge da area di gestione temporanea per il servizio di deployment.

Esegui il deployment dai file di origine

Se esegui il deployment di un agente dai file di origine, non è necessario un bucket Cloud Storage.

Esegui il deployment dall'oggetto

Quando esegui il deployment da un oggetto agente, Vertex AI Agent Engine prepara gli artefatti degli agenti di cui è stato eseguito il deployment in un bucket Cloud Storage nell'ambito del processo di deployment. Assicurati che l'entità autenticata per utilizzare Vertex AI (tu o un account di servizio) abbia accesso Storage Admin a questo bucket. Questo è necessario perché l'SDK Vertex AI Python scrive il codice in questo bucket.

Se hai già configurato un bucket, puoi saltare questo passaggio. In caso contrario, puoi seguire le istruzioni standard per la creazione di un bucket.

Nota: ti consigliamo vivamente di creare un bucket Cloud Storage nello stesso progetto in cui esegui il deployment degli agenti in Vertex AI Agent Engine. Se utilizzi un bucket in un progetto diverso, devi concedere manualmente all'agente di servizio Vertex AI ([e-mail]) le autorizzazioni di lettura per il tuo bucket Cloud Storage.

Chiedi all'amministratore di concederti il ruolo IAM Amministratore Storage (roles/storage.admin) nel tuo progetto.

Google Cloud Console

1. Nella Google Cloud console, vai alla pagina Bucket in Cloud Storage.

   Vai a Bucket

2. Fai clic su Crea.
3. Nella pagina Crea un bucket, inserisci le informazioni del bucket. Per passare al passaggio successivo, fai clic su Continua.
   1. Nella sezione Inizia, segui questi passaggi:
      • Inserisci un nome univoco a livello globale che soddisfi i requisiti di denominazione dei bucket.
      • Per aggiungere un' etichetta del bucket, espandi la sezione Etichette (), fai clic su Aggiungi etichetta e specifica una key e un value per l'etichetta.
   2. Nella sezione Scegli dove archiviare i tuoi dati, segui questi passaggi:
      1. Seleziona un tipo di località.
      2. Scegli una località in cui i dati del bucket vengono archiviati in modo permanente dal menu a discesa Tipo di località.
         • Se selezioni il tipo di località a due regioni, puoi anche scegliere di abilitare la replica turbo utilizzando la casella di controllo pertinente.
      3. Per configurare la replica tra bucket, seleziona Aggiungi una replica tra bucket mediante Storage Transfer Service e segui questi passaggi:

         Configura la replica tra bucket

         1. Nel menu Bucket, seleziona un bucket.

         2. Nella sezione Impostazioni di replica , fai clic su Configura per configurare le impostazioni del job di replica.

            Viene visualizzato il riquadro Configura replica tra bucket.

            • Per filtrare gli oggetti da replicare in base al prefisso del nome dell'oggetto, inserisci un prefisso da includere o escludere gli oggetti, quindi fai clic su Aggiungi un prefisso.
            • Per impostare una classe di archiviazione per gli oggetti replicati, seleziona una classe di archiviazione dal menu Classe di archiviazione. Se salti questo passaggio, gli oggetti replicati utilizzeranno per impostazione predefinita la classe di archiviazione del bucket di destinazione.
            • Fai clic su Fine.
   3. Nella sezione Scegli come archiviare i tuoi dati, segui questi passaggi:
      1. Seleziona una classe di archiviazione predefinita per il bucket o Autoclass per la gestione automatica della classe di archiviazione dei dati del bucket.
      2. Per abilitare lo spazio dei nomi gerarchico, nella sezione Ottimizza l'archiviazione per i workload con uso intensivo dei dati, seleziona Abilita uno spazio dei nomi gerarchico in questo bucket.
         Nota: non puoi abilitare lo spazio dei nomi gerarchico nei bucket esistenti.
   4. Nella sezione Scegli come controllare l'accesso agli oggetti, seleziona se il bucket applica o meno la prevenzione dell'accesso pubblico, e seleziona un metodo di controllo dell'accesso per gli oggetti del bucket.
      Nota: non puoi modificare l'impostazione Impedisci l'accesso pubblico se questa impostazione viene applicata a un criterio dell'organizzazione.
   5. Nella sezione Scegli come proteggere i dati degli oggetti, segui questi passaggi:
      • Seleziona una delle opzioni in Protezione dei dati che vuoi impostare per il bucket.
        • Per abilitare l'eliminazione temporanea, seleziona la casella di controllo Policy di eliminazione temporanea (per il recupero dei dati) e specifica il numero di giorni per cui vuoi conservare gli oggetti dopo l'eliminazione.
        • Per impostare il controllo delle versioni degli oggetti, seleziona la casella di controllo Controllo delle versioni degli oggetti (per il controllo delle versioni), e specifica il numero massimo di versioni per oggetto e il numero di giorni dopo i quali le versioni non correnti scadono.
        • Per abilitare la policy di conservazione su oggetti e bucket, seleziona la casella di controllo Conservazione (per la conformità) e poi:
          • Per abilitare il blocco della conservazione degli oggetti, seleziona la casella di controllo Abilita conservazione degli oggetti.
          • Per abilitare il blocco del bucket, seleziona la casella di controllo Imposta policy di conservazione del bucket e scegli un'unità di tempo e una durata per il periodo di conservazione.
      • Per scegliere come criptare i dati degli oggetti, espandi la la sezione Criptaggio dei dati () e seleziona un metodo di criptaggio dei dati.
4. Fai clic su Crea.

Riga di comando

Crea un bucket Cloud Storage e configurarlo come segue:
• Sostituisci STORAGE_CLASS con la classe di archiviazione che preferisci .
• Sostituisci LOCATION con la località che preferisci (ASIA, EU, o US)
• Sostituisci BUCKET_NAME con un nome del bucket che soddisfi i requisiti di denominazione dei bucket.

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

Installa e inizializza l'SDK Vertex AI Python

Questa sezione presuppone che tu abbia configurato un ambiente di sviluppo Python, o che tu stia utilizzando Colab (o qualsiasi altro runtime adatto che lo abbia configurato per te).

(Facoltativo) Configura un ambiente virtuale

Ti consigliamo inoltre di configurare un ambiente virtuale per isolare le dipendenze.

Installazione

Per ridurre al minimo l'insieme di dipendenze da installare, abbiamo separato le dipendenze in:

• agent_engines: l'insieme di pacchetti richiesti per il deployment in Vertex AI Agent Engine.
• adk: l'insieme di pacchetti Agent Development Kit compatibili.
• langchain: l'insieme di pacchetti LangChain e LangGraph compatibili.
• ag2: l'insieme di pacchetti AG2 compatibili.
• llama_index: l'insieme di pacchetti LlamaIndex compatibili.

Quando installi l'SDK Vertex AI Python, puoi specificare le dipendenze richieste (separate da virgole). Per installarle tutte:

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

Per utilizzare Agent2Agent (A2A) su Agent Engine, devi anche installare il pacchetto a2a-sdk:

pip install a2a-sdk>=0.3.4

Autenticazione

Colab

Esegui questo codice:

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

Non occorre alcun intervento.

Shell locale

Esegui questo comando:

gcloud auth application-default login

Importa e inizializza l'SDK

Esegui il seguente codice per importare e inizializzare l'SDK per Vertex AI Agent Engine:

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

dove

• PROJECT_ID è l' Google Cloud ID progetto in cui sviluppi e esegui il deployment degli agenti e
• LOCATION è una delle regioni supportate.

Passaggi successivi

• Sviluppa un agente.
• Risolvi i problemi di configurazione di un ambiente.
• Richiedi assistenza.