Configurare l'ambiente

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

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

Configura con Google Cloud

Puoi configurare Google Cloud per Agent Runtime creando un progetto Google Cloud .

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:

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

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Gemini Enterprise Agent Platform, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

Ottieni i ruoli richiesti

Per ottenere le autorizzazioni necessarie per utilizzare Agent Runtime, chiedi all'amministratore di concederti il ruolo IAM Agent Platform User (roles/aiplatform.user) nel 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

Per configurare l'identità e le autorizzazioni, hai a disposizione le seguenti opzioni:

  • Identità agente (consigliata) Utilizza l'identità agente di Identity and Access Management (IAM) per fornire funzionalità di sicurezza e gestione degli accessi quando utilizzi gli agenti su Agent Runtime. L'identità dell'agente è legata a ogni singolo agente. Per impostazione predefinita, gli agenti hanno il ruolo Agent Platform Agent Default Access (roles/aiplatform.agentDefaultAccess), che include solo le autorizzazioni di base per il logging e la chiamata dei modelli a livello di progetto, e il ruolo Agent Platform Agent Context Editor (roles/aiplatform.agentContextEditor), che limita l'accesso di un agente solo alle proprie sessioni, memorie e sandbox.

    Nota: alcune funzionalità accessibili con questo ruolo potrebbero essere in Anteprima

  • Service account: i service account sono condivisi tra gli agenti di cui esegui il deployment in Agent Runtime. Per il account di servizio hai due opzioni:

    • Service agent predefinito: per impostazione predefinita, gli agenti utilizzano l'AI Platform Reasoning Engine Service Agent. Questo account di servizio gestito da Google ha il ruolo Gemini Enterprise Agent Platform 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 un account di servizio personalizzato che gli agenti possono utilizzare. In questo modo, hai un controllo più granulare sulle autorizzazioni concesse agli agenti.

Agent Identity

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 Platform con solo il campo identity_type:

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

Una volta creata l'istanza di Agent Platform con l'identità dell'agente, puoi:

  1. Concedi all'identità dell'agente ruoli aggiuntivi in base alle esigenze del tuo caso d'uso.

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

Default Service Agent

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

Se l'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 service-PROJECT_NUMBER@gcp-sa-aiplatform-re..

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

Genera manualmente l'agente di servizio predefinito

Sebbene l'agente di servizio del motore di ragionamento venga eseguito automaticamente durante il deployment di Agent Runtime, potrebbero esserci 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

  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 service-PROJECT_NUMBER@gcp-sa-aiplatform-re..

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

  5. Fai clic sul pulsante Salva.

Service account 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 Agent Platform User (roles/aiplatform.user).

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

  2. Concedi al account di servizio il ruolo Utente piattaforma agente (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 Service Account User (roles/iam.serviceAccountUser) su questo service account personalizzato.

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

Account di servizio personalizzato tra progetti

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

  1. Policy dell'organizzazione per disattivare l'utilizzo dei account di servizio tra progetti: nel progetto in cui si trova il account di servizio, assicurati che la policy dell'organizzazione iam.disableCrossProjectServiceAccountUsage NON venga applicata. Per saperne di più, consulta Disabilita l'applicazione dell'utilizzo dei account di servizio tra progetti.

  2. Concedi le autorizzazioni all'agente di servizio della piattaforma dell'agente: nel progetto in cui si trova l'account di servizio, concedi il ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator) all'agente di servizio della piattaforma dell'agente (service-RESOURCE_PROJECT_NUMBER@gcp-sa-aiplatform.) 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 Agent Platform User (roles/aiplatform.user) e qualsiasi altro ruolo richiesto dal codice dell'agente.

(Facoltativo) Crea un bucket Cloud Storage

La necessità di un bucket Cloud Storage dipende dal fatto che l'SDK Agent Platform per Python abbia bisogno o meno di un luogo in cui eseguire lo stage del codice dell'agente prima del deployment:

  • Esegui il deployment dai file di origine: l'agente esiste come file. L'SDK Agent Platform 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 Agent Platform per 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, Agent Runtime esegue la gestione temporanea 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 Gemini Enterprise Agent Platform (tu o un account di servizio) abbia l'accesso Storage Admin a questo bucket. Questo è necessario perché l'SDK Agent Platform per Python scrive il tuo 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.

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

ConsoleGoogle Cloud

  1. Nella console Google Cloud , 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 andare al passaggio successivo, fai clic su Continua.
    1. Nella sezione Inizia, segui questi passaggi:
    2. Nella sezione Scegli dove archiviare i tuoi dati, segui questi passaggi:
      1. Seleziona un Tipo di località.
      2. Scegli una località in cui archiviare in modo permanente i dati del bucket dal menu a discesa Tipo di località.
        • Se selezioni il tipo di località a due regioni, puoi anche scegliere di attivare 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 per il 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 dagli 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 workload con uso intensivo dei dati, seleziona Abilita lo spazio dei nomi gerarchico in questo bucket.
    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.
    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, fai clic sulla 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, fai clic sulla casella di controllo Controllo delle versioni degli oggetti 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, fai clic sulla casella di controllo Conservazione (per la conformità), quindi segui questi passaggi:
          • Per abilitare il blocco della conservazione degli oggetti, fai clic sulla casella di controllo Abilita conservazione degli oggetti.
          • Per abilitare Blocco bucket, fai clic sulla casella di controllo Imposta criterio 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 sezione Crittografia dei dati () e seleziona un metodo di crittografia dei dati.
  4. Fai clic su Crea.

Riga di comando

    Crea un bucket Cloud Storage e configuralo come segue: 
    gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

Installa e inizializza l'SDK Agent Platform 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, abbiamo separato le dipendenze in:

  • agent_engines: l'insieme di pacchetti richiesti per il deployment in Agent Runtime.
  • adk: l'insieme di pacchetti Agent Development Kit (ADK) 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 Agent Platform per 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.112.0

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

pip install google-adk[a2a]

Autenticazione

Colab

Esegui questo codice:

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

Nessuna azione richiesta.

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 Runtime:

Google Cloud progetto 

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

(Facoltativo) Bring Your Own Container (BYOC)

Per impostazione predefinita, Agent Runtime crea un container nell'ambito del processo di deployment. Se vuoi creare un container personalizzato per il deployment, segui le istruzioni riportate in questa sezione.

Per eseguire il deployment dell'agente con un container personalizzato, completa le seguenti attività di alto livello:

  1. Crea un'immagine container ed eseguine il push in Artifact Registry.
  2. Configura l'identità e le autorizzazioni per l'agente.
  3. Concedi il ruolo Artifact Registry Reader al service agent predefinito di Agent Runtime.

Crea ed esegui il push dell'immagine container

Per creare ed eseguire il push dell'immagine container, segui le istruzioni riportate in Crea ed esegui il push di un'immagine Docker con Cloud Build.

Configura l'identità e le autorizzazioni per Agent Runtime

L'agente di servizio predefinito di Agent Runtime è necessario per importare i container dal repository Artifact Registry.

Per impostazione predefinita, l'agente di servizio viene generato automaticamente nel progetto. Se non esiste, segui le istruzioni riportate in Configura l'identità e le autorizzazioni per l'agente per crearlo e configurarlo.

Concedi il ruolo Artifact Registry Reader

Concedi il ruolo Artifact Registry Reader (roles/artifactregistry.reader) al service agent predefinito (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.).

Esegui questo comando per concedere il ruolo richiesto all'agente di servizio predefinito:

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform-re." \
  --role="roles/artifactregistry.reader"

(Facoltativo) Concedi l'autorizzazione tra progetti

L'autorizzazione tra progetti è necessaria se le immagini container sono archiviate in un repository Artifact Registry in un progetto Google Cloud diverso da quello in cui viene eseguito il deployment degli agenti.

In questo caso, concedi il ruolo Lettore Artifact Registry al service agent della piattaforma agent (service-PROJECT_NUMBER@gcp-sa-aiplatform.) nel progetto del repository Artifact Registry.

gcloud projects add-iam-policy-binding AR_REPO_PROJECT_NUMBER \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform." \
  --role="roles/artifactregistry.reader"

Passaggi successivi

Panoramica

Scopri come creare un agente utilizzando il runtime di Agent Platform.

Risoluzione dei problemi

Scopri come risolvere gli errori comuni durante la creazione di agenti personalizzati.

Risorsa

Trova risorse e assistenza per Google Agent Platform.