Risolvere i problemi di autenticazione dell'identità dell'agente

Questo documento descrive come risolvere gli errori comuni di autenticazione utilizzando l'identità dell'agente con il gestore dell'autenticazione.

URI di reindirizzamento non corrispondente

Se ricevi un errore redirect URI mismatch dall'applicazione di terze parti durante il flusso OAuth, assicurati che l'URI di reindirizzamento registrato nel portale per sviluppatori di terze parti corrisponda esattamente all'URI generato dal gestore dell'autenticazione.

Per risolvere il problema, trova l'URI di reindirizzamento generato visualizzando i dettagli del provider di autenticazione nella Google Cloud console o eseguendo il seguente gcloud comando:

gcloud alpha agent-identity authProviders describe AUTH_PROVIDER_NAME \
    --location="LOCATION"

Ruolo utente mancante

Se l'agente non può utilizzare il provider di autenticazione, verifica che l'identità dell'agente abbia il ruolo roles/agentidentity.user nella risorsa del provider di autenticazione.

Per risolvere il problema, assegna il ruolo utilizzando la Google Cloud console o esegui il add-iam-policy-binding comando.

Problemi relativi all'endpoint dell'emittente

Per i provider OIDC, verifica che l'endpoint dell'emittente sia accessibile pubblicamente e supporti il documento di rilevamento .well-known/openid-configuration.

Se non riesci a recuperare i metadati OIDC o JWKS, assicurati che l'endpoint non sia protetto da un firewall o da una rete con limitazioni. Google Cloud

Errore 401 UNAUTHENTICATED

Se l'agente non riesce ad autenticarsi, potrebbe verificarsi il seguente errore. Questo errore è in genere causato da un criterio di accesso sensibile al contesto gestito da Google che applica l'associazione mTLS e le prove crittografiche DPoP:

{
  "error": {
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED"
  }
}

Per risolvere questo errore, puoi disattivare il criterio di accesso sensibile al contesto predefinito quando hai requisiti specifici di condivisione dei token o devi inserire il token direttamente nell'intestazione. Per disattivare, imposta la seguente variabile di ambiente quando esegui il deployment dell'agente:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

Servizio chiavi API bloccato (API_KEY_SERVICE_BLOCKED)

Se convalidi la chiave API, potrebbe verificarsi il seguente errore. Questo errore indica che il servizio è bloccato:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_SERVICE_BLOCKED",
    "domain": "googleapis.com",
    "metadata": {
      "methodName": "google.cloud.translate.v2.TranslateService.TranslateText",
      "service": "translate.googleapis.com",
      "consumer": "projects/PROJECT_NUMBER",
      "apiName": "translate"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "Requests to this API translate method google.cloud.translate.v2.TranslateService.TranslateText are blocked."
  }
]

Questo errore si verifica perché il servizio API di destinazione (ad esempio, l'API Cloud Translation) non è stato abilitato nel tuo Google Cloud progetto, o le limitazioni della chiave API non consentono l'accesso a questo servizio.

Per risolvere questo errore, segui questi passaggi:

  1. Nella Google Cloud console, vai alla pagina API e servizi >Libreria e assicurati che l'API di destinazione sia abilitata.

    Vai ad API e servizi >Libreria

  2. Nella Google Cloud console, vai alla pagina API e servizi >Credenziali, modifica la chiave API e verifica che le limitazioni API consentano l'accesso al servizio.

    Vai ad API e servizi >Credenziali

Chiave API non valida (API_KEY_INVALID)

Quando invii richieste a un servizio di terze parti, potrebbe verificarsi il seguente errore. Questo errore indica che la chiave API non è valida:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_INVALID",
    "domain": "googleapis.com",
    "metadata": {
      "service": "translate.googleapis.com"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "API key not valid. Please pass a valid API key."
  }
]

Questo errore si verifica perché la stringa della chiave API passata nell'intestazione della richiesta non è corretta, è malformata o non esiste nelle credenziali del progetto.

Per risolvere questo errore, verifica di aver copiato la stringa della chiave API corretta dalla pagina Credenziali nella Google Cloud console e di non aver incluso spazi iniziali o finali.

Autorizzazione negata per il recupero delle credenziali (agentidentity.authProviders.retrieveCredentials)

Quando esegui adk web in locale o interagisci con l'agente di cui hai eseguito il deployment, potrebbe verificarsi il seguente errore 403 Forbidden:

google.api_core.exceptions.Forbidden: 403 POST https://agentidentitycredentials.mtls.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/credentials:retrieve?%24alt=json%3Benum-encoding%3Dint: Permission 'agentidentity.authProviders.retrieveCredentials' denied on resource '//agentidentity.googleapis.com/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME' (or it may not exist).

Questo errore si verifica perché l'entità che tenta di richiamare il provider di autenticazione non dispone delle autorizzazioni IAM richieste per recuperare le credenziali.

Per risolvere questo errore, assegna il ruolo Utente identità dell'agente (roles/agentidentity.user) all'entità:

  • Se questo errore si verifica durante lo sviluppo locale (uv run adk web o uvicorn), assicurati di aver concesso il ruolo al tuo account utente personale (user:USER_EMAIL).
  • Se questo errore si verifica quando interagisci con un agente di cui è stato eseguito il deployment, assicurati di aver concesso il ruolo all'entità dell'ID SPIFFE dell'agente (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

Errore generico di deployment

Quando esegui il deployment dell'agente utilizzando uv run adk deploy, il comando potrebbe non riuscire con un messaggio di errore generico.

Questo errore si verifica a causa di dipendenze Python mancanti, errori di sintassi in agent.py o variabili di ambiente configurate in modo errato.

Per risolvere questo errore:

  1. Apri la Google Cloud console e vai alla pagina Esplora log.
  2. Cerca i log del container di deployment temporaneo (ad esempio, maps_mcp_agent_tmp... o bigquery_mcp_agent_tmp...).
  3. Controlla il traceback di Python per identificare gli errori di sintassi o tracciare i pacchetti mancanti.
  4. Assicurati che tutti i pacchetti richiesti siano elencati nel file requirements.txt.

Passaggi successivi