Questa pagina descrive come utilizzare Identity and Access Management (IAM) per gestire l'accesso alle risorse di Gemini Enterprise Agent Platform. Per gestire l'accesso alle istanze di Vertex AI Workbench, consulta Controllo dell'accesso alle istanze di Vertex AI Workbench.
Panoramica
Agent Platform utilizza IAM per gestire l'accesso alle risorse. Quando pianifichi controllo dell'accesso per le tue risorse, considera quanto segue:
Puoi gestire l'accesso a livello di progetto o di risorsa. L'accesso a livello di progetto si applica a tutte le risorse del progetto. L'accesso a una risorsa specifica si applica solo a quella risorsa. Consulta Accesso a livello di progetto e a livello di risorsa.
Concedi l'accesso assegnando ruoli IAM alle entità. Sono disponibili ruoli predefiniti per semplificare la configurazione dell'accesso, ma sono consigliati i ruoli personalizzati perché li crei tu, quindi puoi limitare il loro accesso solo alle autorizzazioni necessarie. Consulta Ruoli IAM.
Ruoli IAM
Esistono diversi tipi di ruoli IAM che possono essere utilizzati in Agent Platform:
I ruoli personalizzati ti consentono di scegliere un insieme specifico di autorizzazioni, creare un ruolo personalizzato con queste autorizzazioni e concedere il ruolo agli utenti della tua organizzazione.
I ruoli predefiniti ti consentono di concedere un insieme di autorizzazioni correlate alle risorse della piattaforma dell'agente a livello di progetto.
I ruoli di base (proprietario, editor e visualizzatore) forniscono ilcontrollo dell'accessoo alle risorse di Agent Platform a livello di progetto e sono comuni a tutti i servizi Google Cloud .
Per aggiungere, aggiornare o rimuovere questi ruoli nel tuo progetto Agent Platform, consulta la documentazione su concessione, modifica e revoca dell'accesso.
Ruoli personalizzati
I ruoli personalizzati ti consentono di scegliere un insieme specifico di autorizzazioni, creare il tuo ruolo con queste autorizzazioni e concederlo agli utenti della tua organizzazione. Per saperne di più, consulta Informazioni sui ruoli IAM personalizzati.
Utilizzare i ruoli personalizzati per concedere autorizzazioni con privilegio minimo
I ruoli predefiniti spesso contengono più autorizzazioni di quelle necessarie. Puoi creare ruoli personalizzati per concedere alle tue entità solo le autorizzazioni specifiche richieste.
Ad esempio, puoi creare un ruolo personalizzato con l'autorizzazione
aiplatform.endpoints.predict e poi assegnare il ruolo a
uaccount di serviziont su un endpoint. In questo modo, il account di servizio ha la possibilità di chiamare l'endpoint per le previsioni, ma non di controllarlo.
Ruoli predefiniti per Agent Platform
| Role | Permissions |
|---|---|
Vertex AI Administrator( Grants full access to all resources in Vertex AI |
|
Aiplatform Editor( Editor role for aiplatform |
|
Vertex AI Platform Express User Beta( Grants user access to Vertex AI Express |
|
Vertex AI User( Grants access to use all resource in Vertex AI |
|
Vertex AI Viewer( Grants access to view all resource in Vertex AI |
|
Colab Enterprise Admin( Admin role of using colab enterprise. |
|
Colab Enterprise User( User role of using colab enterprise. |
|
Vertex AI Feature Store EntityType owner( Provides full access to all permissions for a particular entity type resource. Lowest-level resources where you can grant this role:
|
|
Vertex AI Platform Express Admin Beta( Grants admin access to Vertex AI Express |
|
Vertex AI Feature Store Admin( Grants full access to all resources in Vertex AI Feature Store Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store Data Viewer( This role provides permissions to read Feature data. Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store Data Writer( This role provides permissions to read and write Feature data. Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store Instance Creator( Administrator of Featurestore resources, but not the child resources under Featurestores. Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store Resource Viewer( Viewer of all resources in Vertex AI Feature Store but cannot make changes. Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store User Beta( Deprecated. Use featurestoreAdmin instead. |
|
Vertex AI Agent Engine Memory Editor Role( Grants edit access to Memory for Agent Engine. |
|
Vertex AI Agent Engine Memory User Role( Grants full user access to Memory for Agent Engine. |
|
Vertex AI Agent Engine Memory Viewer Role( Grants viewer access to Memory for Agent Engine. |
|
Vertex AI Migration Service User( Grants access to use migration service in Vertex AI |
|
Notebook Executor User Beta( Grants users full access to schedules and notebook execution jobs. |
|
Notebook Runtime Admin( Grants full access to all runtime templates and runtimes in Notebook Service. |
|
Notebook Runtime User( Grants users permissions to create runtime resources using a runtime template and manage the runtime resources they created. |
|
Vertex AI Platform Provisioned Throughput Admin Beta( Grants access to use all resources related to Vertex AI Provisioned Throughput |
|
Vertex AI Platform Publisher Provisioned Throughput Admin Beta( Grants Publisher access to use all resources related to Vertex AI Provisioned Throughput Orders |
|
Vertex AI Platform Publisher Provisioned Throughput Viewer Beta( Grants Publisher access to view all resources related to Vertex AI Provisioned Throughput Orders |
|
Vertex AI Agent Engine Session Editor Role( Grants edit access to Session for Agent Engine. |
|
Vertex AI Agent Engine Session User Role( Grants full user access to Session for Agent Engine. |
|
Vertex AI Agent Engine Session Viewer Role( Grants viewer access to Session for Agent Engine. |
|
Vertex AI Tensorboard Web App User Beta( Grants access to the Vertex AI TensorBoard web app. |
|
Service agent roles
Service agent roles should only be granted to service agents.
| Role | Permissions |
|---|---|
Vertex AI Agent Sandbox Service Agent( Vertex AI Service Agent used to access Agent Sandbox managed resources in consumer project with restricted permissions. |
|
Vertex AI Batch Prediction Service Agent( Vertex AI Batch Prediction Service Agent for serving batch prediction requests. |
|
Vertex AI Colab Service Agent( Gives Vertex AI Colab the proper permissions to function. |
|
Vertex AI Custom Code Service Agent( Gives Vertex AI Custom Code the proper permissions. |
|
Vertex AI Extension Custom Code Service Agent( Gives Vertex AI Extension that executes custom code the permissions it needs to function. |
|
Vertex AI Extension Service Agent( Gives Vertex AI Extension the permissions it needs to function. |
|
Vertex AI Model Monitoring Service Agent( Gives Vertex AI Model Monitoring the permissions it needs to function. |
|
Vertex AI Notebook Service Agent( Vertex AI Service Agent used to run Notebook managed resources in user project with restricted permissions. |
|
Vertex AI Online Prediction Service Agent( Gives Vertex AI Online Prediction the permissions it needs to function. |
|
Vertex AI RAG Data Service Agent( Vertex AI Service Agent used by Vertex RAG to access user imported data, Vertex AI, Document AI processors, and Vector Search in the project |
|
Vertex AI Rapid Eval Service Agent( Vertex AI Service Agent used by GenAI Rapid Evaluation Service to access publisher model endpoints in the user project |
|
Vertex AI Reasoning Engine Service Agent( Gives Vertex AI Reasoning Engine the proper permissions to function. The aiplatform.reasoningEngines.create IAM permission implies read access to the GCS objects of the consumer project through this service agent. |
|
Vertex AI Service Agent( Gives Vertex AI the permissions it needs to function. |
|
Vertex AI Telemetry Service Agent( Allows Vertex AI Telemetry Service Agent to access telemetry data. |
|
Vertex AI Tuning Service Agent( Vertex AI Service Agent used for tuning in user project. |
|
Ruoli di base
I Google Cloud ruoli di base meno recenti sono comuni a tutti i servizi Google Cloud . Questi ruoli sono Proprietario, Editor e Visualizzatore.
Accesso a livello di progetto e a livello di risorsa
Puoi gestire l'accesso a livello di progetto o di risorsa. Potresti anche avere la possibilità di gestire l'accesso a livello di cartella o organizzazione.
Per la maggior parte delle risorse della piattaforma dell'agente, l'accesso può essere controllato solo da progetto, cartella e organizzazione. L'accesso alle singole risorse può essere concesso solo per tipi di risorse specifici, ad esempio un endpoint o un archivio di caratteristiche.
Gli utenti condividono il controllo di tutte le risorse a cui possono accedere. Ad esempio, se un utente registra un modello, tutti gli altri utenti autorizzati del progetto possono accedere, modificare ed eliminare il modello.
Per concedere l'accesso alle risorse a livello di progetto, assegna uno o più ruoli a un principal (utente, gruppo o service account).
Per le risorse della piattaforma dell'agente che ti consentono di concedere l'accesso a livello di risorsa, imposta una policy IAM sulla risorsa. La policy definisce quali ruoli vengono assegnati a quali entità.
L'impostazione di una policy a livello di risorsa non influisce sulle policy a livello di progetto. Una risorsa eredita tutte le policy dalla sua ascendenza. Puoi utilizzare questi due livelli di granularità per personalizzare le autorizzazioni. Ad esempio, puoi concedere agli utenti le autorizzazioni di lettura a livello di progetto in modo che possano leggere tutte le risorse del progetto, quindi puoi concedere agli utenti le autorizzazioni di scrittura per risorsa (a livello di risorsa).
Non tutti i ruoli e le risorse predefiniti di Agent Platform supportano i criteri a livello di risorsa. Per identificare quali ruoli possono essere utilizzati su quali risorse, consulta la tabella dei ruoli predefiniti.
Risorse supportate
Agent Platform supporta le risorse featurestore e entity type di Vertex AI Feature Store. Per ulteriori informazioni, consulta Controllare l'accesso alle risorse di Vertex AI Feature Store.
Dopo aver concesso o revocato l'accesso a una risorsa, la propagazione delle modifiche richiede tempo. Per saperne di più, consulta la sezione Propagazione della modifica di accesso.
Risorse, service account e service agent
I servizi della piattaforma agent spesso gestiscono risorse a esecuzione prolungata che eseguono azioni, ad esempio l'esecuzione di un job di addestramento che legge i dati di addestramento o la distribuzione di un modello di machine learning (ML) che legge il peso del modello. Queste risorse autonome hanno una propria identità di risorsa quando eseguono azioni. Questa identità è diversa da quella dell'entità che ha creato la risorsa. Le autorizzazioni concesse all'identità della risorsa definiscono a quali dati e altre risorse può accedere l'identità della risorsa, non le autorizzazioni dell'entità che ha creato la risorsa.
Per impostazione predefinita, le risorse Agent Platform utilizzano i service account gestiti da Agent Platform come identità della risorsa. Questi service account sono chiamati service agent della piattaforma degli agenti e sono collegati al progetto in cui viene creata la risorsa. Gli utenti con autorizzazioni specifiche di Agent Platform possono creare risorse che utilizzano i service agent di Agent Platform. Per alcuni servizi, puoi specificare unaccount di serviziot da collegare alla risorsa. La risorsa utilizza questo account di serviziot per accedere ad altre risorse e servizi. Per saperne di più sui service account, consulta Service account.
Agent Platform utilizza diversi service agent a seconda delle API chiamate. Ogni service agent dispone di autorizzazioni IAM specifiche per il progetto a cui è associato. Queste autorizzazioni vengono utilizzate dall'identità della risorsa per eseguire azioni e possono includere l'accesso di sola lettura a tutte le risorse Cloud Storage e ai dati BigQuery nel progetto.
Service account
Un service account è un account speciale utilizzato da un'applicazione o da un'istanza di macchina virtuale (VM), non da una persona. Puoi creare e assegnare autorizzazioni agli account di servizio per fornire autorizzazioni specifiche a una risorsa o un'applicazione.
Per informazioni sull'utilizzo di un account di servizio per personalizzare le autorizzazioni disponibili per un container di addestramento personalizzato o un container che fornisce previsioni online per un modello con addestramento personalizzato, leggi Utilizzare un service account personalizzato.
I service account sono identificati da un indirizzo email.
Agenti di servizio
Gli agenti di servizio vengono forniti automaticamente e consentono a un servizio di accedere alle risorse per tuo conto.
Quando viene creato un service agent, gli viene concesso un ruolo predefinito per il tuo progetto. La tabella seguente elenca gli agenti di servizio della piattaforma per agenti, i loro indirizzi email e i rispettivi ruoli:
| Nome | Utilizzato per | Indirizzo email | Ruolo |
|---|---|---|---|
| Agent Platform Service Agent | Funzionalità di Agent Platform | service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com |
roles/aiplatform.serviceAgent |
| Vertex AI RAG Data Service Agent | Vertex AI RAG accede ai dati importati dall'utente, a Vertex AI e ai processori Document AI nel progetto | service-PROJECT_NUMBER@gcp-sa-vertex-rag.iam.gserviceaccount.com |
roles/ |
| Vertex AI Custom Code Service Agent |
Codice di addestramento personalizzato Codice dell'applicazione Ray on Vertex AI |
service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com |
roles/aiplatform.customCodeServiceAgent |
| Vertex AI Extension Service Agent | Estensioni Vertex | service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com |
|
| Service account Cloud AI Platform Notebooks | Funzionalità di Vertex AI Workbench | service-PROJECT_NUMBER@gcp-sa-notebooks.iam.gserviceaccount.com |
roles/notebooks.serviceAgent |
L'agente di servizio del codice personalizzato Vertex AI viene creato solo se esegui il codice di addestramento personalizzato per addestrare un modello con addestramento personalizzato.
Ruoli e autorizzazioni service agent
Consulta i seguenti ruoli e autorizzazioni concessi agli agenti di servizio della piattaforma dell'agente.
| Ruolo | Autorizzazioni |
|---|---|
Vertex AI Service Agent( Concede a Vertex AI le autorizzazioni necessarie per il funzionamento. |
|
Vertex AI RAG Data Service Agent( Service agent Vertex AI utilizzato dalla RAG di Vertex per accedere ai dati importati dall'utente, a Vertex AI, ai processori Document AI e alla ricerca vettoriale nel progetto |
|
Vertex AI Custom Code Service Agent( Concede al codice personalizzato Vertex AI le autorizzazioni appropriate. |
|
Vertex AI Extension Service Agent( Concede all'estensione Vertex AI le autorizzazioni necessarie per il funzionamento. |
|
AI Platform Notebooks Service Agent( Fornisci accesso per consentire al service agent notebook di gestire le istanze notebook nei progetti degli utenti |
|
Concedere agli agenti di servizio Agent Platform l'accesso ad altre risorse
A volte devi concedere ruoli aggiuntivi a un service agent di Agent Platform. Ad esempio, se hai bisogno che Agent Platform acceda a un bucket Cloud Storage in un progetto diverso, devi concedere uno o più ruoli aggiuntivi al service agent.
Requisiti per l'aggiunta di ruoli per BigQuery
La seguente tabella descrive i ruoli aggiuntivi richiesti da aggiungere all'agente di servizio della piattaforma dell'agente per le tabelle o le visualizzazioni BigQuery in un progetto diverso o supportate da un'origine dati esterna.
Il termine progetto home si riferisce al progetto in cui si trova il set di dati o il modello di Agent Platform. Il termine progetto diverso si riferisce a qualsiasi altro progetto.
| Tipo di tabella | Progetto con tabella | Progetto origine dati | È necessario aggiungere un ruolo |
|---|---|---|---|
| Tabella BigQuery nativa | Progetto della casa | N/D | Nessuno. |
| Tabella BigQuery nativa | Progetto diverso | N/D | BigQuery Data Viewer per un altro progetto. Scopri di più. |
| Vista BigQuery | Progetto della casa | N/D | Nessuno. |
| Vista BigQuery | Progetto diverso | N/D | BigQuery Data Viewer per un altro progetto. Scopri di più. |
| Origine dati BigQuery esterna supportata da Bigtable | Progetto della casa | Progetto della casa | Bigtable Reader per il progetto della casa. Scopri di più. |
| Origine dati BigQuery esterna supportata da Bigtable | Progetto della casa | Progetto diverso | Bigtable Reader per un altro progetto. Scopri di più. |
| Origine dati BigQuery esterna supportata da Bigtable | Progetto diverso | Progetto diverso | BigQuery Reader e Bigtable Reader per un altro progetto. Scopri di più. |
| Origine dati BigQuery esterna supportata da Cloud Storage | Progetto della casa | Progetto della casa | Nessuno. |
| Origine dati BigQuery esterna supportata da Cloud Storage | Progetto della casa | Progetto diverso | Storage Object Viewer per un altro progetto. Scopri di più. |
| Origine dati BigQuery esterna supportata da Cloud Storage | Progetto diverso | Progetto diverso | Storage Object Viewer e BigQuery Data Viewer per un altro progetto. Scopri di più. |
| Origine dati BigQuery esterna supportata da Fogli Google | Progetto della casa | N/D | Condividi il file Fogli con il account di servizio della piattaforma per agenti. Scopri di più. |
| Origine dati BigQuery esterna supportata da Fogli Google | Progetto diverso | N/D | BigQuery Reader per un progetto diverso e condividi il file Fogli con il service account della piattaforma dell'agente. |
Requisiti per l'aggiunta di ruoli per Cloud Storage
Se accedi ai dati in un bucket Cloud Storage in un progetto diverso, devi assegnare il ruolo Storage > Storage Object Viewer ad Agent Platform in quel progetto. Scopri di più.
Se utilizzi un bucket Cloud Storage per ricevere dati dal computer locale per un'operazione di importazione e il bucket si trova in un progetto diverso dal progettoGoogle Cloud , devi assegnare il ruolo Storage > Storage Object Creator ad Agent Platform in quel progetto. Scopri di più.
Concedere l'accesso alla piattaforma dell'agente alle risorse del tuo progetto principale
Per concedere ruoli aggiuntivi a un service agent per Agent Platform nel tuo progetto principale:
Vai alla pagina IAM della console Google Cloud per il tuo progetto principale.
Seleziona la casella di controllo Includi concessioni di ruoli fornite da Google.
Determina l'agente di servizio a cui vuoi concedere le autorizzazioni e fai clic sull'icona a forma di matita .
Puoi filtrare in base a Principal:@gcp-sa-aiplatform-cc.iam.gserviceaccount.com per trovare gli agenti di servizio di Agent Platform.
Concedi i ruoli richiesti al service agent e salva le modifiche.
Concedere l'accesso alla piattaforma dell'agente alle risorse di un altro progetto
Quando utilizzi origini dati o destinazioni in un progetto diverso, devi concedere le autorizzazioni del service agent della piattaforma dell'agente in quel progetto. L'agente di servizio Agent Platform viene creato dopo l'avvio del primo job asincrono (ad esempio, la creazione di un endpoint). Puoi anche creare esplicitamente l'agente del servizio Agent Platform. Per saperne di più, consulta gcloud beta services identity create. Questo comando Google Cloud CLI crea l'agente di servizio principale e l'agente di servizio del codice personalizzato. Tuttavia, nella risposta viene restituito solo il service agent principale.
Per aggiungere autorizzazioni alla piattaforma dell'agente in un altro progetto:
Vai alla pagina IAM della console Google Cloud per il tuo progetto principale (il progetto in cui utilizzi Agent Platform).
Seleziona la casella di controllo Includi concessioni di ruoli fornite da Google.
Determina l'agente di servizio a cui vuoi concedere le autorizzazioni e copia il suo indirizzo email (elencato in Entità).
Puoi filtrare in base a Principal:@gcp-sa-aiplatform-cc.iam.gserviceaccount.com per trovare gli agenti di servizio di Agent Platform.
Modifica i progetti in modo che corrispondano a quello in cui devi concedere le autorizzazioni.
Fai clic su Aggiungi e inserisci l'indirizzo email in Nuove entità.
Aggiungi tutti i ruoli richiesti e fai clic su Salva.
Fornire l'accesso a Fogli Google
Se utilizzi un'origine dati BigQuery esterna supportata da Fogli Google, devi condividere il foglio con l'account di servizio della piattaforma Agenti. Il account di servizio della piattaforma dell'agente viene creato dopo l'avvio del primo job asincrono (ad esempio, la creazione di un endpoint). Puoi anche creare esplicitamente il account di servizio della piattaforma Agent utilizzando gcloud CLI seguendo questa istruzione.
Per autorizzare Agent Platform ad accedere al tuo file Fogli:
Vai alla pagina IAM della console Google Cloud .
Cerca il account di servizio con il nome
Agent Platform Service Agente copia il relativo indirizzo email (elencato in Entità).Apri il file Fogli e condividilo con questo indirizzo.
Passaggi successivi
- Scopri di più su IAM.
- Scopri di più sulle autorizzazioni IAM specifiche e sulle operazioni che supportano.
- Per scoprire i modi consigliati per configurare un progetto per un team, vedi Configurare un progetto per un team.
- Visualizza una panoramica di Agent Platform.