Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Gestire l'accesso per gli agenti di cui è stato eseguito il deployment

La gestione dell'accesso per gli agenti di cui è stato eseguito il deployment in Gemini Enterprise Agent Platform prevede la configurazione dell'autenticazione e dell'autorizzazione sia per l'agente che accede alle risorse esterne sia per i client esterni che accedono all'agente. Questo documento descrive i metodi di autenticazione disponibili, tra cui l'identità dell'agente, i service account, le chiavi API e i client OAuth.

Sono disponibili diversi tipi di metodi di autenticazione per diverse modalità di accesso:

Metodo di autenticazione	Caso d'uso	Informazioni su questo metodo di autenticazione
Agent Identity (anteprima)	Accedi alle origini dati direttamente da un agente.	Un agente di cui è stato eseguito il deployment con l'identità dell'agente può accedere alle risorse in base alle autorizzazioni IAM che concedi all'agente.
Service account	Accedi alle origini dati direttamente da un agente.	Gli agenti di cui è stato eseguito il deployment hanno accesso a tutte le risorse a cui il loro service account è autorizzato ad accedere.
Chiavi API	Invia richieste agli endpoint utilizzando le chiavi API dall'interno di un agente.	Prima di utilizzare questo metodo di autenticazione, verifica che l'API che vuoi utilizzare supporti le chiavi API.
ID client OAuth	Gestire gli account utente, la registrazione, l'accesso o l'autorizzazione per gli utenti finali dell'agente.	Richiede che l'agente richieda e riceva il consenso dell'utente.

Agent Identity

Se hai utilizzato l'identità dell'agente per configurare l'identità e le autorizzazioni per il tuo agente, consulta Utilizza l'identità dell'agente con Agent Runtime per informazioni su come gestire controllo dell'accesso alle risorse.

Service account

Se hai utilizzato i service account per configurare l'identità e le autorizzazioni per il tuo agente, gli agenti di cui esegui il deployment su Agent Runtime vengono eseguiti utilizzando l'AI Platform Reasoning Engine Service Agent o il tuo account di servizio personalizzato.

AI Platform Reasoning Engine Service Agent

Il account di servizio AI Platform Reasoning Engine Service Agent utilizza il formato service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

Il account di servizio ha un ruolo Gemini Enterprise Agent Platform Reasoning Engine Service Agent (roles/aiplatform.reasoningEngineServiceAgent) 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.

Elenca i ruoli di un agente di cui è stato eseguito il deployment

Console

Vai alla pagina IAM.

Vai a IAM
Seleziona il progetto corrispondente al tuo progetto Google Cloud .
Trova l'entità che corrisponde al service account utilizzato come identità dell'agente.
I ruoli dell'agente di cui è stato eseguito il deployment sono elencati nella colonna Ruolo.

gcloud

Innanzitutto, installa e inizializza l'interfaccia a riga di comando gcloud. Quindi esegui questo comando:

gcloud projects get-iam-policy PROJECT_ID_OR_NUMBER \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:PRINCIPAL" \
  --format="value(bindings.role)"

dove

PROJECT_ID_OR_NUMBER è l'ID o il numero del progetto.
PRINCIPAL si basa sul service account utilizzato durante il deployment dell'agente su Runtime.

Per maggiori dettagli, consulta la documentazione di IAM e il riferimento dell'interfaccia a riga di comando.

Python

Innanzitutto, installa la libreria client eseguendo questo comando:

pip install google-api-python-client

Quindi autenticati ed esegui il comando seguente per elencare i ruoli di un agente di cui è stato eseguito il deployment:

from google.cloud import resourcemanager_v3
from google.iam.v1 import iam_policy_pb2

project_id = "PROJECT_ID"
principal = "PRINCIPAL"

crm_service = resourcemanager_v3.ProjectsClient()
policy = crm_service.get_iam_policy(iam_policy_pb2.GetIamPolicyRequest(
    resource=f"projects/{project_id}"
))
for binding in policy.bindings:
    for member in binding.members:
        if principal in member:
            print(binding.role)

Dove PRINCIPAL si basa sul service account utilizzato durante il deployment dell'agente su Runtime.

Concedi i ruoli per un agente di cui è stato eseguito il deployment

Console (consigliato)

Vai alla pagina IAM.

Vai a IAM
Seleziona il progetto corrispondente al tuo progetto Google Cloud .
Trova l'entità che corrisponde al service account utilizzato come identità dell'agente.
Aggiungi i ruoli richiesti all'entità facendo clic sul pulsante di modifica, aggiungendo i ruoli e poi facendo clic sul pulsante Salva.

gcloud

Innanzitutto, installa e inizializza l'interfaccia a riga di comando gcloud. Quindi esegui questo comando:

gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

dove

PRINCIPAL si basa sul service account utilizzato durante il deployment dell'agente su Runtime.
ROLE_NAME è il nome del ruolo che vuoi concedere. Per un elenco dei ruoli predefiniti, consulta Informazioni sui ruoli.

Per maggiori dettagli, consulta la documentazione di IAM e il riferimento dell'interfaccia a riga di comando.

Python

Non è consigliabile scrivere il proprio codice Python per concedere o revocare i ruoli per gli agenti di cui è stato eseguito il deployment. Ti consigliamo invece di utilizzare la console Google Cloud o gcloud per le operazioni una tantum o Terraform per gestire controllo dell'accesso IAM in modo programmatico. Se vuoi o devi farlo in Python, consulta la documentazione della libreria client IAM.

Revoca i ruoli di un agente di cui è stato eseguito il deployment

Console (consigliato)

Vai alla pagina IAM.

Vai a IAM
Seleziona il progetto corrispondente al tuo progetto Google Cloud .
Trova l'entità che corrisponde al service account utilizzato come identità dell'agente.
Revoca i ruoli dall'entità facendo clic sul pulsante di modifica, rimuovendo i ruoli corrispondenti e facendo clic sul pulsante Salva.

gcloud

Innanzitutto, installa e inizializza l'interfaccia a riga di comando gcloud. Quindi esegui questo comando:

gcloud projects remove-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE_NAME

dove

PRINCIPAL si basa sul service account utilizzato durante il deployment dell'agente su Runtime.
ROLE_NAME è il nome del ruolo che vuoi revocare. Per un elenco dei ruoli predefiniti, consulta Informazioni sui ruoli.

Per maggiori dettagli, consulta la documentazione di IAM e il riferimento dell'interfaccia a riga di comando.

Python

Chiavi API

Le chiavi API utilizzano i secret, che contengono una o più versioni dei secret, insieme a metadati come etichette e informazioni di replica. Il payload effettivo di un secret è archiviato in una versione del secret. I secret vengono gestiti (tramite Secret Manager) a livello di progetto e possono essere condivisi tra gli agenti di cui è stato eseguito il deployment. Per elencare i secret corrispondenti a un agente in Secret Manager, puoi aggiungere etichette e utilizzarle per il filtro.

Crea un secret

Console

Vai alla pagina Secret Manager.

Vai a Secret Manager
Nella pagina Secret Manager, fai clic su Crea secret.
Nel campo Nome, inserisci un nome per il secret (ad esempio my-secret).
(Facoltativo) Per aggiungere anche una versione del secret durante la creazione del secret iniziale, inserisci un valore per il secret nel campo Valore secret, ad esempio abcd1234.
Vai a Etichette e poi fai clic su Aggiungi etichetta.
Inserisci una chiave e il valore corrispondente per creare un'etichetta.
Fai clic su Crea secret.

gcloud

Innanzitutto, installa e inizializza l'interfaccia a riga di comando gcloud. Quindi esegui questi comandi:

gcloud secrets create SECRET_ID --replication-policy="automatic"
gcloud secrets versions add SECRET_ID --data-file="FILE_PATH"

dove

SECRET_ID è l'ID del secret o l'identificatore completo del secret.
FILE_PATH è il percorso completo (incluso il nome file) del file contenente i dettagli della versione.

Per maggiori dettagli, consulta la documentazione di Secret Manager per la creazione di un secret e di una versione del secret oppure il riferimento dell'interfaccia a riga di comando per la creazione di un secret e di una versione del secret, rispettivamente.

Python

Innanzitutto, installa la libreria client eseguendo questo comando:

pip install google-cloud-secret-manager

Quindi autenticati ed esegui il comando seguente:

from google.cloud import secretmanager
import google_crc32c

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "SECRET_ID",
    "secret": {  # google.cloud.secretmanager_v1.types.Secret
        # Required. The replication policy cannot be changed after the Secret has been created.
        "replication": {"automatic": {}},
        # Optional. Labels to associate with the secret.
        "labels": {"type": "api_key", "provider": "anthropic"},
        # Optional. The secret's time-to-live in seconds with format (e.g.,
        # "900s" for 15 minutes). If specified, the secret versions will be
        # automatically deleted upon reaching the end of the TTL period.
        "ttl": "TTL",
    },
})

anthropic_api_key = "API_KEY"  # The secret to be stored.
payload_bytes = anthropic_api_key.encode("UTF-8")
# Optional. Calculate payload checksum.
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

version = client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),  # Optional.
    },
})
print(f"Added secret version: {version.name}")

Ottieni un secret

Console

Vai alla pagina Secret Manager.

Vai a Secret Manager
Nella pagina Secret Manager, fai clic sul nome di un secret da descrivere.
La pagina Dettagli secret elenca le informazioni sul secret.

gcloud

Innanzitutto, installa e inizializza l'interfaccia a riga di comando gcloud. Quindi esegui questo comando:

gcloud secrets versions describe VERSION_ID --secret=SECRET_ID

dove

VERSION_ID è l'ID della versione del secret;
SECRET_ID è l'ID del secret o l'identificatore completo del secret.

Per maggiori dettagli, consulta la documentazione di Secret Manager o il riferimento dell'interfaccia a riga di comando.

Python

Innanzitutto, installa la libreria client eseguendo questo comando:

pip install google-cloud-secret-manager

Quindi autenticati ed esegui il comando seguente:

from google.cloud import secretmanager

client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.get_secret(request={"name": name})

Elenco secret

Console

Vai alla pagina Secret Manager.

Vai a Secret Manager
Nella tabella Secret, fai clic sul campo Filtro.
Scegli una proprietà filtro e il valore corrispondente, ad esempio Location:asia-east1.
La tabella viene filtrata automaticamente in base ai valori inseriti.
(Facoltativo) Per filtrare le versioni dei secret: seleziona un secret per accedere alle sue versioni, quindi utilizza l'opzione Filtro nella tabella Versioni.

gcloud

Innanzitutto, installa e inizializza l'interfaccia a riga di comando gcloud.

Per elencare tutti i secret di un progetto, esegui questo comando:

gcloud secrets list --filter="FILTER"

dove FILTER è una stringa (ad es. name:asecret OR name:bsecret) o espressioni regolari (ad es. name ~ "secret_ab.*").

Per elencare tutte le versioni di un secret, esegui questo comando:

gcloud secrets versions list SECRET_ID

dove SECRET_ID è l'ID del secret o l'identificatore completo del secret.

Per maggiori dettagli, consulta la documentazione di Secret Manager per filtrare i secret ed elencare le versioni dei secret o il riferimento dell'interfaccia a riga di comando per elencare rispettivamente i secret e le versioni dei secret.

Python

Innanzitutto, installa la libreria client eseguendo questo comando:

pip install google-cloud-secret-manager

Quindi autenticati ed esegui il comando seguente:

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
for secret in client.list_secrets(request={
    "parent": "projects/PROJECT_ID",
    "filter": "FILTER", # e.g. "labels.provider=anthropic"
}):
    print(f"Found secret: {secret.name}")

Aggiorna un secret

Console

Vai alla pagina Secret Manager.

Vai a Secret Manager
Nella pagina Secret Manager, fai clic sulla casella di controllo accanto al nome del secret.
Se il riquadro informazioni è chiuso, fai clic su Mostra riquadro informazioni per visualizzarlo.
Nel riquadro Informazioni, seleziona la scheda Etichette.
Fai clic su Aggiungi etichetta e inserisci una chiave e un valore per l'etichetta.
Fai clic su Salva.

gcloud

Innanzitutto, installa e inizializza l'interfaccia a riga di comando gcloud. Quindi esegui questo comando:

gcloud secrets update SECRET_ID --update-labels=KEY=VALUE

dove

SECRET_ID è l'ID del secret o l'identificatore completo del secret,
KEY è la chiave dell'etichetta e
VALUE è il valore corrispondente dell'etichetta.

Per maggiori dettagli, consulta la documentazione di Secret Manager o il riferimento dell'interfaccia a riga di comando.

Python

Innanzitutto, installa la libreria client eseguendo questo comando:

pip install google-cloud-secret-manager

Quindi autenticati ed esegui il comando seguente:

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
response = client.update_secret(request={
    "secret": {
        "name": name,
        "labels": {"type": "api_key", "provider": "anthropic"}, # updated labels
    },
    "update_mask": {"paths": ["labels"]},
})
print(f"Updated secret: {response.name}")

Elimina un secret

Console

Vai alla pagina Secret Manager.

Vai a Secret Manager
Nella pagina Secret Manager, nella colonna Azioni del secret, fai clic su Mostra altro.
Nel menu, seleziona Elimina.
Nella finestra di dialogo Elimina secret, inserisci il nome del secret.
Fai clic sul pulsante Elimina secret.

gcloud

Innanzitutto, installa e inizializza l'interfaccia a riga di comando gcloud.

Per eliminare una versione del secret, esegui questo comando:

gcloud secrets versions destroy VERSION_ID --secret=SECRET_ID

dove

VERSION_ID è il nome della risorsa della versione del secret.
SECRET_ID è l'ID del secret o l'identificatore completo del secret.

Per eliminare un secret e tutte le sue versioni, esegui questo comando:

gcloud secrets delete SECRET_ID

dove SECRET_ID è l'ID del secret o l'identificatore completo del secret

Per maggiori dettagli, consulta la documentazione di Secret Manager per eliminare un secret e eliminare una versione del secret o il riferimento dell'interfaccia a riga di comando per eliminare un secret ed eliminare una versione del secret.

Python

Innanzitutto, installa la libreria client eseguendo questo comando:

pip install google-cloud-secret-manager

Quindi autenticati ed esegui il comando seguente:

from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = client.secret_path("PROJECT_ID", "SECRET_ID")
client.delete_secret(request={"name": name})

Client e credenziali OAuth

Un ID client viene utilizzato per identificare un singolo agente nei server OAuth di Google. Se l'agente viene eseguito su più piattaforme, ogni piattaforma deve avere il proprio ID client. In linea generale, per integrare un agente basato su OAuth, procedi nel seguente modo:

Crea un client e una credenziale OAuth.
Archivia l'ID client e il secret in Secret Manager. (Consulta Crea un secret).
Accedi al secret nel tuo agente durante lo sviluppo.

Crea una credenziale client OAuth

Nella console Google Cloud , vai alla pagina Google Auth Platform > Client.

Vai a Google Auth Platform > Client
(Se necessario) Se lo schermo mostra "Google Auth Platform non ancora configurata", fai clic su Inizia e compila le Configurazioni del progetto. (Possono essere aggiornate in un secondo momento). Per informazioni dettagliate sull'idoneità alla produzione, consulta la pagina Conformità alle norme OAuth 2.0.
Fai clic su Crea client.
Imposta Tipo di applicazione su Web application.
Imposta il nome del client OAuth su OAUTH_CLIENT_DISPLAY_NAME.
In URI di reindirizzamento autorizzati, aggiungi l'URI per REDIRECT_URI.
In Client secret, fai clic sul pulsante "Scarica JSON". Viene scaricato un file client_secret.json con i seguenti contenuti:

{'web': {
    'client_id': "CLIENT_ID",
    'client_secret': "CLIENT_SECRET",
    'project_id': "PROJECT_ID",
    'redirect_uris': [REDIRECT_URIs],
    'auth_uri': 'https://accounts.google.com/o/oauth2/auth',
    'token_uri': 'https://www.googleapis.com/oauth2/v3/token',
    'auth_provider_x509_cert_url': 'https://www.googleapis.com/oauth2/v1/certs',
    'javascript_origins': "JAVASCRIPT_ORIGINS",  # Optional.
}}

Archivia l'ID client e il secret in Secret Manager, ad esempio:

from google.cloud import secretmanager
import google_crc32c
import json

client = secretmanager.SecretManagerServiceClient()
secret = client.create_secret(request={
    "parent": "projects/PROJECT_ID",
    "secret_id": "OAUTH_SECRET_ID", # e.g. "oauth-client-demo"
    "secret": {
        "labels": {"type": "oauth_client"},
        "replication": {"automatic": {}},
    },
})

payload_bytes = json.dumps(cred).encode("UTF-8")
crc32c = google_crc32c.Checksum()
crc32c.update(payload_bytes)

client.add_secret_version(request={
    "parent": secret.name,
    "payload": {
        "data": payload_bytes,
        "data_crc32c": int(crc32c.hexdigest(), 16),
    },
})

Elenca client OAuth

Nella console Google Cloud , vai alla pagina Google Auth Platform > Client, che elenca le credenziali client OAuth.

Vai a Google Auth Platform > Client

Elimina un client OAuth

Nella console Google Cloud , vai alla pagina Google Auth Platform > Client.

Vai a Google Auth Platform > Client
Seleziona le credenziali client OAuth da eliminare e fai clic su Elimina.

Chiavi di crittografia gestite dal cliente (CMEK)

Per impostazione predefinita, Google Cloud cripta automaticamente i dati at-rest utilizzando chiavi di crittografia gestite da Google. Se hai requisiti normativi o di conformità specifici relativi alle chiavi che proteggono i tuoi dati, puoi utilizzare le chiavi di crittografia gestite dal cliente (CMEK) per gli agenti di cui hai eseguito il deployment.

Consulta la documentazione relativa alle CMEK per Gemini Enterprise Agent Platform per i requisiti generali e le indicazioni sull'utilizzo delle CMEK con Gemini Enterprise Agent Platform, tra cui:

Configurazione del progetto (fatturazione e API abilitate)
Creazione di chiavi automatizzate e chiavi
Concessioni di autorizzazioni obbligatorie

Per abilitare CMEK per l'agente, devi specificare encryption_spec con la chiave Cloud Key Management Service durante la creazione di un'istanza della piattaforma dell'agente. Per esempi di codice, consulta Configura le chiavi di crittografia gestite dal cliente.

Limitazioni

Quando utilizzi CMEK con Agent Runtime, si applicano le seguenti limitazioni:

Non sono consentite chiavi multiregionali: sono supportate solo chiavi a regione singola. La regione delle chiavi automatizzate e della chiave deve essere la stessa dell'istanza di Agent Platform.
La chiave di crittografia non può essere aggiornata per le istanze CMEK: una volta eseguito il deployment di un agente con una chiave CMEK, la chiave di crittografia non può essere modificata per quel deployment. Per utilizzare una nuova chiave, devi eseguire il deployment di una nuova istanza di Agent Platform.
Alcuni metadati e dati operativi non sono criptati con la tua chiave: CMEK cripta i dati principali dell'agente at-rest. Tuttavia, alcuni metadati e dati operativi di runtime non sono criptati con la tua chiave. Vengono invece criptati utilizzando la crittografia predefinita di Google. È incluso quanto segue:
- Metadati dell'agente:
  - Nomi visualizzati
  - Descrizioni
- Dati operativi di runtime:
  - Email del service account
  - Nomi dei metodi della classe di oggetti dell'agente
  - Variabili di ambiente

Controlli di servizio VPC (VPC-SC)

Agent Runtime supporta i Controlli di servizio VPC per rafforzare la sicurezza dei dati e mitigare i rischi di esfiltrazione di dati.

Quando i Controlli di servizio VPC sono configurati, l'agente di cui è stato eseguito il deployment mantiene l'accesso sicuro alle API di Google e ai servizi, come l'API BigQuery, l'API Cloud SQL Admin e l'API Agent Platform, verificando il funzionamento senza interruzioni all'interno del perimetro definito. In particolare, i Controlli di servizio VPC bloccano efficacemente tutti gli accessi a internet pubblici, limitando lo spostamento dei dati ai confini della rete autorizzata e migliorando in modo significativo la security posture della tua azienda.

Le opzioni di deployment disponibili sono elencate in Esegui il deployment di un agente. A seconda dell'opzione di deployment, è necessario configurare le seguenti regole del traffico in entrata:

Per i deployment basati su pickle, è necessario l'accesso in entrata al servizio storage.googleapis.com e al servizio artifactregistry.googleapis.com.
Per i deployment basati sull'origine, su Git e BYOD (Bring Your Own Dockerfile), è richiesto l'accesso al servizio artifactregistry.googleapis.com.
Per i deployment BYOC (Bring Your Own Container), non è richiesta alcuna regola aggiuntiva per il traffico in entrata.

Limitazioni

I Controlli di servizio VPC non sono supportati con Agent Gateway.

Tuttavia, puoi utilizzare i vincoli delle policy dell'organizzazione personalizzate per limitare i gateway che possono essere associati ai tuoi agenti. Per saperne di più, consulta Instrada il traffico tramite Agent Gateway.

Gestire l'accesso per gli agenti di cui è stato eseguito il deployment Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Agent Identity

Service account

AI Platform Reasoning Engine Service Agent

Elenca i ruoli di un agente di cui è stato eseguito il deployment

Console

gcloud

Python

Concedi i ruoli per un agente di cui è stato eseguito il deployment

Console (consigliato)

gcloud

Python

Revoca i ruoli di un agente di cui è stato eseguito il deployment

Console (consigliato)

gcloud

Python

Chiavi API

Crea un secret

Console

gcloud

Python

Ottieni un secret

Console

gcloud

Python

Elenco secret

Console

gcloud

Python

Aggiorna un secret

Console

gcloud

Python

Elimina un secret

Console

gcloud

Python

Client e credenziali OAuth

Crea una credenziale client OAuth

Elenca client OAuth

Elimina un client OAuth

Chiavi di crittografia gestite dal cliente (CMEK)

Limitazioni

Controlli di servizio VPC (VPC-SC)

Limitazioni

Gestire l'accesso per gli agenti di cui è stato eseguito il deployment