Verbindungsprobleme mit dem Agent Gateway beheben

In diesem Leitfaden erfahren Sie, wie Sie Verbindungsfehler mit der Gemini Enterprise Agent Platform beheben können, insbesondere wenn Sie Agent Gateway, Agentenidentität, IAM-Richtlinien (Identity and Access Management) und delegierte Autorisierung mit Dienst-Erweiterungen verwenden.

Fehlerbehebung mit dem Skill „Agent Platform Troubleshooting“

Wenn Sie Verbindungs-, Autorisierungs- und Startprobleme interaktiv mit einem KI-basierten Programmierassistenten diagnostizieren möchten, können Sie die agent-platform-troubleshooting-Fähigkeit aus dem Cloud de Confiance by S3NS Agent Skills-Repository installieren.

Dieser Skill stattet KI-Agenten mit fachspezifischen Diagnose-Playbooks, Logfiltern und Lösungsschritten für den gesamten Agent Platform-Stack aus, darunter:

  • Ablehnungen von ausgehendem Traffic des Agent-Gateways: Diagnostizieren von 403 Forbidden-Fehlern, die vom Gateway abgefangen wurden, und Prüfen von IAP-Autorisierungsentscheidungen.
  • Fehler beim Starten der Agent Runtime: Identifizieren fehlender Rollen (z. B. roles/browser oder resourcemanager.projects.get) und Bootstrap-Ausnahmen.
  • Probleme mit dem Ziel der Agent Registry: Überprüfen von Diensteinträgen, Endpunktschnittstellen und konsolidierten Google APIs-Konfigurationen.
  • IAM-Zugriffsrichtlinien: Validierung von UAP-Bindungen (Unified Access Policy), Bedingungsausdrücken und PAB-Bereichen (Principal Access Boundary).
  • Container-Vertrauensstellung: Diagnostizieren von TLS-Zertifikats- und Handshake-Fehlern für benutzerdefinierte Container (BYOC) oder private Zertifizierungsstellen (CAs).

Führen Sie den folgenden Befehl aus, um den Skill in Ihrer Agent-Umgebung zu installieren:

npx skills add https://github.com/google/skills --skill agent-platform-troubleshooting

Ablauf von ausgehenden Anfragen

Die Agent Platform verwendet für den gesamten ausgehenden Traffic eine Standard-Ablehnungsrichtlinie. Damit ein Agent eine Verbindung zu externen Ressourcen herstellen kann, müssen Sie den Zugriff auf jeder Netzwerk- und Identitätsebene explizit zulassen. Wenn Agent Gateway aktiviert ist, fängt das Gateway alle Anfragen vom Agent ab und wendet die konfigurierten Richtlinien an.

Damit eine Anfrage erfolgreich ist, muss sie alle folgenden Bedingungen erfüllen:

  • IAM-Zugriffsrichtlinie: Der Identität des KI-Agents, die dem KI-Agenten zugewiesen ist, muss die Berechtigung iap.resources.egressViaIAP für die Zielressource gewährt werden, entweder direkt oder über eine Gruppe von Hauptkonten. Weitere Informationen finden Sie unter IAM-Agent-Richtlinien erstellen. Informationen zur Fehlerbehebung bei IAP-Richtlinien
  • Agent Registry: Es wird empfohlen, Ziele in der Agent Registry zu registrieren, um detaillierte Zugriffsrichtlinien pro Ressource und Steuerelemente auf Tool-Ebene zu erzwingen. Wenn der Agent versucht, ein Ziel zu erreichen, das nicht registriert ist, müssen Sie der Agentenidentität die Berechtigung iap.resources.egressViaIAP erteilen, indem Sie eine Richtlinie für einen nicht registrierten Endpunkt konfigurieren.
  • Agent Gateway: Das Gateway muss mit einer Autorisierungsrichtlinie verknüpft sein, die explizit auf das Gateway abzielt. Standardmäßig verwendet das Gateway IAP und Model Armor, um Anfragen zu schützen.
  • Delegierte Autorisierung mit Diensterweiterungen: Sie können Autorisierungsentscheidungen mithilfe von Diensterweiterungen an eine benutzerdefinierte Autorisierungs-Engine delegieren. Je nach konfigurierter Autorisierungsrichtlinie wird der Antrag von einer oder mehreren dieser Autorisierungs-Engines zugelassen oder abgelehnt.

Allgemeine Probleme

Sehen Sie sich diese häufigen Probleme und ihre Lösungen an, wenn Sie Fehler im Agent Gateway beheben.

Fehler beim Starten der Agent Runtime

Wenn Ihre Agent Runtime-Instanzen nicht gestartet oder bereitgestellt werden können, kann das daran liegen, dass entweder IAP den internen Traffic blockiert oder Ihrem Agent die grundlegenden Rollen fehlen, die er für die Initialisierung benötigt.

  1. Prüfen, ob IAP Aufrufe an interne Dienste blockiert

    Symptom: 403 Forbidden-Fehler beim Start.

    Ursache: Agent Gateway verwendet für den gesamten Traffic eine Standardrichtlinie zum Ablehnen. Wenn IAP im Erzwingungsmodus ist, werden daher auch Aufrufe an interne Dienste (z. B. aiplatform oder logging) blockiert, sofern sie nicht registriert sind und der Agent die erforderlichen IAM-Berechtigungen hat.

    Behebung: Stellen Sie IAP vorübergehend auf den Probelaufmodus um, um zu sehen, welche Verbindungen fehlschlagen, ohne den Start zu blockieren. Alternativ können Sie Cloud Logging abfragen, um die genau blockierten Hostnamen zu ermitteln. Nachdem Sie die Hostnamen der Zieldienste identifiziert haben, registrieren Sie sie in der Agent Registry und weisen Sie dem Agenten die Berechtigung iap.resources.egressViaIAP zu.

    Wenn Sie bestimmte blockierte Hostnamen mit Cloud Logging finden möchten, führen Sie die folgende Abfrage im Log-Explorer aus:

    resource.type="networkservices.googleapis.com/Gateway"
resource.labels.gateway_type="SECURE_WEB_GATEWAY"
httpRequest.status=403

    Sehen Sie sich die Felder httpRequest.requestUrl oder jsonPayload.authzPolicyInfo in den Ergebnissen an, um die Zielhostnamen zu finden.

    Zu den gängigen internen Diensten, die beim Start registriert werden müssen, gehören:

    • Agent Platform (Reasoning Engine und Sessions): https://REGION-aiplatform.mtls.googleapis.com
    • Resource Manager: https://cloudresourcemanager.mtls.googleapis.com und https://cloudresourcemanager.mtls.googleapis.com/
    • Google Cloud Observability (falls aktiviert): https://telemetry.mtls.googleapis.com/
    • Cloud Logging (falls aktiviert): https://logging.googleapis.com/
    • Cloud Monitoring: https://monitoring.googleapis.com/ und https://monitoring.mtls.googleapis.com/
    • Cloud Trace: https://cloudtrace.googleapis.com/ und https://cloudtrace.mtls.googleapis.com/
    • Secret Manager: https://secretmanager.googleapis.com/ und https://secretmanager.mtls.googleapis.com/

  2. Bestätigen, dass die Agent-Identität die erforderlichen grundlegenden Rollen hat

    Symptome: In den aiplatform.googleapis.com/reasoning_engine_stderr-Logs werden Fehler wie google.api_core.exceptions.Unknown: None oder Failed to convert project number to project ID angezeigt. Der Fehler tritt beim Start der Reasoning Engine auf.

    Ursache: Der Identität des KI-Agenten fehlt die Berechtigung resourcemanager.projects.get, die zum Auflösen des Projektnamens bei der Initialisierung erforderlich ist.

    Korrigieren: Achten Sie darauf, dass die Agentenidentität (oder die zugehörige Hauptkontogruppe) die erforderlichen Berechtigungen zum Lesen der eigenen Laufzeitkonfiguration hat. Die folgenden Rollen sind erforderlich:

    • roles/aiplatform.agentDefaultAccess: Standardmäßige Agentenrolle.
    • roles/aiplatform.user: Erforderlich, um den Agenten auszuführen.
    • roles/agentregistry.viewer: Erforderlich, um registrierte Ressourcen anzusehen.
    • roles/logging.logWriter und roles/monitoring.metricWriter: Für die Beobachtbarkeit erforderlich.
    • roles/browser: Erforderlich, um resourcemanager.projects.get während der SDK-Initialisierung auszuführen.

    Führen Sie den folgenden Befehl aus, um die der Agentenidentität zugewiesenen Rollen zu prüfen:

    gcloud projects get-iam-policy PROJECT_ID \
--flatten="bindings[].members" \
--filter="bindings.members:AGENT_IDENTITY_PRINCIPAL"

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Ihre Cloud de Confiance Projekt-ID
    • AGENT_IDENTITY_PRINCIPAL: Das Agent Identity-Hauptkonto. Verwendet das Format: principal://TRUST_DOMAIN/resources/SERVICE/RESOURCE_PATH

    Informationen zum Zuweisen von Rollen finden Sie unter Agent Identity mit Agent Runtime verwenden.

403 Forbidden Fehler

Wenn ein 403 Forbidden-Fehler auftritt, prüfen Sie, ob er sich auf den Agent Gateway-Ausgang bezieht. Hier ist ein Beispiel für eine Fehlermeldung für ausgehenden Traffic:

{"code": 403, "message": "403 Forbidden. {'message': 'Egress request is not authorized.', 'status': 'Forbidden'}"}

Fragen Sie die Agenten-Logs in Logging ab, um die fehlgeschlagenen Aufrufe zu finden:

resource.type="aiplatform.googleapis.com/ReasoningEngine"
resource.labels.location="LOCATION"
resource.labels.reasoning_engine_id="AGENT_ID"
textPayload:"403"

Ersetzen Sie Folgendes:

  • LOCATION: Die Region, in der der Agent bereitgestellt wird, z. B. us-central1.
  • AGENT_ID: Die ID des Agenten (Reasoning Engine).

Suchen Sie im textPayload des Logeintrags nach der Meldung Egress request is not authorized. Wenn der 403-Fehler anderen Text enthält, lehnt der Zieldienst den Aufruf möglicherweise direkt ab und nicht Agent Gateway.

Sie können sich auch Logs für ausgehenden Traffic, einschließlich 403-Ablehnungen, im integrierten Beobachtbarkeits-Dashboard ansehen.

Verbindung zu selbst signierten oder privaten CA-Zielen schlägt fehl

  • Symptom:Der Agent kann keine Verbindung zu Zielen herstellen, die selbstsignierte oder von einer privaten Zertifizierungsstelle ausgestellte Zertifikate präsentieren.
  • Ursache:Standardmäßig vertraut Agent Gateway nur Zertifikaten, die von öffentlich vertrauenswürdigen Zertifizierungsstellen ausgestellt wurden. Für Verbindungen zu Zielen, die private Zertifizierungsstellen oder selbstsignierte Zertifikate verwenden, ist eine zusätzliche Konfiguration erforderlich.
  • Abhilfe: Wenn Sie eine Verbindung zu Zielen mit privaten Zertifizierungsstellen oder selbst signierten Zertifikaten herstellen möchten, müssen Sie benutzerdefinierte TLS-Vertrauensanker mit der Einstellung tlsConfig in einer Agent-Verbindungsvorlage konfigurieren.

Agent, der mit benutzerdefiniertem Container (BYOC) bereitgestellt wurde, kann keine Verbindung zum Agent Gateway herstellen

  • Symptom: Der BYOC-Agent kann keine Verbindungen herstellen, wenn er über das Agent Gateway geleitet wird. In den Logs werden möglicherweise TLS-Handshake- oder Zertifikatsprüfungsfehler angezeigt.
  • Ursache:Der benutzerdefinierte Container des KI-Agenten vertraut der Zertifizierungsstelle des Agent Gateway nicht.
  • Lösung:Achten Sie darauf, dass Sie das Root-Zertifikat des Agent-Gateways dem CA-Speicher Ihres Containers hinzugefügt haben. Weitere Informationen finden Sie unter Benutzerdefinierte Container-Agenten (BYOC) für Agent Gateway konfigurieren.

Richtlinienbindung schlägt fehl oder ähnelt einer Governance-Ablehnung

  • Symptom: Konfigurationen für Richtlinienbindungen schlagen fehl, Sie werden beim Binden von Richtlinien interaktiv zur Eingabe eines etag aufgefordert oder Anfragen schlagen mit einem falschen Governance-Ablehnungsfehler fehl (z. B. „Nicht registriertes Ziel korrekt abgelehnt“).
  • Ursache:Die Identity-Aware Proxy API (iap.googleapis.com) ist in Ihrem Projekt deaktiviert.
  • Lösung:Aktivieren Sie die Identity-Aware Proxy API.

Fehler bei der Verwaltung von Agent Gateway mit der Mitarbeiteridentitätsföderation

Dieses Problem kann auftreten, wenn Sie Agent Gateway in derCloud de Confiance -Konsole verwalten oder die gcloud CLI verwenden, wenn Sie mit der Mitarbeiteridentitätsföderation (Workforce Identity Federation, WIF) authentifiziert sind.

In der Console werden allgemeine Lade- oder Erstellungsfehler wie die folgenden angezeigt:

  • „Beim Laden ist ein Fehler aufgetreten…“
  • „Der Server konnte Ihre Anfrage nicht verarbeiten.“
  • „Agenten-Gateway konnte nicht erstellt werden“
  • „Konnte nicht geladen werden“

Außerdem können gcloud-Befehle (z. B. gcloud network-services agent-gateways import) einen internen Fehler wie error 13: an internal error has occurred zurückgeben.

Um dieses Problem zu beheben, authentifizieren Sie sich mit einem Standard-Google-Konto, das über Cloud Identity oder Google Workspace verwaltet wird und die erforderlichen Berechtigungen hat, z. B. roles/networkservices.admin.

Föderierte Identitäten werden in der Vorschau nur eingeschränkt von den Diensten Agent Platform Governance und Gateway unterstützt. Das Problem wird nicht behoben, wenn Sie einem föderierten Hauptkonto umfassendere IAM-Rollen zuweisen.

Debugging-Workflow

Wenn eine der im Ablauf für Ausstiegsanfragen beschriebenen Bedingungen fehlt, werden Ihre Anfragen möglicherweise blockiert.

IAP-Entscheidung prüfen

Wenn Sie Ihre Log-Suche auf IAP-Ausgangsentscheidungen eingrenzen möchten, führen Sie die folgende Abfrage in Logging aus:

protoPayload.serviceName="iap.googleapis.com"
protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
protoPayload.metadata.mcp_attributes.base_protocol_method="true"

Wenn Sie überhaupt keinen passenden IAP-Logeintrag sehen, hat das Gateway die Anfrage möglicherweise abgelehnt, bevor IAP sie ausgewertet hat. Fahren Sie mit dem nächsten Schritt fort.

Wenn Sie einen passenden Logeintrag finden, prüfen Sie die folgenden Felder:

  • protoPayload.authorizationInfo[].granted: Gibt an, ob die Anfrage zulässig (true) oder abgelehnt (false) wurde.
  • protoPayload.authenticationInfo.principalSubject: Die SPIFFE-ID oder principal://...-Identität des Aufrufers. Prüfen Sie, ob diese mit der Identität Ihres Agenten übereinstimmt.
  • protoPayload.authorizationInfo[].resource: Die registrierte Zielressource, zu der der Aufruf aufgelöst wurde.
  • labels."iap.googleapis.com/audited_resource_name": Wenn dieser Wert unregisteredResource ist, ist der Ziel-Hostname nicht registriert. Registrieren Sie den Ziel-Hostname in der Agent-Registrierung und achten Sie darauf, dass der Agent die Berechtigung iap.resources.egressViaIAP für dieses Ziel hat.
  • Durchsetzungsmodus: Sehen Sie sich den Durchsetzungsmodus der Anfrage an. Wenn Sie nach Probelaufanfragen filtern möchten, können Sie der Abfrage protoPayload.metadata.iamEnforcementMode="DRY_RUN" hinzufügen. Im Modus DRY_RUN protokolliert IAP Ablehnungen, erzwingt sie aber nicht. Wenn der Agent also im Probebetriebsmodus mit einem 403-Fehler fehlschlägt, stammt die Ablehnung wahrscheinlich entweder vom Egress-Proxy des Gateways oder von der Zielressource.

Entscheidung des KI-Agenten-Gateways prüfen

Wenn Sie sehen möchten, wie das Agent Gateway die Anfrage bewertet hat, fragen Sie die Gateway-Logs in Logging ab. In diesem Beispiel filtern wir die Logs nur nach 403-Fehlern:

resource.type="networkservices.googleapis.com/Gateway"
resource.labels.gateway_type="SECURE_WEB_GATEWAY"
resource.labels.location="REGION"
resource.labels.gateway_name="AGENT_GATEWAY_NAME"
httpRequest.status=403
-httpRequest.requestMethod="CONNECT"

Prüfen Sie die folgenden Felder im entsprechenden Logeintrag:

  • jsonPayload.authzPolicyInfo.policies.result: Das Autorisierungsergebnis insgesamt, entweder ALLOWED oder DENIED.
  • httpRequest.requestUrl: Notieren Sie die genaue Ziel-URL, die der Agent aufzurufen versucht hat. Im nächsten Schritt wird geprüft, ob der von der Zielressource verwendete Hostname in der Agent Registry registriert wurde.

Registrierung des Ziels und Abdeckung der IAM-Zugriffsrichtlinie prüfen

Für den Zugriff auf Ziele ist immer eine IAM-Zulassungsrichtlinie erforderlich, die der Agentenidentität die Berechtigung iap.resources.egressViaIAP gewährt. Die Registrierung von Zielen in der Agent Registry wird empfohlen, um detaillierte Zugriffsrichtlinien pro Ressource zu erzwingen und einen genauen Hostname-Abgleich zu gewährleisten. Prüfen Sie bei nicht registrierten Zielen, ob eine Richtlinie für nicht registrierte Endpunkte der Agentenidentität die erforderliche Berechtigung gewährt.

Wenn Sie ressourcenspezifische Richtlinien verwenden, muss jeder Zielhostname und jede Variante des Hostnamens, die der Agent zu erreichen versucht, in der Agent Registry registriert sein. Das liegt daran, dass eine Google-API wie aiplatform.googleapis.com je nach SDK-Version, regionaler Clientkonfiguration oder mTLS-Verwendung über mehrere Hostnamen aufgelöst werden kann (z. B. us-central1-aiplatform.googleapis.com oder us-central1-aiplatform.mtls.googleapis.com).

Da das Gateway Hostnamen genau abgleicht, wird die Anfrage abgelehnt, wenn Sie aiplatform.googleapis.com registrieren, der Agent aber us-central1-aiplatform.googleapis.com aufruft, da das Gateway die Ressource als nicht registriert betrachtet.

Führen Sie das folgende Beispielskript aus, um Ihre Registrierungseinträge nach Ressourcentyp aufzulisten und die Einträge für den spezifischen Hostnamen zu prüfen, der vom Aufruf des Agents verwendet wird:

HOSTNAME="HOSTNAME"
PROJECT_ID="PROJECT_ID"
LOCATION="REGION"

echo "Checking Endpoints..."
gcloud agent-registry endpoints list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

echo "Checking MCP Servers..."
gcloud agent-registry mcp-servers list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

echo "Checking Agents..."
gcloud agent-registry agents list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

Ersetzen Sie Folgendes:

  • HOSTNAME: Der Zielhostname, den der Agent zu erreichen versucht, z. B. us-central1-aiplatform.mtls.googleapis.com.
  • PROJECT_ID: Ihre Cloud de Confiance Projekt-ID
  • REGION: Der Speicherort Ihrer Agent Registry- und Agent Gateway-Ressourcen, z. B. us-central1.

Ausgabe 1: Hostname ist bereits registriert

Wenn der Hostname in einem Agent-Registry-Eintrag vorhanden ist, sieht die Ausgabe in etwa so aus:

Checking Endpoints...
  url: https://us-central1-aiplatform.mtls.googleapis.com
Checking MCP Servers...
Checking Agents...

Fahren Sie mit IAM-Bindungen für die Zielressource prüfen fort, um zu prüfen, ob eine ressourcenspezifische oder registryweite Richtlinie Zugriff auf die Agent-Identität gewährt.

Ausgabe 2: Hostname ist nicht in der Registry vorhanden

Wenn der Hostname nicht in der Registry vorhanden ist, sieht die Ausgabe in etwa so aus:

Checking Endpoints...
Checking MCP Servers...
Checking Agents...

Wenn Sie Richtlinien pro Ressource oder für die gesamte Registry verwenden möchten, registrieren Sie das Ziel zuerst in Agent Registry. Wenn Sie Richtlinien für nicht registrierte Endpunkte verwenden, fahren Sie mit IAM-Bindungen für die Zielressource überprüfen fort.

IAM-Bindungen für die Zielressource prüfen

Die Agentenidentität oder die zugehörige Hauptkontogruppe muss die Berechtigung iap.resources.egressViaIAP für das Ziel haben.

Sie können Richtlinienbindungen für drei Bereiche konfigurieren:

  • Registry-weit: Zugriff auf alle in der Registry registrierten KI-Agenten, MCP-Server und Endpunkte.
  • Pro Ressource: Zugriff einschränken. Eine ressourcenspezifische Bindung ersetzt die registryweite Bindung für diese bestimmte Ressource, anstatt mit ihr zusammengeführt zu werden.
  • Richtlinien für nicht registrierte Endpunkte: Zugriff auf Ziele, die nicht in Agent Registry registriert sind.

Verwenden Sie eines der folgenden Beispiele, um nach Bindungen zu suchen:

  • Führen Sie den folgenden Befehl aus, um nach IAM-Richtlinienbindungen auf Registrierungsebene zu suchen:

    curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry:getIamPolicy" \
-H "Content-Type: application/json"

  • Führen Sie den folgenden Befehl aus, um nach IAM-Richtlinienbindungen pro Endpunkt zu suchen:

    export HOSTNAME=HOSTNAME

ENDPOINT_ID=$(gcloud agent-registry endpoints list \
--project="PROJECT_ID" \
--location="REGION" \
--filter="interfaces.url:$HOSTNAME" \
--format="value(name.basename())")

echo "ENDPOINT_ID=$ENDPOINT_ID"

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/endpoints/${ENDPOINT_ID}:getIamPolicy"

    Ersetzen Sie HOSTNAME durch den Hostnamen des Ziels, das der Agent erreichen möchte, z. B. us-central1-aiplatform.mtls.googleapis.com.

  • Führen Sie den folgenden Befehl aus, um nach IAM-Richtlinienbindungen pro MCP-Server zu suchen:

    export MCP_SERVER=MCP_SERVER

MCP_SERVER_ID=$(gcloud agent-registry mcp-servers list \
--project="PROJECT_ID" \
--location="REGION" \
--filter="interfaces.url:$MCP_SERVER" \
--format="value(name.basename())")

echo "MCP_SERVER_ID=$MCP_SERVER_ID"

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/mcpServers/${MCP_SERVER_ID}:getIamPolicy"

    Ersetzen Sie MCP_SERVER durch die URL des MCP-Servers (z. B. https://example-abc12345-uc.a.run.app/mcp).

Suchen Sie in den zurückgegebenen Richtlinieninformationen nach einer Bindung mit der Berechtigung iap.resources.egressViaIAP, die mit der Identität oder dem Hauptkontensatz des Agents übereinstimmt. Wenn die zurückgegebene Ausgabe ein "etag"-Feld, aber keine Bindungen enthält, bedeutet das, dass keine IAM-Richtlinie vorhanden ist.

Wenn eine Bindung vorhanden ist, aber eine condition enthält, prüfen Sie, ob der CEL-Ausdruck (Common Expression Language) den Agent ausschließt. Eine Bedingung, die nach einem Attribut filtert, das dem KI-Agenten fehlt, schließt den KI-Agenten möglicherweise stillschweigend aus.

Wenn das Ziel keine übereinstimmende Richtlinienbindung hat, die Ihrer Agentenidentität oder Ihrem Hauptkontosatz die Berechtigung iap.resources.egressViaIAP gewährt, gewähren Sie die Berechtigung mit einer der folgenden Richtlinienoptionen:

Autorisierungsrichtlinie und ‑erweiterung prüfen

In diesem Abschnitt prüfen wir, ob eine Autorisierungsrichtlinie vorhanden ist, die explizit auf das Agent-Gateway abzielt, das dem Agent zugeordnet ist.

  1. Rufen Sie die Details der Autorisierungserweiterung ab, die mit dem Gateway verknüpft ist, und prüfen Sie, ob die verwendete Erweiterung wie erwartet konfiguriert ist.

    gcloud service-extensions authz-extensions describe AUTHORIZATION_EXTENSION_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

    Ersetzen Sie AUTHORIZATION_EXTENSION_NAME durch den Namen der Erweiterung, die dem Gateway zugeordnet ist. Wenn Sie den Namen der Erweiterung nicht kennen, können Sie in der Cloud de Confiance Cloud de Confiance -Konsole die Detailseite des Gateways aufrufen und den Wert des Felds Name der Erweiterung unter „Diensterweiterungen“ notieren.

  2. Prüfen Sie, ob eine Autorisierungsrichtlinie explizit auf die Gateway-Ressource ausgerichtet ist und mit derselben Autorisierungserweiterung verknüpft ist. Sie können in der Cloud de Confiance Cloud de Confiance Console zur Detailseite des Gateways navigieren und sich unter „Service Extensions“ (Diensterweiterungen) den Wert des Felds Policy name (Richtlinienname) notieren.

    Wenn keine Richtlinie auf das Gateway ausgerichtet ist oder die Zuordnung von Gateway zu Richtlinie falsch ist, wird die Autorisierungserweiterung nicht ausgeführt.

Principal Access Boundary-Richtlinien prüfen

Principal Access Boundary-Richtlinien haben Vorrang vor IAM-Zulassungsrichtlinien. Das bedeutet: Selbst wenn Sie alle IAM-Bindungen richtig konfiguriert haben, schlägt eine Anfrage fehl, wenn es eine aktive Richtlinie für die Principal Access Boundary-Richtlinie gibt, die die Zielressource aus dem Bereich des Agents ausschließt.

Führen Sie Folgendes aus, um organisationsweite Richtlinien aufzulisten:

gcloud iam principal-access-boundary-policies list \
  --organization="ORGANIZATION_ID" \
  --location=global

So finden Sie Richtlinien, die an den Hauptkontosatz des Agents gebunden sind:

gcloud iam policy-bindings search-target-policy-bindings \
  --project="PROJECT_ID" \
  --target="PRINCIPAL_SET"

Ersetzen Sie Folgendes:

  • ORGANIZATION_ID: Ihre Organisations-ID von Cloud de Confiance .
  • PROJECT_ID: Ihre Cloud de Confiance Projekt-ID
  • PRINCIPAL_SET: Die Gruppe von Identitäten des Agenten.

Wenn eine Bindung vorhanden ist, prüfen Sie das Feld details.rules[].resources[], um zu bestätigen, dass das Ziel für Ihren Agenten infrage kommt.

Prinzipal- und Prinzipalgruppenbindungen testen

Wenn Berechtigungen nicht konsistent funktionieren oder unerwartet fehlschlagen, liegt das Problem möglicherweise an der Konfiguration der Gruppenidentität Ihres Agents (der Principal-Gruppe). Hauptkontobasierte Berechtigungen können aus folgenden Gründen fehlschlagen:

  • Synchronisierungsverzögerungen: Wenn Sie einem Set eine Identität hinzufügen, kann es einige Minuten dauern, bis IAM aktualisiert wird und das neue Mitglied erkennt.
  • Fehlende Attribute: Wenn für die Mitgliedschaft in einer Hauptkontengruppe bestimmte Attribute erforderlich sind, muss die Identität des KI-Agenten genau diese Attribute aufweisen (z. B. Abteilungs- oder Teamlabels). Wenn diese Attribute in der Identität fehlen, wird der Agent möglicherweise ohne Benachrichtigung aus der Gruppe ausgeschlossen.

Um zu testen, ob die Gruppenmitgliedschaft das Problem ist, erteilen Sie dem jeweiligen Agenten Berechtigungen direkt, indem Sie eine direkte principal://-Bindung für die betroffene Ressource hinzufügen. Wenn der Agent eine Verbindung über die direkte Bindung herstellen kann, liegt die Ursache wahrscheinlich in einer Attributabweichung oder einer Synchronisierungsverzögerung mit dem Hauptkonto. Um dieses Problem zu beheben, überprüfen und korrigieren Sie die Identitätsattribute des Kundenservicemitarbeiters oder verwenden Sie direkte principal://-Bindungen.

Nächste Schritte

Codelab

Hier erfahren Sie, wie Sie agentische Arbeitslasten mit Agent Gateway auf der Gemini Enterprise Agent Platform verwalten.

Leitfaden

Informationen zum Überwachen des KI-Agenten-Gateways