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 identità dell'agente e Agent Registry, forniscono funzionalità integrate per la creazione, il deployment e la gestione di agenti AI, server Model Context Protocol (MCP) e strumenti. Se attivi queste funzionalità per le tue risorse Cloud Run, puoi sfruttare le identità gestite dal sistema e la registrazione automatica per semplificare l'individuazione e la sicurezza dei tuoi workload agentici.

Questa guida spiega come:

• Stabilire i ruoli IAM richiesti
• Informazioni sui tipi funzionali e di identità
• Configurare le funzionalità per servizi e lavori
• Visualizzare le identità assegnate
• Visualizzare gli agenti e gli strumenti registrati nel registro degli agenti

Cloud Run supporta le seguenti funzionalità della piattaforma agent:

• Identità agente: assegna un'identità univoca e verificabile dal punto di vista crittografico 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

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

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

Verify that billing is enabled for your Google Cloud project.

Installa Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

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

Verify that billing is enabled for your Google Cloud project.

Installa Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

1. Abilita le API Cloud Run Admin, Identity and Access Management, Agent Registry e App Hub, se non sono già abilitate.

   Ruoli richiesti per abilitare le API

   Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di 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

2. Assicurati di aver configurato Agent Registry nel tuo progetto o nella tua organizzazione.
3. Installa e inizializza gcloud CLI.
4. Aggiorna i componenti:

   gcloud components update

5. Consulta la pagina Prezzi di Cloud Run per CPU, memoria e uscita di rete. 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: Cloud Run Admin (roles/run.admin)
• Per gestire le risorse di App Hub, uno dei seguenti elementi:
  • App Hub Admin (roles/apphub.admin)
  • Agent Registry API Admin (roles/apiregistry.admin)
• Per eseguire il deployment con un'identità specifica, una delle seguenti opzioni:
  • Utente service account IAM (roles/iam.serviceAccountUser)
  • Amministratore service account 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 con altri agenti, strumenti e Google Cloud API utilizzando un'identità univoca gestita dal sistema e associata al suo ciclo di vita.
• Attiva il rilevamento automatico degli agenti e dei server MCP all'interno di Agent Registry della tua organizzazione.
• Utilizza Identity-Aware Proxy come policy di autenticazione per proteggere i server MCP.

Comprendere i tipi funzionali e di identità

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

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

• Tipo funzionale: dichiara lo scopo principale del carico di lavoro. Una volta impostata, questa proprietà non può essere modificata o annullata. Assegna al tuo workload uno dei seguenti tipi funzionali:
  • agent: indica il workload come agente AI. I carichi di lavoro di questo tipo devono utilizzare il tipo agent-identity.
  • mcp-server: indica 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 tuo workload uno dei seguenti tipi di identità:
  • agent-identity: assegna un'identità agente gestita dal sistema progettata per gli agenti. Quando esegui il deployment con agent-identity, Agent Platform attiva i certificati di identità per impostazione predefinita. Per disattivare la funzionalità, aggiorna il servizio con il flag --no-identity-certificate o imposta l'annotazione run.googleapis.com/identity-certificate-enabled: "false". Segui la guida per autenticarti a strumenti e 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ù sull'Agent Identity.
  • service-account: utilizza un service account Google Cloud standard.

Comportamento della configurazione

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

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

Configurare 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 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 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

• Per aggiornare un servizio esistente in modo che utilizzi l'identità dell'agente:

  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 account di servizio precedente. Per evitare interruzioni della connessione, utilizza Policy Analyzer per identificare i ruoli richiesti e preassegnarli al principal principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME 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 servizio Cloud Run.
  • ORGANIZATION_ID: l'ID della tua Google Cloud organizzazione.
  • PROJECT_NUMBER: il tuo numero di progetto Google Cloud .
  • REGION: la regione in cui viene deployato il servizio.

• Per eseguire il deployment di un server MCP gestito dall'utente, specifica --functional-type=mcp-server. Puoi anche 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 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 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 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.

Visualizzare le identità assegnate

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

Servizi

Console

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

   Vai a Cloud Run

2. Seleziona Servizi dal menu di navigazione di Cloud Run e fai clic sul tuo 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 assegnato viene visualizzata nell'output.

Job

Console

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

   Vai a Cloud Run

2. Seleziona Job dal menu di navigazione di Cloud Run e fai clic sul tuo 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 assegnato viene visualizzata nell'output.

Visualizzare un agente o un server MCP in Agent Registry

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

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

Per visualizzare gli agenti e gli strumenti registrati nel registry e scoprire come memorizzarli e scoprirli in modo sicuro, esplora Agent Registry.

Passaggi successivi

• Scopri come autenticare i tuoi agenti per 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, consulta Esegui il deployment di agenti A2A su Cloud Run.
• Consulta la guida alla risoluzione dei problemi se riscontri problemi con la registrazione dell'agente o l'assegnazione dell'identità.