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

Auf dieser Seite wird beschrieben, wie Sie Agent Runtime-Traffic über Agent Gateway weiterleiten. Das Agent Gateway ist eine zentrale Netzwerk- und Sicherheitskomponente des Gemini Enterprise Agent Platform-Ökosystems. 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 das Agent Gateway im Agent-to-Anywhere-Modus (Ausgang) verwenden, um die gesamte ausgehende Kommunikation mit ausgehendem Traffic zu Tools, Modellen, APIs und anderen Agenten zu sichern und zu verwalten. 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 sollen.

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

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

Agent Runtime-Traffic über Agent Gateway weiterleiten

So leiten Sie 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 (ausgehend) oder im Client-to-Agent-Modus (eingehend) erstellen.

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

   Eine Anleitung finden Sie unter Agent Gateway einrichten.

   Achten Sie darauf, dass das Gateway so konfiguriert ist, dass es den Anforderungen Ihrer Bereitstellung entspricht. Wenn Ihr Agent beispielsweise LLM-Zugriff benötigt, konfigurieren Sie das Gateway so, dass dieser Zugriff zugelassen wird, um potenzielle Bereitstellungsfehler in 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:

   gcloud

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

   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.

   1. 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.s3ns-system.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 Laufzeit-Agent bereitgestellt ist.

   Terraform

   Wenn Sie projektübergreifenden Zugriff von mehreren Runtime-Arbeitslastprojekten auf ein zentrales Agenten-Gateway-Projekt deklarativ gewähren möchten, erstellen Sie die benutzerdefinierte IAM-Rolle im zentralen Gateway-Projekt und weisen Sie sie dem Runtime-Dienst-Agenten jedes Arbeitslastprojekts zu:

   variable "runtime_project_numbers" {
     type        = set(string)
     description = "Project numbers hosting cross-project Agent Runtime workloads"
     default     = ["AGENT_RUNTIME_PROJECT_NUMBER"]
   }
   
   resource "google_project_iam_custom_role" "ar_agw_cross_project_sa" {
     project     = "AGENT_GATEWAY_PROJECT_ID"
     role_id     = "ar_agw_cross_project_sa"
     title       = "Runtime Agent Gateway Cross-Project SA"
     description = "Custom role for cross-project service agents to access Agent Gateway"
     permissions = [
       "networkservices.agentGateways.get",
       "networkservices.operations.get",
     ]
   }
   
   resource "google_project_iam_member" "ar_agw_cross_project_binding" {
     for_each = var.runtime_project_numbers
   
     project = "AGENT_GATEWAY_PROJECT_ID"
     role    = google_project_iam_custom_role.ar_agw_cross_project_sa.name
     member  = "serviceAccount:service-${each.value}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com"
   }
   

3. KI-Agenten so konfigurieren, dass Traffic über das KI-Agenten-Gateway geleitet 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 Agenten, die das Python SDK verwenden

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

     Wenn Sie gateway-vermittelte Plattformfunktionen wie Model Armor oder semantische Governance-Richtlinien mit diesem Agenten verwenden möchten, legen Sie im Erstellungsaufruf sowohl agent_gateway_config als auch identity_type=AGENT_IDENTITY 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 weggelassen oder falsch konfiguriert wird.

     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 Agenten, die Terraform verwenden

     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 ausgehenden Traffic 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 Agenten
     • 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 Agenten
     • 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 Client-zu-Agent-Modus (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 mit einem Agent-to-Anywhere-Gateway für ausgehenden Traffic 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 KI-Agenten

     Client zu Agent

     Verwenden Sie die folgende REST API-Anfrage, um einen vorhandenen Agenten mit einem Client-zu-Agent-Gateway für eingehenden Traffic 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": {
             "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 im Abschnitt „Client zu Agent (eingehend)“ erstellt haben
     • RESOURCE_ID: die Ressourcen-ID des KI-Agenten

4. KI-Agenten in der Agent Registry registrieren

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

   gcloud

   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 Agent-Eintrag in der Registry 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 Registry.
   • RUNTIME_AGENT_PROJECT_NUMBER: die Projektnummer des Projekts, in dem der Runtime-Agent bereitgestellt wird
   • ENGINE_ID: die Ressourcen-ID des KI-Agenten

   Terraform

   resource "google_agent_registry_service" "runtime_agent_entry" {
     project      = "AGENT_GATEWAY_PROJECT_ID"
     location     = "REGION"
     service_id   = "RUNTIME_AGENT_SERVICE_NAME"
     display_name = "RUNTIME_AGENT_DISPLAY_NAME"
   
     endpoint_spec {
       no_spec {}
     }
   
     interfaces {
       url              = "https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID"
       protocol_binding = "jsonrpc"
     }
   }
   

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

5. IAM-Richtlinienbindung zwischen Agent und Registry erstellen

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

   gcloud

   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
   

   Terraform

   resource "google_iap_agent_registry_endpoint_iam_member" "egress_binding" {
     project     = "AGENT_GATEWAY_PROJECT_ID"
     location    = "REGION"
     endpoint_id = "AGENT_ENDPOINT_ID"
     role        = "roles/iap.egressor"
     member      = "MEMBER"
   }
   

   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 KI-Agenten in einem Projekt oder in der gesamten Organisation Zugriff auf ausgehenden Traffic gewähren möchten, anstatt einzelne Instanzen zu binden, können Sie die IAM-Richtlinie an eine Hauptkontogruppe binden:

     • So gewähren Sie Zugriff auf alle KI-Agenten in einem Projekt: principalSet://TRUST_DOMAIN/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER
     • So gewähren Sie allen KI-Agenten 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 Traffic des KI-Agenten wird jetzt über das Agent Gateway geleitet. Agent Gateway verwendet jedoch eine Standard-Ablehnungsrichtlinie. Damit bestimmte Agent Platform-Funktionen aktiviert werden können, muss der Agent mit den folgenden Endpunkten kommunizieren können:

   Der Hostname-Abgleich im KI-Agenten-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 die 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 Agenten Funktionen wie Sitzungen oder Memory Bank verwenden, müssen Sie außerdem dafür sorgen, dass die Agenten 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 das Agent-SDK verwendet. Je nach SDK-Version, regionaler Clientkonfiguration oder mTLS-Nutzung kann eine Google API beispielsweise über die folgenden Endpunkt-Hostnamen 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 eine Umgebung mit mehreren Projekten haben, können Sie mehrere Google API-Kernendpunkte 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 Richtlinie für ausgehenden Traffic von Agent zu Endpunkt erstellen.

7. Agentenkonfiguration prüfen

   Console

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

      Zu Deployments

   2. Klicken Sie auf den Namen des bereitgestellten KI-Agenten.

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

   4. Klicken Sie auf Bereitstellungsdetails. Die Konfigurationen für eingehenden und ausgehenden Traffic des KI-Agenten-Gateways sind im Feld Deployment spec 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 KI-Agent bereitgestellt wird
   • RESOURCE_ID: die Ressourcen-ID des KI-Agenten

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

Wenn Sie ausgehenden Traffic über ein Agent-to-Anywhere-Agent-Gateway (Ausgang) 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 Root-Zertifikat der Zertifizierungsstelle des Gateways in den Trust Store des benutzerdefinierten Container-Images einbinden.

Da Agent Gateway die TLS-Entschlüsselung und -Prüfung für die ausgehende Agent-Kommunikation durchführt, wird das Zertifikat der Zertifizierungsstelle bei Nicht-BYOC-Agent-Bereitstellungen (quellbasiert) 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 Agent-Gateways für ausgehenden Traffic
   • 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 CA 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 mithilfe von Cloud Build das Container-Image.

   Erstellen Sie eine cloudbuild.yaml-Datei, um den Root-Zertifikatsstring 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 den Namen Ihres Artifact Registry-Repositorys und den Image-Namen.

4. Containerisierten Agenten bereitstellen

   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 zulässigen Agent Gateway-Ressourcen zu definieren, die beim Bereitstellen von Agenten 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.

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

Beschränkungen

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

  • Projektübergreifende Bindungen zwischen Agenten und Gateways werden nur im Agent-to-Anywhere-Modus (ausgehend) unterstützt. Im Client-zu-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 projektübergreifende End-to-End-Governance zu konfigurieren. Die Cloud de Confiance Cloud de Confiance Console unterstützt nicht das Erstellen von projektübergreifenden IAM-Richtlinienbindungen oder Agent Registry-Einträgen.

• 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-to-Anywhere- (Ausgang) und Client-to-Agent-Agent-Gateway-Instanzen (Eingang) gehostet werden. Alle Agent Runtime-Agenten, die in diesem Projekt und dieser Region bereitgestellt werden, müssen jedoch an dieselben spezifischen Agent-Gateway-Instanzen für ausgehenden und eingehenden Traffic gebunden sein.

  Wenn ein Projekt und eine Region beispielsweise egress-gateway-X und egress-gateway-Y enthalten, müssen alle Agents in diesem Projekt und dieser Region so konfiguriert sein, dass sie dasselbe Gateway für ausgehenden Traffic 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.

  Diese Bindungsregel gilt auch für Gateways für eingehenden Traffic innerhalb eines Projekts 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-zu-Agent-Modus (eingehend) kann das Agent Gateway nur die Methoden query und streamQuery der 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 Agenten aktualisieren möchten, ohne seine Reasoning-Engine-ID zu ändern oder Richtlinienbindungen zu unterbrechen, aktualisieren Sie Ihre Agenteninstanz direkt, wie unter Agent Runtime-Instanz aktualisieren beschrieben.

Nächste Schritte