Configura Agent Registry

Per registrare e scoprire i tuoi agenti AI, i server Model Context Protocol (MCP), le competenze autonome e gli endpoint in Agent Registry, devi abilitare l'API Agent Registry nel tuo progetto Google Cloud . Il progetto in cui abiliti Agent Registry funge da progetto di governance.

Puoi configurare Agent Registry in un singolo progetto di governance o in più progetti configurando un confine di gestione in cui un progetto di gestione centrale funge da progetto di governance.

Prima di iniziare

Configura Agent Registry in un singolo progetto o in più progetti:

• Progetto singolo: scopri e gestisci agenti, server MCP, skill ed endpoint in un unico progetto di governance Google Cloud . Utilizza un progetto esistente o crea un progetto, abilita l'API Agent Registry e concedi le autorizzazioni.
• Più progetti (confine di gestione): centralizza il discovery e la governance in più progetti membri nella gerarchia delle risorseGoogle Cloud associando un confine di gestione a un progetto di gestione. Designa un progetto Google Cloud esistente come progetto di gestione o lascia che Resource Manager ne crei uno per te, abilita l'API Resource Manager, configura un confine di gestione e concedi le autorizzazioni.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare Agent Registry, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo progetto Google Cloud :

• Abilitare l'API Agent Registry: Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin)
• Concedi i ruoli per l'utilizzo dell'API Agent Registry: Project IAM Admin (roles/resourcemanager.projectIamAdmin)
• Ottieni l'accesso completo alle risorse dell'API Agent Registry: Agent Registry API Admin (roles/agentregistry.admin)

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'ambiente Google Cloud CLI

Se prevedi di utilizzare gcloud CLI per Agent Registry, segui questi passaggi:

1. Nella console Google Cloud , attiva Cloud Shell.

   Attiva Cloud Shell

   Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

2. Aggiorna gcloud CLI alla versione più recente con il comando gcloud components update:

   gcloud components update
   

3. Se prevedi di utilizzare le funzionalità in anteprima, installa il componente alpha con il comando gcloud components install:

   gcloud components install alpha
   

Abilita l'API Agent Registry

• Per un singolo progetto: abilita l'API Agent Registry nel tuo progetto di governance. Dopo aver abilitato l'API e concesso le autorizzazioni, puoi iniziare a registrare e scoprire gli agenti in quel progetto. Non è necessario configurare un confine di gestione.
• Per più progetti (limite di gestione): abilita l'API Resource Manager nel progetto che utilizzi per eseguire i comandi di configurazione. Quando configuri un confine di gestione per più progetti e crei la configurazione delle funzionalità, Resource Manager abilita automaticamente l'API Agent Registry nel tuo progetto di gestione.

Utilizza l'ID progetto per abilitare le API:

Console

Per un singolo progetto, abilita l'API Agent Registry nel tuo progetto:

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilitare l'API

Per più progetti (limite di gestione), abilita l'API Resource Manager nel progetto che utilizzi per la configurazione:

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilitare l'API

gcloud

• Per un singolo progetto, abilita l'API Agent Registry nel progetto con il comando gcloud services enable:

  gcloud services enable agentregistry.googleapis.com \
      --project=PROJECT_ID
  

• Per più progetti (limite di gestione), abilita l'API Resource Manager nel progetto che utilizzi per la configurazione:

  gcloud services enable cloudresourcemanager.googleapis.com \
      --project=PROJECT_ID
  

Sostituisci PROJECT_ID con l'ID progetto del tuo progetto di governance autonomo o del progetto che vuoi utilizzare come progetto di gestione per il tuo confine di gestione.

Nota: se integri Agent Registry con Agent Gateway per l'applicazione delle policy, devi anche abilitare l'API Identity-Aware Proxy nel tuo progetto. Il gateway utilizza l'API Identity-Aware Proxy per autenticare e autorizzare il traffico in uscita dai tuoi agenti verso destinazioni esterne.

Configura un confine di gestione per più progetti

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Per utilizzare Agent Registry in più progetti Google Cloud , configura un limite di gestione. Un confine di gestione raggruppa uno o più progetti membri Google Cloud in un progetto di gestione centrale che funge da progetto di governance in modo da poter scoprire e gestire agenti AI, server MCP e strumenti tra i progetti.

Puoi definire un confine di gestione in Resource Manager. Per istruzioni passo passo, consulta Configura i confini di gestione nella documentazione di Resource Manager.

Per una panoramica dell'architettura di come funzionano insieme le risorse BoundaryConfig, Boundary e CapabilityConfig, consulta Confini tra progetti.

Quando crei una risorsa CapabilityConfig con agent-management, Resource Manager attiva automaticamente agentregistry.googleapis.com nel progetto di gestione. Dopo aver stabilito il confine di gestione:

1. Se necessario per le operazioni locali all'interno di singoli progetti membri, abilita l'API Agent Registry in questi progetti membri.
2. Concedi i ruoli e le autorizzazioni richiesti agli utenti e ai service account nel progetto di gestione.

Quando elenchi o cerchi agenti o server MCP in una località del progetto di gestione, Agent Registry aggrega e restituisce le risorse rilevate automaticamente in quella località da tutti i progetti membri nel confine, insieme a tutte le risorse Service registrate create direttamente in quella località nel progetto di gestione. Ogni nome risorsa restituito conserva l'ID del componente e utilizza il progetto specificato nella richiesta.

Concedi le autorizzazioni

Per visualizzare e gestire le risorse in Agent Registry, devi concedere agli utenti le autorizzazioni di Identity and Access Management (IAM) appropriate.

Concedi ai tuoi utenti uno o più dei seguenti ruoli di Agent Registry:

• Agent Registry API Viewer (roles/agentregistry.viewer): visualizza e cerca agenti, server MCP, strumenti, skill autonome, revisioni delle skill, publisher, endpoint e associazioni.
• Agent Registry API Editor (roles/agentregistry.editor): visualizza e modifica le risorse di Agent Registry, tra cui la registrazione, l'aggiornamento e l'eliminazione di agenti, server MCP, strumenti, endpoint, skill autonome e revisioni delle skill.
• Agent Registry API Admin (roles/agentregistry.admin): esegue tutte le azioni sulle risorse di Agent Registry, tra cui la registrazione e la gestione di agenti, server MCP, strumenti, endpoint, skill autonomi, revisioni di skill, associazioni e policy IAM degli skill.
• Utente Agent Registry (roles/agentregistry.user): visualizza tutte le risorse di Agent Registry e crea, aggiorna ed elimina skill autonome e revisioni delle skill senza accesso in modifica ad agenti, server MCP o endpoint.

Per scoprire come concedere i ruoli IAM su un progetto, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Nota: Agent Registry e Agent Gateway hanno un supporto limitato per la federazione delle identità della forza lavoro. Se si verificano errori di caricamento o autorizzazione nella console Google Cloud , accedi al servizio con un Account Google standard gestito tramite Cloud Identity o Google Workspace.

Modifica il progetto Agent Registry

Se vuoi cambiare il progetto in cui utilizzi Agent Registry e rimuovere le dipendenze dal progetto precedente, disattiva l'API Agent Registry nel progetto precedente. Dopo aver disabilitato l'API Agent Registry nel vecchio progetto, puoi abilitarla in un altro progetto. La migrazione dei dati non viene eseguita e devi ricreare le risorse in questo nuovo progetto.

Disabilita l'API Agent Registry

Se non vuoi più utilizzare Agent Registry, disabilita l'API Agent Registry nel progetto:

Console

1. Nella console Google Cloud , vai alla pagina di gestione dell'API Agent Registry:

   Vai all'API Agent Registry

2. Nel selettore di progetti, seleziona il progetto Google Cloud in cui hai configurato Agent Registry.

3. Fai clic su Disabilita API.

4. Nella finestra di dialogo di conferma, fai clic su Disabilita.

gcloud

Disabilita l'API Agent Registry nel tuo progetto con il comando gcloud services disable:

gcloud services disable agentregistry.googleapis.com \
    --project=PROJECT_ID

Sostituisci PROJECT_ID con l'ID del progetto.

Passaggi successivi

• Scopri di più sui confini tra progetti
• Guida rapida: registra un agente
• Registra i server MCP
• Registra le skill
• Cerca agenti, strumenti e skill