Configurare l'ambiente

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

Per un esempio di riferimento di Terraform per semplificare la configurazione e il deployment dell'ambiente Agent Engine, ti consigliamo di esplorare agent-starter-pack.

Configurare il progetto Google Cloud

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

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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Vertex AI and Cloud Storage APIs.

   Enable the APIs

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

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Vertex AI and Cloud Storage APIs.

   Enable the APIs

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

Ottieni i ruoli richiesti

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

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

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

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

Configurare le autorizzazioni dell'agente di servizio

Gli agenti di cui esegui il deployment in Agent Engine vengono eseguiti utilizzando l'account di servizio Agente di servizio del motore di ragionamento della piattaforma AI. Questo account ha il ruolo Agente di servizio del motore di ragionamento Vertex AI che concede le autorizzazioni predefinite richieste per gli agenti di cui è stato eseguito il deployment. Puoi visualizzare l'elenco completo delle autorizzazioni predefinite nella documentazione IAM.

Se hai bisogno di autorizzazioni aggiuntive, puoi concedere all'agente di servizio altri ruoli svolgendo i seguenti passaggi:

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à corrispondente a [e-mail].

3. Aggiungi i ruoli richiesti all'entità facendo clic sul pulsante di modifica e poi sul pulsante di salvataggio.

Generare manualmente un agente di servizio

Sebbene il provisioning dell'agente di servizio del motore di ragionamento venga eseguito automaticamente durante il deployment dell'agente Engine, potrebbero verificarsi scenari in cui è necessario generarlo manualmente in precedenza. Questo è particolarmente importante quando devi concedere ruoli specifici all'agente di servizio per assicurarti che la procedura di implementazione disponga delle autorizzazioni necessarie ed evitare potenziali errori di implementazione.

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 Reasoning Engine.

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

   Vai a IAM

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

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

5. Fai clic sul pulsante Salva.

Crea un bucket Cloud Storage

Agent Engine esegue la gestione 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 la creazione di un bucket.

Console Google Cloud

1. In the Google Cloud console, go to the Cloud Storage Buckets page.

   Go to Buckets page

2. Click Create bucket.
3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
   • For Name your bucket, enter a name that meets the bucket naming requirements.
   • For Choose where to store your data, do the following:
     • Select a Location type option.
     • Select a Location option.
   • For Choose a default storage class for your data, select a storage class.
   • For Choose how to control access to objects, select an Access control option.
   • For Advanced settings (optional), specify an encryption method, a retention policy, or bucket labels.
4. Click Create.

Riga di comando

Create a Cloud Storage bucket and configure it as follows:
• Sostituisci STORAGE_CLASS con la classe di archiviazione che preferisci.
• Sostituisci LOCATION con la tua località preferita (ASIA, EU o US)
• Sostituisci BUCKET_NAME con un nome del bucket che soddisfi i requisiti per i nomi dei bucket.

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

Installa e inizializza l'SDK Vertex AI per 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, le abbiamo suddivise in:

• agent_engines: l'insieme di pacchetti necessari per il deployment in Agent Engine.
• langchain: l'insieme di pacchetti LangChain compatibili.
• langgraph: l'insieme di pacchetti LangGraph compatibili.

Quando installi l'SDK Vertex AI per Python, puoi specificare le dipendenze obbligatorie (separate da virgole). Per installarli tutti:

pip install google-cloud-aiplatform[agent_engines,langchain,langgraph]

Autenticazione

Colab

Esegui questo codice:

from google.colab import auth

auth.authenticate_user()

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 Agent Engine:

import vertexai
from vertexai import agent_engines

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

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la tua regione cloud.
• BUCKET_NAME: il tuo Google Cloud bucket.

Passaggi successivi

• Sviluppare un'applicazione.