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

Autenticare gli agenti AI

Quando esegui il deployment di un agente su Cloud Run, puoi assegnargli un'identità che gli consenta di autenticarsi in modo sicuro quando comunica con le API e altri agenti.

Autenticarsi per Google Cloud API, altri agenti e strumenti

Quando il tuo workload Cloud Run è configurato con il tipo di identità agent-identity, riceve un'identità gestita dal sistema nel seguente formato:

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

Per i progetti senza un'organizzazione, il formato utilizza il numero di progetto:

principal://agents.global.project-PROJECT_NUMBER.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

Puoi utilizzare questa identità per autenticare in modo sicuro il tuo agente quando comunica con Google Cloud API, altri agenti o strumenti.

Autenticarsi alle API Google Cloud

Gli agenti possono utilizzare l'identità dell'agente assegnata per autenticarsi nelle Google Cloud API come Vertex AI, Cloud Storage e altri Google Cloud prodotti utilizzando i token di accesso recuperati dal server dei metadati di Cloud Run.

Concedi il ruolo IAM appropriato all'entità del tuo agente, ad esempio:
- Concedi l'accesso a Vertex AI:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="AGENT_PRINCIPAL" \
    --role="roles/aiplatform.user"
```
- Concedi l'accesso ad altre Google Cloud API:
  
  Concedi il ruolo richiesto alla risorsa di destinazione a AGENT_PRINCIPAL, ad esempio, roles/storage.objectViewer su un bucket Cloud Storage. Per i dettagli, vedi Eseguire l'autenticazione con le credenziali predefinite dell'applicazione.
Sostituisci quanto segue:
- PROJECT_ID: il tuo ID progetto Google Cloud .
- AGENT_PRINCIPAL: l'identità del tuo agente, ad esempio principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/AGENT_NAME.
Nel codice dell'applicazione dell'agente, utilizza le librerie client Google Cloud standard. Le librerie client utilizzano automaticamente le credenziali predefinite dell'applicazione (ADC) per recuperare i token di accesso di breve durata dal server dei metadati.

In alternativa, puoi recuperare manualmente un token di accesso dal server di metadati all'interno del container:
```
curl -s -H "Metadata-Flavor: Google" \
"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"
```

Autenticarsi in altri agenti su Cloud Run

Quando un agente deve chiamare un altro agente ospitato su Cloud Run, ad esempio gli agenti A2A, esegui l'autenticazione utilizzando un token di identità JWT (JSON Web Token) convalidato dal controllo IAM roles/run.invoker integrato di Cloud Run:

Concedi all'identità dell'agente chiamante il ruolo roles/run.invoker sul servizio Cloud Run di destinazione:
```
gcloud run services add-iam-policy-binding TARGET_SERVICE_NAME \
    --member="CALLER_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION
```
Sostituisci quanto segue:
- TARGET_SERVICE_NAME: il nome del servizio agente Cloud Run di destinazione.
- CALLER_AGENT_PRINCIPAL: l'identità dell'agente chiamante.
- REGION: la regione Google Cloud del servizio di destinazione.

Opzioni di convalida dei token

Cloud Run supporta due metodi di convalida dei token ID:

Token non associati: token di identità standard associati al pubblico generati dal server di metadati. Questo è il meccanismo predefinito per l'autenticazione da servizio a servizio e da agente ad agente.
Token vincolati: forniscono un binding crittografico tra il token e il certificato del workload utilizzando mTLS. Per utilizzare i token vincolati, il client chiamante fornisce la propria catena di certificati foglia nella richiesta.

Puoi utilizzare i token associati a mTLS per richiamare le risorse Cloud Run configurate con ingress=internal. In questo modo puoi limitare l'accesso a internet pubblico ai tuoi agenti o server MCP senza richiedere una rete VPC.

Recuperare un token ID non associato

Dal contenitore dell'agente chiamante, recupera un token di identità con l'URL del servizio di destinazione come pubblico:
```
TOKEN=$(curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_URL")
```
Sostituisci TARGET_SERVICE_URL con l'URL del servizio Cloud Run di destinazione, ad esempio https://target-agent-1234567890.us-central1.run.app.
Invia richieste al servizio di destinazione con il token nell'intestazione Authorization:
```
curl -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_URL/endpoint
```

Recupera un token ID vincolato (mTLS)

All'interno del contenitore dell'agente chiamante, leggi la catena di certificati foglia e richiedi un token vincolato dal server di metadati utilizzando una richiesta POST:

CERT_PATH="/var/run/secrets/workload-spiffe-credentials/certificates.pem"
JSON_PAYLOAD=$(jq -n --arg certs "$(cat $CERT_PATH)" '{"certificate_chain": $certs}')

TOKEN=$(curl -s -X POST \
    -H "Metadata-Flavor: Google" \
    -H "Content-Type: application/json" \
    -d "$JSON_PAYLOAD" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_MTLS_URL")

Chiama l'endpoint mTLS del servizio di destinazione, presentando i certificati del workload durante l'handshake TLS:

KEY_PATH="/var/run/secrets/workload-spiffe-credentials/private_key.pem"

curl --cert $CERT_PATH \
    --key $KEY_PATH \
    -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_MTLS_URL/endpoint

Esempio Python

Se scrivi codice dell'agente basato su Python, le librerie client Google Cloud standard richiedono automaticamente token vincolati per impostazione predefinita quando sono presenti certificati. Se devi effettuare richieste HTTP manuali:

import os
import requests
import google.auth
from google.auth.transport.requests import Request
from google.oauth2 import id_token

# Target agent's mTLS URL
target_mtls_url = "TARGET_SERVICE_MTLS_URL"

# 1. Fetch the ID token.
# google-auth automatically requests a bound ID token via POST because
# the platform configures the workload certificate environment variables.
auth_req = Request()
token = id_token.fetch_id_token(auth_req, target_mtls_url)

# 2. Make the HTTP call over mTLS, presenting the workload certificates.
cert_path = "/var/run/secrets/workload-spiffe-credentials/certificates.pem"
key_path = "/var/run/secrets/workload-spiffe-credentials/private_key.pem"

response = requests.get(
    target_mtls_url,
    headers={"Authorization": f"Bearer {token}"},
    cert=(cert_path, key_path)
)
print(response.text)

Sostituisci TARGET_SERVICE_MTLS_URL con l'URL mTLS del servizio Cloud Run di destinazione, ad esempio https://target-agent-12345.us-central1.mtls.run.app.

Esegui l'autenticazione sui server MCP su Cloud Run

Per connetterti a un server o strumento MCP ospitato su Cloud Run, utilizza l'identificatore --functional-type=mcp-server per attivare la registrazione automatica del server MCP nel registro degli agenti.

Se il server MCP è accessibile solo da altri agenti in esecuzione su Cloud Run, utilizza il controllo IAM invoker integrato. Consenti ai tuoi agenti di comunicare in modo nativo utilizzando le norme standard di richiamo dell'esecuzione:

gcloud run services add-iam-policy-binding MCP_SERVICE_NAME \
    --member="CALLING_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

Sostituisci quanto segue:

MCP_SERVICE_NAME: il nome del servizio Cloud Run di destinazione che ospita il server MCP.
CALLING_AGENT_PRINCIPAL: l'identità principale dell'agente che richiama il server MCP. Ad esempio, serviceAccount:my-agent@my-project.iam.iam.gserviceaccount.com.
REGION: la Google Cloud regione in cui viene eseguito il deployment del server MCP.

Dopo aver concesso il ruolo run.invoker, l'agente chiamante può recuperare un token di identità come descritto nella sezione Opzioni di convalida dei token.

Per scoprire come proteggere i server MCP con IAP per l'accesso programmatico a CLI e SDK, consulta Autenticare i server MCP.

Autenticarsi per conto degli utenti

Quando l'agente accede a strumenti e servizi esterni per conto di un utente, può utilizzare la propria identità di agente di cui è stato eseguito il provisioning per gestire l'autenticazione con i server MCP e gli endpoint esterni.

Per gestire in modo sicuro flussi di lavoro di autorizzazione complessi, come il consenso OAuth a tre vie (3LO), OAuth a due vie (2LO) e le chiavi API, configura gestore di autenticazione di Agent Identity.

Per istruzioni sul binding di questi gestori dell'autenticazione ai tuoi toolset, consulta Autenticarsi per accedere a strumenti e risorse.