Configurare l'ambiente

Prima di utilizzare Vertex AI Agent Engine, devi assicurarti che il tuo ambiente sia configurato. Devi disporre di 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 l'agent-starter-pack.

Configura il progetto Google Cloud

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

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.

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

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

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

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

Ottenere i ruoli richiesti

Per ottenere le autorizzazioni necessarie per utilizzare Vertex AI Agent Engine, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

• Utente Vertex AI (roles/aiplatform.user)
• Amministratore spazio di archiviazione (roles/storage.admin)

Per ulteriori informazioni 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.

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

Gli agenti di cui esegui il deployment su Vertex AI Agent Engine vengono eseguiti utilizzando account di servizio come identità.

Hai due opzioni per il account di servizio:

• Agente di servizio predefinito:per impostazione predefinita, gli agenti utilizzano l'agente di servizio AI Platform Reasoning Engine. Questo account di servizio gestito da Google ha il ruolo Vertex AI Reasoning Engine Service Agent (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.

Utilizzo dell'agente di servizio predefinito

Per impostazione predefinita, viene utilizzato l'agente di servizio del motore di ragionamento di AI Platform. Puoi visualizzare l'elenco completo delle autorizzazioni predefinite nella documentazione 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 di modifica e poi sul pulsante di salvataggio.

Generare manualmente l'agente di servizio predefinito

Sebbene l'agente di servizio Reasoning Engine venga sottoposto a provisioning automatico durante il deployment di Vertex AI Agent Engine, potrebbero verificarsi scenari in cui è necessario generarlo manualmente in anticipo. Ciò è particolarmente importante quando devi concedere ruoli specifici all'agente di servizio per garantire che la procedura 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 Reasoning Engine 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 accesso.

   Vai a IAM

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

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

5. Fai clic sul pulsante Salva.

Utilizzo di un 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. Vedi Creare service account.

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

3. Concedi all'account di servizio tutti gli altri ruoli richiesti dal codice 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, vedi 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 si trova il account di servizio sia nel progetto in cui viene eseguito il deployment dell'agente.

1. Policy dell'organizzazione Disabilita l'utilizzo dei account di servizio tra i progetti:nel progetto in cui si trova il account di servizio, assicurati che la policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage NON sia applicata. Per ulteriori dettagli, consulta Disabilita l'applicazione dell'utilizzo dei account di servizio tra i progetti.

2. Concedi le autorizzazioni all'agente di servizio Vertex AI:nel progetto in cui si trova l'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 verrà eseguito il deployment dell'agente.

3. Concedi le autorizzazioni al service account personalizzato:nel progetto in cui intendi eseguire il deployment dell'agente, concedi i ruoli necessari al account di servizio personalizzato, come descritto in Utilizzo di un service account personalizzato. In genere, questo include il ruolo Vertex AI User (roles/aiplatform.user) e qualsiasi altro ruolo richiesto dal codice dell'agente.

Crea un bucket Cloud Storage

Vertex AI Agent Engine esegue il staging degli 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 per 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 creare 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 bucket Cloud Storage.
1. In the Google Cloud console, go to the Cloud Storage Buckets page.

   Go to Buckets

2. Click Create.
3. 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.
4. Click Create.

Installare e inizializzare 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) Configurare 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 suddiviso le dipendenze in:

• agent_engines: l'insieme di pacchetti richiesti per il deployment su Vertex AI Agent Engine.
• adk: l'insieme di pacchetti Agent Development Kit compatibili.
• langchain: il set di pacchetti LangChain e LangGraph compatibili.
• ag2: il set 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 installarli tutti:

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

Autenticazione

Colab

Esegui questo codice:

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

Non occorre alcun intervento.

Local Shell

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:

import vertexai
from vertexai import agent_engines

vertexai.init(
    project="PROJECT_ID",
    location="LOCATION",
    staging_bucket="gs://BUCKET_NAME",
)

dove

• PROJECT_ID è l' Google Cloud ID progetto in cui svilupperai e implementerai gli agenti,
• LOCATION è una delle regioni supportate e
• BUCKET_NAME è il nome del bucket Cloud Storage per lo staging degli artefatti durante il deployment degli agenti.

Passaggi successivi

• Sviluppare un agente.
• Risolvi i problemi di configurazione di un ambiente.
• Richiedere assistenza.