Traffic der Laufzeit für KI-Agenten über das Agent Gateway weiterleiten

Auf dieser Seite wird beschrieben, wie Sie den Traffic der Agent Runtime über das Agent Gateway weiterleiten. Das Agent Gateway ist eine zentrale Netzwerk- und Sicherheitskomponente des Ökosystems der Gemini Enterprise Agent Platform. Es bietet sichere und verwaltete Verbindungen für alle Interaktionen zwischen KI-Agenten, unabhängig davon, ob sie zwischen Nutzern und KI-Agenten, KI-Agenten und Tools oder zwischen KI-Agenten selbst stattfinden.

Hinweis

  • Machen Sie sich mit der Bereitstellung von KI-Agenten in der Agent Runtime vertraut.

  • Informationen zum KI-Agenten-Gateway Sie können Agent Gateway im Agent-to-Anywhere-Modus (Egress) verwenden, um die gesamte ausgehende Kommunikation mit ausgehendem Traffic zu Tools, Modellen, APIs und anderen Agents zu sichern und zu steuern. Sie verwenden das Gateway im Client-zu-Agent-Modus (Ingress), um zu steuern, welche Clients auf Ihre Agenten zugreifen können. Über das Gateway können Sie auswählen, welche IAP-Richtlinien und Model Armor-Vorlagen auf diese Interaktionen angewendet werden müssen.

    Eine einzelne Runtime-Instanz kann gleichzeitig an ein Agent-to-Anywhere-Gateway (Ausgang) und ein Client-to-Agent-Gateway (Eingang) gebunden werden.

  • Lesen Sie die Einschränkungen für Runtime-Bereitstellungen, die mit Agent Gateway verknüpft sind.

Agent Runtime-Traffic über Agent Gateway weiterleiten

So leiten Sie den Agent Runtime-Traffic über das Agent Gateway weiter:

  1. Agent-Gateway erstellen

    Erstellen Sie eine Agent Gateway-Ressource und hängen Sie bei Bedarf Autorisierungsrichtlinien an. Sie können ein Gateway entweder im Agent-to-Anywhere-Modus (Egress) oder im Client-to-Agent-Modus (Ingress) erstellen.

    • Im Client-to-Agent-Modus (Ingress) müssen der Agent und das Gateway im selben Projekt und in derselben Region erstellt werden.
    • Im Agent-to-Anywhere-Modus (Ausgang) kann das Gateway in einem anderen Projekt als der Agent erstellt werden, muss aber in derselben Region erstellt werden. Alle zugehörigen Agent Registry-Registrierungen und IAM-Richtlinienbindungen müssen im selben Projekt wie das Agent Gateway erstellt werden.

    Eine Anleitung finden Sie unter Agent Gateway einrichten.

    Achten Sie darauf, dass das Gateway entsprechend den Anforderungen Ihrer Bereitstellung konfiguriert ist. Wenn Ihr Agent beispielsweise LLM-Zugriff benötigt, konfigurieren Sie das Gateway so, dass dieser Zugriff zulässig ist, um potenzielle Fehler bei der Bereitstellung der Agent Runtime zu vermeiden.

  2. Optional: Projektübergreifenden Zugriff auf das Egress-Gateway konfigurieren

    Wenn sich Ihr Agent-to-Anywhere-Gateway (ausgehend) in einem anderen Projekt als Ihr Laufzeit-Agent befindet, führen Sie die folgenden Schritte aus, um dem Laufzeit-Dienst-Agent Zugriff auf das Projekt des Gateways für ausgehenden Traffic zu gewähren:

    1. Erstellen Sie eine benutzerdefinierte IAM-Rolle im Agent Gateway-Projekt:

      gcloud iam roles create ar_agw_cross_project_sa \
  --project=AGENT_GATEWAY_PROJECT_ID \
  --title="Runtime Agent Gateway Cross-Project SA" \
  --description="Custom role for the cross-project service agent to access Agent Gateway" \
  --permissions="networkservices.agentGateways.get,networkservices.operations.get"

      Ersetzen Sie AGENT_GATEWAY_PROJECT_ID durch die Projekt-ID, unter der das Agent-Gateway bereitgestellt ist.

    2. Weisen Sie dem Agent Runtime-Dienst-Agent des Agent-Projekts die benutzerdefinierte Rolle im Gateway-Projekt zu:

      gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
  --member="serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="projects/AGENT_GATEWAY_PROJECT_ID/roles/ar_agw_cross_project_sa"

      Ersetzen Sie AGENT_RUNTIME_PROJECT_NUMBER durch die Projektnummer des Projekts, in dem der Runtime-Agent bereitgestellt wird.

  3. KI-Agenten so konfigurieren, dass Traffic über das KI-Agenten-Gateway weitergeleitet wird

    Je nachdem, ob Sie einen neuen Agent bereitstellen oder einen vorhandenen Agent konfigurieren, wählen Sie eine der folgenden Optionen aus:

    • Für neue Agents mit dem Python SDK

      Geben Sie die Gateway-Ressource an, während Sie den Agenten bereitstellen. Wenn Sie den KI-Agenten beispielsweise in der Agent Runtime bereitstellen möchten, verwenden Sie client.runtimes.create, um das local_agent-Objekt zusammen mit allen optionalen Konfigurationen zu übergeben.

      Wenn Sie Gateway-basierte Plattformfunktionen wie Model Armor oder Semantic Governance Policies mit diesem Agent verwenden möchten, legen Sie sowohl agent_gateway_config als auch identity_type=AGENT_IDENTITY im Erstellungsaufruf fest, wie in diesem Beispiel gezeigt. Das Backend erzwingt identity_type = "AGENT_IDENTITY" auf API-Ebene, wenn agent_gateway_config angegeben ist. Dadurch schlägt die Bereitstellungsvalidierung fehl, wenn die Identität der Laufzeitinstanz ausgelassen oder falsch konfiguriert ist.

      Agent zu beliebigem Ziel 

      remote_agent = client.runtimes.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME}
      },
      "identity_type": types.IdentityType.AGENT_IDENTITY,
      # Other optional configuration ...
      # "requirements": requirements,
      # "gcs_dir_name": gcs_dir_name,
      # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
      "env_vars": {
        "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
      }
  },
)

      Ersetzen Sie Folgendes:

      • AGENT_GATEWAY_PROJECT_ID: Die Projekt-ID, in der das Agent Gateway bereitgestellt wird
      • REGION: die Region, in der der Agent und das Gateway bereitgestellt werden
      • AGENT_GATEWAY_TO_ANYWHERE_NAME: der Name des Agent-Gateways, das Sie im Modus „Agent zu beliebigem Ziel (ausgehend)“ erstellt haben

      Client zu Agent 

      remote_agent = client.runtimes.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "client_to_agent_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME}
      },
      "identity_type": types.IdentityType.AGENT_IDENTITY,
      # Other optional configuration ...
      # "requirements": requirements,
      # "gcs_dir_name": gcs_dir_name,
      # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
      "env_vars": {
        "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
      }
  },
)

      Ersetzen Sie Folgendes:

      • PROJECT_ID: die Projekt-ID, in der der Agent und das Gateway bereitgestellt werden
      • REGION: die Region, in der der Agent und das Gateway bereitgestellt werden
      • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: der Name des Agent-Gateways, das Sie im Modus „Client zu Agent (eingehend)“ erstellt haben

    • Für neue Agents mit Terraform

      Wenn Sie Ihren KI-Agenten mit Terraform bereitstellen, verwenden Sie den Anbieter google-beta und konfigurieren Sie den Block agent_gateway_config in der Ressource google_vertex_ai_reasoning_engine. Weitere Informationen zur Terraform-Einrichtung finden Sie unter Agents mit Terraform bereitstellen.

      Agent zu beliebigem Ziel

      Verwenden Sie die folgende Terraform-Konfiguration, um einen Agent mit einem Agent-to-Anywhere-Gateway für den Egress zu verknüpfen.

      resource "google_vertex_ai_reasoning_engine" "agent" {
provider = google-beta

project      = "AGENT_RUNTIME_PROJECT_ID"
region       = "REGION"
display_name = "AGENT_DISPLAY_NAME"
description  = "AGENT_DESCRIPTION"

spec {
  identity_type = "AGENT_IDENTITY"

  container_spec {
    image_uri = "REGION-docker.pkg.dev/AGENT_RUNTIME_PROJECT_ID/REPOSITORY/IMAGE:TAG"
  }

  deployment_spec {
    agent_gateway_config {
      agent_to_anywhere_config {
        agent_gateway = "projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
      }
    }
  }
}
}

      Ersetzen Sie Folgendes:

      • AGENT_RUNTIME_PROJECT_ID: die Projekt-ID, in der der Agent bereitgestellt wird
      • REGION: die Region, in der der Agent und das Gateway bereitgestellt werden
      • AGENT_DISPLAY_NAME: der Anzeigename für Ihren Agent
      • AGENT_DESCRIPTION: eine Beschreibung Ihres Agenten
      • REPOSITORY: das Artifact Registry-Repository, das Ihr Container-Image enthält
      • IMAGE: der Name des Container-Images
      • TAG: das Container-Image-Tag
      • AGENT_GATEWAY_PROJECT_ID: Die Projekt-ID, in der das Agent Gateway bereitgestellt wird
      • AGENT_GATEWAY_TO_ANYWHERE_NAME: der Name des Agent-Gateways, das Sie im Modus „Agent zu beliebigem Ziel (ausgehend)“ erstellt haben

      Client zu Agent

      Verwenden Sie die folgende Terraform-Konfiguration, um einen Agenten mit einem Client-zu-Agent-Gateway für eingehenden Traffic zu verknüpfen.

      resource "google_vertex_ai_reasoning_engine" "agent" {
provider = google-beta

project      = "PROJECT_ID"
region       = "REGION"
display_name = "AGENT_DISPLAY_NAME"
description  = "AGENT_DESCRIPTION"

spec {
  identity_type = "AGENT_IDENTITY"

  container_spec {
    image_uri = "REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG"
  }

  deployment_spec {
    agent_gateway_config {
      client_to_agent_config {
        agent_gateway = "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
      }
    }
  }
}
}

      Ersetzen Sie Folgendes:

      • PROJECT_ID: die Projekt-ID, in der der Agent und das Gateway bereitgestellt werden
      • REGION: die Region, in der der Agent und das Gateway bereitgestellt werden
      • AGENT_DISPLAY_NAME: der Anzeigename für Ihren Agent
      • AGENT_DESCRIPTION: eine Beschreibung Ihres Agenten
      • REPOSITORY: das Artifact Registry-Repository, das Ihr Container-Image enthält
      • IMAGE: der Name des Container-Images
      • TAG: das Container-Image-Tag
      • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: Der Name des Agent-Gateways, das Sie im Modus „Client zu Agent (eingehend)“ erstellt haben.

    • Für vorhandene Agenten, die die REST API verwenden

      Agent zu beliebigem Ziel

      Verwenden Sie die folgende REST API-Anfrage, um einen vorhandenen Agenten für den Egress mit einem Agent-to-Anywhere-Gateway zu verknüpfen.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "spec": {
    "deploymentSpec": {
      "agentGatewayConfig": {
        "agentToAnywhereConfig": {
          "agentGateway": "projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      Ersetzen Sie Folgendes:

      • AGENT_GATEWAY_PROJECT_ID: die Projekt-ID, in der das Gateway bereitgestellt wird
      • AGENT_RUNTIME_PROJECT_ID: die Projekt-ID, in der der Agent bereitgestellt wird
      • REGION: die Region, in der der Agent und das Gateway bereitgestellt werden
      • AGENT_GATEWAY_TO_ANYWHERE_NAME: der Name des Agent-Gateways, das Sie im Modus „Agent zu beliebigem Ziel (ausgehend)“ erstellt haben
      • RESOURCE_ID: die Ressourcen-ID des Agenten

      Client zu Agent

      Verwenden Sie die folgende REST API-Anfrage, um einen vorhandenen Agenten einem Client-to-Agent-Gateway für den Ingress zuzuordnen.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "spec": {
    "deploymentSpec": {
      "agentGatewayConfig": {
        "clientToAgentConfig": {
          "agentGateway": "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      Ersetzen Sie Folgendes:

      • PROJECT_ID: die Projekt-ID, in der der Agent und das Gateway bereitgestellt werden
      • REGION: die Region, in der der Agent und das Gateway bereitgestellt werden
      • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: der Name des Agent-Gateways, das Sie in „Client zu Agent (eingehend)“ erstellt haben
      • RESOURCE_ID: die Ressourcen-ID des Agenten

  4. KI-Agenten in der Agent Registry registrieren

    Der Agent muss in derselben Agent Registry-Instanz im selben Projekt und in derselben Region wie das Agent Gateway registriert sein.

    gcloud agent-registry services create RUNTIME_AGENT_SERVICE_NAME \
  --project=AGENT_GATEWAY_PROJECT_ID \
  --location=REGION \
  --display-name="RUNTIME_AGENT_DISPLAY_NAME" \
  --endpoint-spec-type=no-spec \
  --interfaces=url="https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID",protocolBinding="jsonrpc" \
  --format="value(registryResource)"

    Ersetzen Sie Folgendes:

    • RUNTIME_AGENT_SERVICE_NAME: der Name, den Sie dem Agenteneintrag in der Registrierung geben möchten
    • AGENT_GATEWAY_PROJECT_ID: Die Projekt-ID, in der das Gateway bereitgestellt wird
    • REGION: die Region, in der der Agent und das Gateway bereitgestellt werden
    • RUNTIME_AGENT_DISPLAY_NAME: Der menschenlesbare Anzeigename des Agenteneintrags in der Registrierung.
    • RUNTIME_AGENT_PROJECT_NUMBER: die Projektnummer des Projekts, in dem der Runtime-Agent bereitgestellt wird
    • ENGINE_ID: die Ressourcen-ID des Agenten

    Weitere Informationen finden Sie unter Agents registrieren. Informationen zur manuellen Registrierung von Agenten in Konfigurationen mit mehreren Projekten finden Sie unter Agenten aus einem anderen Projekt registrieren.

  5. IAM-Richtlinienbindung für Agent-zu-Registry erstellen

    Führen Sie diesen Schritt im selben Projekt und in derselben Region wie das Agent-Gateway aus.

    gcloud iap web add-iam-policy-binding \
  --resource-type=agent-registry \
  --endpoint=AGENT_ENDPOINT_ID \
  --region=REGION \
  --project=AGENT_GATEWAY_PROJECT_ID \
  --member=MEMBER \
  --role=roles/iap.egressor

    Ersetzen Sie Folgendes:

    • AGENT_ENDPOINT_ID: Die Dienstendpunkt-ID des registrierten KI-Agenten. Sie erhalten diese aus der Ausgabe des vorherigen Schritts.

    • MEMBER: Das Hauptkonto der Agentenidentität, dem die Rolle zugewiesen werden soll. Das Format für eine einzelne Reasoning Engine ist: principal://TRUST_DOMAIN/resources/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID.

      Wenn Sie allen Agents in einem Projekt oder in der gesamten Organisation Egress-Zugriff gewähren möchten, anstatt einzelne Instanzen zu binden, können Sie die IAM-Richtlinie an einen Hauptkontensatz binden:

      • So gewähren Sie Zugriff auf alle Agents in einem Projekt: principalSet://TRUST_DOMAIN/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER
      • So gewähren Sie allen Agents in der Organisation Zugriff: principalSet://TRUST_DOMAIN/*

      In diesen Hauptkontostrings ist TRUST_DOMAIN normalerweise agents.global.org-ORGANIZATION_ID.system.id.goog.

  6. Wichtige APIs für Laufzeitvorgänge auf die Zulassungsliste setzen

    Der KI-Agenten-Traffic wird jetzt über das Agent Gateway weitergeleitet. Agent Gateway verwendet jedoch eine Standardablehnungsrichtlinie. Damit bestimmte Funktionen der Agent Platform genutzt werden können, muss der Agent mit den folgenden Endpunkten kommunizieren können:

    Der Hostname-Abgleich im Agent Gateway ist exakt. Platzhalter wie *.googleapis.com oder Präfixformen werden nicht unterstützt. Sie müssen jede Standard-, regionale und sichere (mTLS) Hostnamenvariante registrieren, in die Ihr Agent-SDK oder Ihre Clientanwendung aufgelöst wird.

    Damit bestimmte Agent Platform-Funktionen aktiviert werden können und Initialisierung und Telemetrie erfolgreich sind, müssen Sie Traffic zu den folgenden Endpunkten in der Agent Registry zulassen:

    Wichtige Plattformendpunkte

    In der folgenden Tabelle sind die wichtigsten Plattformendpunkte aufgeführt, die Ihre Agents für Standardvorgänge, Tracing, Logging und Metadatenauflösung benötigen:

    Dienstname Standard-Hostname mTLS-Hostname Regionale und andere Varianten
    Agent Registry agentregistry.googleapis.com – –
    Cloud Logging logging.googleapis.com logging.mtls.googleapis.com –
    Cloud Trace / Telemetrie telemetry.googleapis.com telemetry.mtls.googleapis.com –
    Trace API cloudtrace.googleapis.com cloudtrace.mtls.googleapis.com –
    Cloud Monitoring monitoring.googleapis.com monitoring.mtls.googleapis.com –
    Secret Manager secretmanager.googleapis.com secretmanager.mtls.googleapis.com –
    Resource Manager cloudresourcemanager.googleapis.com cloudresourcemanager.mtls.googleapis.com –
    IAM-Anmeldedaten iamcredentials.googleapis.com iamcredentials.mtls.googleapis.com –
    Agent Platform (aiplatform) aiplatform.googleapis.com aiplatform.mtls.googleapis.com REGION-aiplatform.googleapis.com
    REGION-aiplatform.mtls.googleapis.com
    aiplatform.REGION.rep.googleapis.com

    Funktionsspezifische Endpunkte

    Wenn Ihre Agents Funktionen wie Sitzungen oder Memory Bank verwenden, müssen Sie außerdem dafür sorgen, dass die Agents mit den spezifischen Endpunkten kommunizieren können, die von diesen Diensten verwendet werden:

    • Für Sitzungen: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/sessions
    • Für Memory Bank: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/memories

    Aus Sicherheitsgründen empfehlen wir, nur die spezifischen URIs zu registrieren und auf die Zulassungsliste zu setzen, auf die der Agent zugreift. Da das Gateway Hostnamen direkt abgleicht, müssen Sie alle Varianten registrieren, die vom Agent-SDK verwendet werden. Je nach SDK-Version, regionaler Clientkonfiguration oder mTLS-Nutzung kann eine Google API beispielsweise über die folgenden Endpunkthostnamen aufgelöst werden:

    • https://REGION-aiplatform.googleapis.com
    • https://REGION-aiplatform.mtls.googleapis.com
    • https://aiplatform.REGION.rep.googleapis.com

    Informationen zum Registrieren von Endpunkten finden Sie unter Endpunkte registrieren. Wenn Sie mehrere Projekte haben, können Sie mehrere Google-Kern-API-Endpunkte in einem einzigen Agent Registry-Dienst registrieren. Weitere Informationen finden Sie unter Zusammengesetzten Google APIs-Endpunkt registrieren. Außerdem müssen Sie darauf achten, dass der Agent die Berechtigung iap.resources.egressViaIAP für diese Endpunkte hat. Eine Anleitung finden Sie unter Egress-Richtlinie für Agent-zu-Endpoint erstellen.

  7. Agent-Konfiguration überprüfen

    Console

    1. Rufen Sie in der Google Cloud Console die Seite Bereitstellungen der Agent-Plattform auf.

      Zu Deployments

    2. Klicken Sie auf den Namen des bereitgestellten Agents.

    3. Klicken Sie auf Dienstkonfiguration. Der Bereich Beobachtbarkeit für den Agent wird geöffnet.

    4. Klicken Sie auf Bereitstellungsdetails. Die Ingress- und Egress-Konfigurationen des KI-Agenten-Gateways sind im Feld Bereitstellungsspezifikation verfügbar.

    gcloud

    Verwenden Sie die folgende REST API-Anfrage, um zu prüfen, ob der Agent jetzt mit dem Gateway verknüpft ist. Wenn die zurückgegebene Ausgabe null lautet, konnte die Laufzeit nicht an das Gateway gebunden werden.

    curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \
  | jq '.spec.deploymentSpec.agentGatewayConfig'

    Ersetzen Sie Folgendes:

    • AGENT_RUNTIME_PROJECT_ID: die Projekt-ID
    • REGION: die Region, in der der Agent bereitgestellt wird
    • RESOURCE_ID: die Ressourcen-ID des Agenten

Benutzerdefinierte Container-Agents (BYOC) für das KI-Agenten-Gateway konfigurieren

Wenn Sie ausgehenden Traffic über ein Agent-to-Anywhere-Agent-Gateway (ausgehend) für einen KI-Agenten weiterleiten möchten, der mit einem benutzerdefinierten Container-Image (Bring Your Own Container / BYOC) bereitgestellt wurde, müssen Sie das Zertifikat der Root-Zertifizierungsstelle des Gateways in den Trust Store des benutzerdefinierten Container-Images einbinden.

Da Agent Gateway die TLS-Entschlüsselung und -Prüfung für ausgehende Agent-Kommunikation durchführt, wird das Zertifikat der Zertifizierungsstelle bei Agent-Bereitstellungen, die nicht auf BYOC (Quellcode-basiert) basieren, automatisch während der Image-Erstellung eingefügt. Bei benutzerdefinierten Container-Images müssen Sie das CA-Zertifikat des Gateways explizit abrufen, es im System-CA-Truststore in Ihrem Dockerfile installieren und die Umgebungsvariablen für das Zertifikats-Bundle festlegen, die von Python-SDKs, HTTP-Clientbibliotheken und gRPC benötigt werden.

So konfigurieren Sie ein BYOC-Container-Image für ausgehenden Traffic über das Agent-Gateway:

  1. Rufen Sie die Root-Zertifikate aus der Agent Gateway-Ressource ab.

    Exportieren Sie den PEM-String des CA-Root-Zertifikats direkt aus dem Feld agentGatewayCard.rootCertificates Ihrer Agent Gateway-Ressource:

    export AGW_CERT=$(gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --format="value[delimiter=\\n](agentGatewayCard.rootCertificates)")

    Alternativ können Sie die REST API verwenden, um die Gateway-Ressource abzurufen:

    curl -s -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://networkservices.googleapis.com/v1/projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" \
   | jq -r '.agentGatewayCard.rootCertificates[]'

    Ersetzen Sie Folgendes:

    • AGENT_GATEWAY_NAME: der Name Ihres Egress-Agent-Gateways
    • REGION: die Region, in der das Gateway bereitgestellt wird
    • AGENT_GATEWAY_PROJECT_ID: die Projekt-ID, in der das Gateway bereitgestellt wird

  2. Aktualisieren Sie Ihre Dockerfile, damit dem CA-Zertifikat vertraut wird.

    Fügen Sie das Build-Argument AGENT_GATEWAY_ROOT_CERTIFICATES zu Ihrem Dockerfile hinzu. Die Build-Befehle teilen die Zertifikate in separate Dateien auf, installieren sie mit update-ca-certificates und legen Umgebungsvariablen fest, damit OpenSSL, Python-HTTP-Clientbibliotheken (requests, httpx) und gRPC die benutzerdefinierte Zertifizierungsstelle erkennen:

    # Install root certificates under root user
USER root

ARG AGENT_GATEWAY_ROOT_CERTIFICATES
RUN if [ -n "$AGENT_GATEWAY_ROOT_CERTIFICATES" ]; then \
     echo "Installing Agent Gateway root certificates..."; \
     printf "%b" "$AGENT_GATEWAY_ROOT_CERTIFICATES" | awk 'BEGIN {c=0} /BEGIN CERTIFICATE/ {c++} c > 0 { print > "/usr/local/share/ca-certificates/agw-" c ".crt" }'; \
     update-ca-certificates; \
   fi

# Configure SSL/TLS trust paths for Python HTTP libraries, OpenSSL, and gRPC
ENV GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
ENV REQUESTS_CA_BUNDLE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
ENV SSL_CERT_FILE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
ENV AGENT_GATEWAY_ROOT_CERT_302034098528=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}

# Switch back to application execution user
USER 1000

  3. Erstellen Sie das Container-Image mit Cloud Build.

    Erstellen Sie eine cloudbuild.yaml-Datei, um den Root-Zertifikatstring mithilfe von Substitutionen an Cloud Build zu übergeben:

    steps:
- name: 'gcr.io/cloud-builders/docker'
  args:
  - 'build'
  - '--build-arg'
  - 'AGENT_GATEWAY_ROOT_CERTIFICATES=${_AGW_CERT}'
  - '-t'
  - '$_IMAGE_URI'
  - '.'

images:
- '$_IMAGE_URI'

    Senden Sie den Container-Image-Build an Cloud Build:

    export IMAGE_URI="REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest"

gcloud builds submit \
   --project=PROJECT_ID \
   --region=REGION \
   --config=cloudbuild.yaml \
   --substitutions=_IMAGE_URI="$IMAGE_URI",_AGW_CERT="$AGW_CERT" \
   .

    Ersetzen Sie REPOSITORY_NAME und IMAGE_NAME durch die Namen Ihres Artifact Registry-Repositorys und -Images.

  4. Stellen Sie Ihren containerisierten Agenten bereit.

    Geben Sie den URI des erstellten Container-Images zusammen mit Ihrer Agent Gateway-Konfiguration in Ihrer Bereitstellungsanfrage an (mit agent_gateway_config unter spec.deploymentSpec oder mit SDK-Bereitstellungsaufrufen).

Agent Runtime auf genehmigte Agent Gateways beschränken

Sie können benutzerdefinierte Einschränkungen für Organisationsrichtlinien erstellen, um die Gruppe der infrage kommenden Agent Gateway-Ressourcen zu definieren, die beim Bereitstellen von Agents verwendet werden können.

Benutzerdefinierte Einschränkungen für Organisationsrichtlinien erstellen

In diesem Beispiel werden benutzerdefinierte Einschränkungen erstellt, die nur Traffic zu und von einer vorab genehmigten Liste von Gateways zulassen.

Agent zu beliebigem Ziel

  1. Wenn Sie eine benutzerdefinierte Einschränkung für den Agent-to-Anywhere-Modus (ausgehender Traffic) definieren möchten, erstellen Sie eine Datei mit dem Namen constraint-agent-gateway-egress.yaml.

    Im folgenden Beispiel gibt das Feld condition an, dass der Vorgang nur zulässig ist, wenn eine Agent Gateway-Ressource angegeben ist (Feld ist vorhanden und nicht leer) und wenn das angegebene Gateway auf der Liste der vorab genehmigten Gateways steht.

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

    Ersetzen Sie Folgendes:

    • ORGANIZATION_ID: Ihre Organisations-ID.
    • AGENT_PROJECT_ID: Ihre Projekt-ID.
    • REGION: die Region, in der das Gateway erstellt wurde.
    • AGENT_GATEWAY_ID: Ihre Gateway-ID.

  2. Wenden Sie die benutzerdefinierte Einschränkung an.

    gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

    Ersetzen Sie EGRESS_CONSTRAINT_PATH durch den vollständigen Pfad zur benutzerdefinierten Einschränkungsdatei, die im vorherigen Schritt erstellt wurde.

  3. Erstellen Sie die Organisationsrichtlinie, um die Einschränkung zu erzwingen. Erstellen Sie eine YAML-Richtliniendatei mit dem Namen policy-agent-gateway-egress.yaml, um die Organisationsrichtlinie zu definieren. In diesem Beispiel wird diese Einschränkung auf Projektebene erzwungen. Sie können diese Einschränkung aber auch auf Organisations- oder Ordnerebene festlegen.

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    Ersetzen Sie AGENT_PROJECT_ID durch Ihre Projekt-ID.

  4. Erzwingen Sie die Organisationsrichtlinie.

    gcloud org-policies set-policy EGRESS_POLICY_PATH

    Ersetzen Sie EGRESS_POLICY_PATH durch den vollständigen Pfad zur YAML-Datei der Organisationsrichtlinie, die im vorherigen Schritt erstellt wurde. Es kann bis zu 15 Minuten dauern, bis die Richtlinie wirksam wird.

Client zu Agent

  1. Wenn Sie eine benutzerdefinierte Einschränkung für den Client-to-Agent-Modus (Ingress) definieren möchten, erstellen Sie eine Datei mit dem Namen constraint-agent-gateway-ingress.yaml.

    Im folgenden Beispiel gibt das Feld condition an, dass der Vorgang nur zulässig ist, wenn eine Agent-Gateway-Ressource angegeben ist (Feld ist vorhanden und nicht leer) und sich das angegebene Gateway in der Liste der vorab genehmigten Gateways befindet.

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

    Ersetzen Sie Folgendes:

    • ORGANIZATION_ID: Ihre Organisations-ID.
    • AGENT_PROJECT_ID: Ihre Projekt-ID.
    • REGION: die Region, in der das Gateway erstellt wurde.
    • AGENT_GATEWAY_ID: Ihre Gateway-ID.

  2. Wenden Sie die benutzerdefinierte Einschränkung an.

    gcloud org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH

    Ersetzen Sie INGRESS_CONSTRAINT_PATH durch den vollständigen Pfad zur benutzerdefinierten Einschränkungsdatei, die Sie im vorherigen Schritt erstellt haben.

  3. Erstellen Sie die Organisationsrichtlinie, um die Einschränkung zu erzwingen. Erstellen Sie eine YAML-Richtliniendatei mit dem Namen policy-agent-gateway-ingress.yaml, um die Organisationsrichtlinie zu definieren. In diesem Beispiel wird diese Einschränkung auf Projektebene erzwungen. Sie können diese Einschränkung aber auch auf Organisations- oder Ordnerebene festlegen.

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    Ersetzen Sie AGENT_PROJECT_ID durch Ihre Projekt-ID.

  4. Erzwingen Sie die Organisationsrichtlinie.

    gcloud org-policies set-policy INGRESS_POLICY_PATH

    Ersetzen Sie INGRESS_POLICY_PATH durch den vollständigen Pfad zur YAML-Datei der Organisationsrichtlinie, die im vorherigen Schritt erstellt wurde. Es kann bis zu 15 Minuten dauern, bis die Richtlinie wirksam wird.

Weitere Informationen zur Verwendung benutzerdefinierter Einschränkungen für Organisationsrichtlinien finden Sie unter Benutzerdefinierte Einschränkungen erstellen.

Beschränkungen

  • Für die projektübergreifende Verwaltung gelten die folgenden Einschränkungen:

    • Projektübergreifende Bindungen zwischen Agents und Gateways werden nur im Agent-to-Anywhere-Modus (Ausgang) unterstützt. Im Client-to-Agent-Modus (Ingress) müssen sich der Agent und das Agent-Gateway im selben Projekt befinden.
    • Sie müssen die REST API oder gcloud verwenden, um die End-to-End-Governance für mehrere Projekte zu konfigurieren. In der Google Cloud Google Cloud Console können keine projektübergreifenden IAM-Richtlinienbindungen oder Agent Registry-Einträge erstellt werden.

  • Ein Agent Gateway kann nicht an Runtime Reasoning Engines gebunden werden, die vor dem 29. April 2026 erstellt wurden.

  • In einem einzelnen Projekt und einer einzelnen Region können mehrere Agent Gateway-Instanzen für Agent-to-Anywhere (Egress) und Client-to-Agent (Ingress) gehostet werden. Alle Agent Runtime-Agents, die in demselben Projekt und derselben Region bereitgestellt werden, müssen jedoch an dieselben spezifischen Egress- und Ingress-Agent Gateway-Instanzen gebunden werden.

    Wenn ein Projekt und eine Region beispielsweise egress-gateway-X und egress-gateway-Y enthält, müssen alle Agents in diesem Projekt und in dieser Region so konfiguriert werden, dass sie dasselbe Gateway für den Egress verwenden. Das bedeutet, dass entweder alle Agents egress-gateway-X oder alle Agents egress-gateway-Y verwenden. Sie können agent-A nicht für die Verwendung von egress-gateway-X und agent-B nicht für die Verwendung von egress-gateway-Y konfigurieren.

    Dieselbe Bindungsregel gilt auch für Ingress-Gateways in einem Projekt und einer Region.

  • Der Security Command Center Agent Engine Threat Detection-Dienst ist nicht verfügbar, wenn das Agent Gateway für einen Agenten aktiviert ist.

  • Im Client-to-Agent-Modus (eingehend) kann Agent Gateway nur die Methoden query und streamQuery von Agent Runtime steuern. Zum Schutz anderer nicht unterstützter Methoden (z. B. asyncQuery) können Sie Model Armor-Vorlagen direkt über Ihre Anwendung oder Ihren Agenten anwenden. Weitere Informationen finden Sie unter Prompts und Antworten bereinigen oder in diesem Codelab zum Erstellen eines sicheren Agentensystems mit Model Armor.

  • Wenn Sie eine Agent-Gateway-Bindung für einen Laufzeit-Agenten ändern, werden alle vorhandenen Versionen des Agenten archiviert. Das Archivieren kann nicht rückgängig gemacht werden. Weitere Informationen finden Sie unter Agent-Gateway und Versionen.

    Wenn Sie einen Agent aktualisieren möchten, ohne die ID der Reasoning Engine zu ändern oder Richtlinienbindungen zu unterbrechen, aktualisieren Sie die Agent-Instanz direkt, wie unter Agent Runtime aktualisieren beschrieben.

Nächste Schritte

Codelab

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

Leitfaden

Hier erfahren Sie, wie Sie die Autorisierung für Agent Gateway an IAP, Model Armor oder Ihren eigenen benutzerdefinierten Autorisierungsdienst delegieren.

Anleitung

Informationen zum Überwachen des KI-Agenten-Gateways

Fehlerbehebung

Informationen zur Fehlerbehebung bei der Verbindung zum KI-Agenten-Gateway.