Configura le funzionalità di Agent Platform per Cloud Run

Anteprima — configura le funzionalità di Agent Platform per Cloud Run

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. 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.

Le funzionalità di Gemini Enterprise Agent Platform come Agent Identity e Agent Registry forniscono funzionalità integrate per la creazione, il deployment e la gestione di agenti AI, server Model Context Protocol (MCP) e strumenti. Abilitando queste funzionalità per le risorse Cloud Run, puoi sfruttare le identità gestite dal sistema e la registrazione automatica per semplificare il rilevamento e la sicurezza dei workload agentici.

Questa guida spiega come:

• Stabilire i ruoli IAM richiesti
• Comprendere i tipi di identità e funzionali
• Configurare le funzionalità per servizi e job
• Visualizzare le identità assegnate
• Visualizzare gli agenti e gli strumenti registrati in Agent Registry

Cloud Run supporta le seguenti funzionalità di Agent Platform:

• Agent Identity: assegna un'identità univoca e verificabile tramite crittografia al tuo workload, consentendo connessioni sicure ad altri agenti, strumenti e API Google Cloud.
• Agent Registry: registra automaticamente gli agenti e gli strumenti per renderli rilevabili da altri sviluppatori e agenti della tua organizzazione.

Prima di iniziare

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

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

3. Installa Google Cloud CLI.

4. Configura gcloud CLI per utilizzare la tua identità federata.

   Per ulteriori informazioni, vedi Accedi a gcloud CLI con la tua identità federata.

5. Per inizializzare gcloud CLI, esegui questo comando:

   gcloud init

6. Abilita le API Cloud Run Admin, Identity and Access Management, Agent Registry e App Hub.

   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 utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

   Abilita le API

7. Assicurati di aver configurato Agent Registry nel tuo progetto o nella tua organizzazione.
8. Installa e inizializza gcloud CLI.
9. Aggiorna i componenti:

   gcloud components update

10. Consulta la pagina dei prezzi di Cloud Run per CPU, memoria e traffico di rete in uscita. Le dimensioni totali del disco di cui è stato eseguito il provisioning e la durata dell'istanza che lo utilizza contribuiscono al costo.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare le funzionalità di Agent Platform, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

• Per eseguire il deployment e gestire le risorse Cloud Run: Amministratore Cloud Run (roles/run.admin)
• Per gestire le risorse App Hub, uno dei seguenti:
  • Amministratore App Hub (roles/apphub.admin)
  • Amministratore API Agent Registry (roles/apiregistry.admin)
• Per eseguire il deployment con un'identità specifica, uno dei seguenti:
  • Utente account di servizio IAM (roles/iam.serviceAccountUser)
  • Amministratore account di servizio IAM (roles/iam.serviceAccountAdmin)

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.

Casi d'uso

Utilizza le funzionalità di Agent Platform con Cloud Run nei seguenti scenari:

• Autentica l'agente ad altri agenti, strumenti e Google Cloud API utilizzando un'identità univoca gestita dal sistema e associata al suo ciclo di vita.
• Abilita il rilevamento automatico di agenti e server MCP all'interno di Agent Registry della tua organizzazione.
• Utilizza Identity-Aware Proxy come criterio di autenticazione per proteggere i server MCP.

Comprendere i tipi di identità e funzionali

Configura le funzionalità di Agent Platform impostando le proprietà funzionali e di identità sulle risorse Cloud Run.

Queste due proprietà controllano come registrare e identificare un workload:

• Tipo funzionale: dichiara lo scopo principale del workload. Una volta impostata, questa proprietà non può essere modificata o annullata. Assegna al workload uno dei seguenti tipi funzionali:
  • agent: designa il workload come agente AI. I workload di questo tipo devono utilizzare il tipo agent-identity.
  • mcp-server: designa il workload come server MCP gestito dall'utente. Questo tipo può utilizzare qualsiasi tipo di identità supportato.
• Tipo di identità: specifica il tipo di identità assegnata al workload. Una volta impostata, questa proprietà non può essere modificata o annullata. Assegna al workload uno dei seguenti tipi di identità:
  • agent-identity: assegna un'identità dell'agente gestita dal sistema progettata per gli agenti. Quando esegui il deployment con agent-identity, Agent Platform abilita i certificati di identità per impostazione predefinita. Per disattivare questa opzione, aggiorna il servizio con il --no-identity-certificate flag o imposta l' run.googleapis.com/identity-certificate-enabled: "false" annotazione. Segui la guida per autenticare gli strumenti e le risorse per gli agenti che agiscono di propria autorità o per conto degli utenti finali. Per comprendere i concetti di base e i vantaggi in termini di sicurezza delle identità degli agenti gestite dal sistema, scopri di più su Agent Identity.
  • service-account: utilizza un account di servizio Google Cloud standard.

Comportamento della configurazione

Il comportamento delle proprietà funzionali e di identità dipende dalla combinazione scelta:

Tipo funzionale	Tipo di identità	Comportamento conseguente
agent	agent-identity	Il workload viene registrato come agente in Agent Registry e gli viene assegnata un'identità dell'agente gestita dal sistema.
agent	Altro o non specificato	Errore. I workload con functional-type=agent devono utilizzare identity-type=agent-identity.
mcp-server	agent-identity, service-account o non specificato	Il workload viene registrato come server MCP (/mcpServers) in Agent Registry. Se non specificato, il valore predefinito è un'identità dell'account di servizio.
Non specificato	service-account	Il workload viene eseguito come servizio o job Cloud Run standard.

Configura le funzionalità su servizi e job

Configura le funzionalità di Agent Platform sui servizi e sui job Cloud Run utilizzando Google Cloud CLI.

Servizi

• Per eseguire il deployment di un agente, specifica --functional-type=agent e --identity-type=agent-identity:

  gcloud beta run deploy SERVICE_NAME \
      --image=IMAGE_URL \
      --functional-type=agent \
      --identity-type=agent-identity

  Sostituisci quanto segue:

  • SERVICE_NAME: il nome del tuo servizio Cloud Run.
  • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest. Se utilizzi Artifact Registry, il repository REPO_NAME deve essere già stato creato. L'URL segue il formato di LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

• Per aggiornare un servizio esistente in modo che utilizzi Agent Identity:

  gcloud beta run services update SERVICE_NAME \
      --functional-type=agent \
      --identity-type=agent-identity \
      --no-traffic

  Importante: quando aggiorni un servizio esistente da un account di servizio a agent-identity, Cloud Run assegna una nuova entità che non eredita le autorizzazioni dal tuo account di servizio precedente. Per evitare interruzioni della connessione, utilizza Policy Analyzer per identificare i ruoli richiesti e preassegnarli all' principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME entità prima dell'aggiornamento oppure aggiorna il servizio con --no-traffic per assegnare le autorizzazioni prima di eseguire la migrazione del traffico.

  Sostituisci quanto segue:

  • SERVICE_NAME: il nome del tuo servizio Cloud Run.
  • ORGANIZATION_ID: l'ID della tua Google Cloud organizzazione.
  • PROJECT_NUMBER: il tuo Google Cloud progetto numero.
  • REGION: la regione in cui è stato eseguito il deployment del servizio.

• Per eseguire il deployment di un server MCP gestito dall'utente, specifica --functional-type=mcp-server. Facoltativamente, puoi specificare un tipo di identità utilizzando --identity-type:

  gcloud beta run deploy SERVICE_NAME \
      --image=IMAGE_URL \
      --functional-type=mcp-server \
      --identity-type=IDENTITY_TYPE

  Sostituisci quanto segue:

  • SERVICE_NAME: il nome del tuo servizio Cloud Run.
  • IMAGE_URL: un riferimento all'immagine container, ad esempio us-docker.pkg.dev/cloudrun/container/hello:latest. Se utilizzi Artifact Registry, il repository REPO_NAME deve essere già stato creato. L'URL segue il formato di LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
  • IDENTITY_TYPE: (facoltativo) Il tipo di identità assegnata al workload. Specifica agent-identity o service-account. Il valore predefinito è service-account.

Job

Nota: solo i servizi Cloud Run possono essere esposti come server MCP. I job Cloud Run non possono essere esposti come server MCP e supportano solo il tipo funzionale agent.

• Per creare un job dell'agente, specifica --functional-type=agent e --identity-type=agent-identity:

  gcloud beta run jobs create JOB_NAME \
    --image=IMAGE_URL \
    --functional-type=agent \
    --identity-type=agent-identity

  Sostituisci quanto segue:

  • JOB_NAME: il nome del tuo job Cloud Run.
  • IMAGE_URL: un riferimento all'immagine container.

Visualizza le identità assegnate

Puoi visualizzare l'identità dell'agente assegnata dalla Google Cloud console o gcloud CLI.

Servizi

Console

1. Nella Google Cloud console, vai a Cloud Run:

   Vai a Cloud Run

2. Seleziona Servizi dal menu di navigazione di Cloud Run e fai clic sul servizio.

3. Fai clic sulla scheda Revisioni e seleziona una revisione.

4. Fai clic sulla scheda Sicurezza.

Il campo Identità mostra l'identità dell'agente assegnata.

gcloud

Per visualizzare l'identità dell'agente, descrivi la revisione del servizio:

gcloud beta run revisions describe REVISION_NAME

Sostituisci REVISION_NAME con il nome della revisione del servizio.

L'identità dell'agente assegnata viene visualizzata nell'output.

Job

Console

1. Nella Google Cloud console, vai a Cloud Run:

   Vai a Cloud Run

2. Seleziona Job dal menu di navigazione di Cloud Run e fai clic sul job.

3. Fai clic sulla scheda Esecuzioni e seleziona un'esecuzione.

4. Visualizza i dettagli dell'esecuzione.

Il campo Identità mostra l'identità dell'agente assegnata.

gcloud

Per visualizzare l'identità dell'agente per l'esecuzione di un job, descrivi l'esecuzione:

gcloud beta run jobs executions describe EXECUTION_NAME

Sostituisci EXECUTION_NAME con il nome dell'esecuzione del job.

L'identità dell'agente assegnata viene visualizzata nell'output.

Visualizza un agente o un MCP in Agent Registry

Quando esegui il deployment di una risorsa Cloud Run con --functional-type=agent o --functional-type=mcp-server, viene registrata automaticamente in Agent Registry della tua organizzazione.

• Gli agenti vengono registrati nel catalogo degli agenti (/agents).
• I server MCP vengono registrati nel catalogo dei server MCP (/mcpServers).

Per visualizzare gli agenti e gli strumenti registrati nel registro e scoprire come archiviarli e rilevarli in modo sicuro, esplora Agent Registry.

Passaggi successivi

• Scopri come autenticare gli agenti ad API e strumenti.
• Scopri come autenticare i server MCP per connessioni sicure.
• Scopri come ospitare i server MCP su Cloud Run.
• Utilizza l'Agent Development Kit per creare e registrare agenti personalizzati nel registro.
• Per creare ed eseguire il deployment di agenti conformi alla specifica A2A, vedi Esegui il deployment di agenti A2A su Cloud Run.
• Consulta la guida alla risoluzione dei problemi se riscontri problemi con la registrazione degli agenti o l'assegnazione dell'identità.