Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Probleme mit der Authentifizierung der Agent-Identität beheben

Wenn Sie häufige Fehler bei der Authentifizierung von Agenten mit Agent Identity und dem Agent Identity-Authentifizierungsmanager beheben möchten, prüfen Sie die Konfigurationen Ihres Authentifizierungsanbieters, die IAM-Rollenbindungen (Identity and Access Management), die OAuth-Bereiche und die Einstellungen für die OIDC-Tokenüberprüfung (OpenID Connect).

Informationen zum Verwalten von Authentifizierungsanbietern finden Sie unter Authentifizierungsanbieter für Agent Identity verwalten. Informationen zum Prüfen von Agent Identity-ID-Tokens in externen Diensten finden Sie unter Mit der eigenen Identität eines KI-Agenten bei externen Diensten authentifizieren.

Nicht übereinstimmender Weiterleitungs-URI

Wenn Sie während des OAuth-Vorgangs von der Drittanbieteranwendung den Fehler redirect URI mismatch erhalten, prüfen Sie, ob der im Entwicklerportal des Drittanbieters registrierte Weiterleitungs-URI genau mit dem vom Auth-Manager generierten URI übereinstimmt.

Um dieses Problem zu beheben, rufen Sie den generierten Weiterleitungs-URI ab. Dazu können Sie die Details des Authentifizierungsanbieters in der Google Cloud Console aufrufen oder den folgenden gcloud-Befehl ausführen:

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

Nutzerrolle fehlt

Wenn Ihr Agent den Authentifizierungsanbieter nicht verwenden kann, prüfen Sie, ob die Agent-Identität die Rolle roles/agentidentity.user für die Authentifizierungsanbieter-Ressource hat.

Um dieses Problem zu beheben, weisen Sie die Rolle über die Google Cloud Console zu oder führen Sie den Befehl add-iam-policy-binding aus.

Probleme mit dem Aussteller-Endpunkt

Prüfen Sie bei OIDC-Anbietern, ob der Ausstellerendpunkt öffentlich zugänglich ist und das Discovery-Dokument .well-known/openid-configuration unterstützt.

Wenn Google Cloud die OIDC-Metadaten oder JWKS nicht abrufen kann, prüfen Sie, ob sich der Endpunkt hinter einer Firewall oder einem eingeschränkten Netzwerk befindet.

Fehler 401 UNAUTHENTICATED

Wenn sich Ihr Agent nicht authentifizieren kann, tritt möglicherweise der folgende Fehler auf. Dieser Fehler wird in der Regel durch eine von Google verwaltete Richtlinie für den kontextsensitiven Zugriff verursacht, die mTLS-Bindung und kryptografische DPoP-Nachweise erzwingt:

{
  "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"
  }
}

Wenn Sie bestimmte Anforderungen an die Tokenfreigabe haben oder das Token direkt in den Header einfügen müssen, können Sie die Standardrichtlinie für den kontextsensitiven Zugriff deaktivieren, um diesen Fehler zu beheben. Wenn Sie die Funktion deaktivieren möchten, legen Sie die folgende Umgebungsvariable fest, wenn Sie Ihren Agenten bereitstellen:

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

API-Schlüsseldienst blockiert (`API_KEY_SERVICE_BLOCKED`)

Wenn Sie Ihren API-Schlüssel validieren, kann der folgende Fehler auftreten. Dieser Fehler weist darauf hin, dass der Dienst blockiert ist:

"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."
  }
]

Dieser Fehler tritt auf, weil der Ziel-API-Dienst (z. B. die Cloud Translation API) in Ihrem Google Cloud -Projekt nicht aktiviert wurde oder die Einschränkungen des API-Schlüssels den Zugriff auf diesen Dienst nicht zulassen.

So beheben Sie diesen Fehler:

Rufen Sie in der Google Cloud Console die Seite APIs und Dienste >Bibliothek auf und prüfen Sie, ob die Ziel-API aktiviert ist.
Rufen Sie „APIs und Dienste“ > „Bibliothek“ auf.
Rufen Sie in der Google Cloud Console die Seite APIs und Dienste > Anmeldedaten auf, bearbeiten Sie Ihren API-Schlüssel und prüfen Sie, ob die API-Einschränkungen den Zugriff auf den Dienst zulassen.
Rufen Sie „APIs & Dienste“ > „Anmeldedaten“ auf.

Ungültiger API-Schlüssel (`API_KEY_INVALID`)

Beim Senden von Anfragen an einen Drittanbieterdienst kann der folgende Fehler auftreten. Dieser Fehler gibt an, dass der API-Schlüssel ungültig ist:

"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."
  }
]

Dieser Fehler tritt auf, weil der im Anfrageheader übergebene API-Schlüsselstring falsch oder fehlerhaft ist oder in den Anmeldedaten Ihres Projekts nicht vorhanden ist.

Prüfen Sie, ob Sie den richtigen API-Schlüsselstring von der Seite Anmeldedaten in der Google Cloud Console kopiert haben und keine führenden oder nachgestellten Leerzeichen enthalten sind.

Berechtigung zum Abrufen von Anmeldedaten verweigert (`agentidentity.authProviders.retrieveCredentials`)

Wenn Sie adk web lokal ausführen oder mit Ihrem bereitgestellten Agenten interagieren, kann der folgende 403 Forbidden-Fehler auftreten:

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

Dieser Fehler tritt auf, weil das Hauptkonto, das versucht, den Authentifizierungsanbieter aufzurufen, nicht die erforderlichen IAM-Berechtigungen zum Abrufen von Anmeldedaten hat.

Weisen Sie dem Hauptkonto die Rolle Agent Identity User (roles/agentidentity.user) zu, um diesen Fehler zu beheben:

Wenn dieser Fehler während der lokalen Entwicklung (uv run adk web oder uvicorn) auftritt, prüfen Sie, ob Sie die Rolle Ihrem persönlichen Nutzerkonto (user:USER_EMAIL) zugewiesen haben.
Wenn dieser Fehler bei der Interaktion mit einem bereitgestellten Agenten auftritt, prüfen Sie, ob Sie die Rolle dem SPIFFE-ID-Hauptkonto (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID) Ihres Agenten zugewiesen haben.

Allgemeiner Bereitstellungsfehler

Wenn Sie Ihren Agenten mit uv run adk deploy bereitstellen, schlägt der Befehl möglicherweise mit einer allgemeinen Fehlermeldung fehl.

Dieser Fehler tritt aufgrund fehlender Python-Abhängigkeiten, Syntaxfehler in agent.py oder falsch konfigurierter Umgebungsvariablen auf.

So beheben Sie diesen Fehler:

Öffnen Sie die Google Cloud Console und rufen Sie die Seite Log-Explorer auf.
Suchen Sie nach den Logs des temporären Bereitstellungscontainers (z. B. maps_mcp_agent_tmp... oder bigquery_mcp_agent_tmp...).
Prüfen Sie den Python-Traceback, um Syntaxfehler zu identifizieren oder fehlende Pakete zu finden.
Achten Sie darauf, dass alle erforderlichen Pakete in der Datei requirements.txt aufgeführt sind.

ServiceNow-Authentifizierungsschleife oder unerwartete Bereiche

Wenn sich ein Agent mit dreibeinigem OAuth bei ServiceNow authentifiziert, kann der Authentifizierungsablauf fehlschlagen oder der Agent kann in eine Anfrage-Schleife geraten.

Dieses Problem tritt auf, weil ServiceNow die gewährten Bereiche auf Anwendungsebene und nicht anhand der vom Agent angeforderten Bereiche bestimmt. Wenn ein Administrator bestimmte Bereiche in der ServiceNow-Anwendung konfiguriert (z. B. useraccount), gibt ServiceNow Tokens zurück, die nur diese konfigurierten Bereiche enthalten, auch wenn der Agent andere Bereiche angefordert hat (z. B. mcp_server). Wenn der Agent die angeforderten Bereiche strikt erwartet oder validiert, lehnt er das empfangene Token ab und fordert möglicherweise in einer Schleife erneut Anmeldedaten an.

So beheben Sie das Problem:

Melden Sie sich als Administrator in Ihrer ServiceNow-Instanz an.
Rufen Sie die ServiceNow-OAuth-Anwendungskonfiguration auf.
Achten Sie darauf, dass alle für Ihren Agenten erforderlichen Bereiche explizit der Liste der zulässigen Bereiche für die Anwendung hinzugefügt werden.
Konfigurieren Sie Ihren Agenten so, dass er nur die in ServiceNow aktivierten Bereiche anfordert.

Weitere Informationen finden Sie unter Unterstützte Drittanbieterdienste.

Fehler bei mehreren Bereichen in GitHub oder Microsoft

Wenn Sie einen Authentifizierungsanbieter für GitHub oder Microsoft konfigurieren, schlägt die Authentifizierung fehl, wenn Sie mehrere OAuth-Bereiche anfordern.

Der Auth-Manager unterstützt Integrationen mit einem einzelnen Bereich für GitHub und Microsoft. Der Auth-Manager unterstützt nicht das gleichzeitige Anfordern mehrerer Bereiche.

Konfigurieren Sie Ihren Agenten oder Authentifizierungsanbieter so, dass nur ein einziger Bereich angefordert wird, der für die Integration erforderlich ist.

Weitere Informationen finden Sie unter Unterstützte Drittanbieterdienste.

Fehler bei der OpenID Connect-Erkennung und bei JWKS-Endpunkten

Ein externer Dienst oder eine vertrauende Partei kann die Endpunkte des Google CloudSecurity Token Service OpenID Connect Discovery (/.well-known/openid-configuration) oder des JSON Web Key Set (/openid/jwks) abfragen, um ein Agent Identity-ID-Token zu verifizieren. Wenn Sie diese Endpunkte abfragen, kann die Anfrage mit dem Fehler HTTP 400, 404, 429 oder 500 fehlschlagen.

In der folgenden Tabelle werden die Ursachen und Lösungen für diese Fehler beschrieben:

HTTP-Status	Ursache	Lösung
`400 Bad Request`	Dieser Fehler tritt auf, weil der Ressourcenname des Workload Identity-Pools in der Anfrage-URL ungültig ist oder die Anfrage einen HTTP-Header `Authorization` enthält.	So beheben Sie diesen Fehler: Prüfen Sie, ob der Ressourcenname des Workload Identity-Pools ein unterstütztes Format für die Agent Trust-Domain verwendet (`agents.global.org-ORGANIZATION_ID.system.id.goog` oder `agents.global.proj-PROJECT_NUMBER.system.id.goog`). Entfernen Sie alle `Authorization`- oder OAuth-Header aus der Anfrage. Die Endpunkte `/.well-known/openid-configuration` und `/openid/jwks` sind öffentlich und nicht authentifiziert. Wenn Authentifizierungsheader übergeben werden, schlägt die Anfrage mit dem Fehler `HTTP 400` fehl.
`404 Not Found`	Dieser Fehler tritt auf, weil die angegebene Organisations-ID, Projektnummer oder der Workload Identity-Pool nicht vorhanden ist oder der URL-Pfad falsch ist.	Prüfen Sie, ob die Organisations-ID, die Projektnummer und die Vertrauensdomäne (Workload Identity-Pool-ID) in der URL korrekt sind, um diesen Fehler zu beheben. Prüfen Sie auch, ob der URL-Pfad mit `/.well-known/openid-configuration` oder `/openid/jwks` endet.
`429 Too Many Requests`	Dieser Fehler tritt auf, weil Ihr Prüfer das Limit für die Anforderungsrate überschritten hat, indem er die Discovery- oder JWKS-Endpunkte abgefragt hat, ohne die Antwort im Cache zu speichern.	Konfigurieren Sie Ihren Prüfer so, dass das Discovery-Dokument und die JWKS gemäß dem Antwortheader `Cache-Control: public, max-age=86400, must-revalidate` bis zu 24 Stunden lang im Cache gespeichert werden, um diesen Fehler zu beheben.
`500 Internal Server Error`	Dieser Fehler tritt auf, weil der Server beim Abrufen der öffentlichen Signaturschlüssel ein vorübergehendes internes Problem festgestellt hat.	Verwenden Sie zur Behebung dieses Fehlers Ihren im Cache gespeicherten JWKS, falls verfügbar, oder wiederholen Sie die Anfrage mit exponentiellem Backoff.

Überprüfung der Tokensignatur schlägt nach Schlüsselrotation fehl

Wenn ein externer Dienst ein Agent Identity-ID-Token verifiziert, kann die Signaturprüfung für neu ausgestellte Tokens fehlschlagen, obwohl vorherige Tokens desselben Agents erfolgreich waren.

Dieses Problem tritt auf, weil Google Cloud die privaten und öffentlichen Signaturschlüssel für Workload Identity-Pools regelmäßig rotiert. Daher befindet sich die kid (Schlüssel-ID) des eingehenden Tokens möglicherweise nicht im lokalen Schlüssel-Cache Ihres Prüfers.

Konfigurieren Sie zur Behebung dieses Problems Ihren Prüfer so, dass er, wenn er ein Token mit einem nicht erkannten kid empfängt, ein neues JWKS vom /openid/jwks-Endpunkt abruft, bevor er das Token ablehnt.