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

Auf dieser Seite wird beschrieben, wie Sie den Traffic der Agent-Laufzeit ü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 mit KI-Agenten, unabhängig davon, ob sie zwischen Nutzern und KI-Agenten, zwischen KI-Agenten und Tools oder zwischen KI-Agenten selbst stattfinden.

Hinweis

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

  • Weitere Informationen zum KI-Agenten-Gateway Sie können Agent Gateway im Agent-to-Anywhere-Modus (Ausgang) 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-to-Agent-Modus (Ingress), um zu steuern, welche Clients auf Ihre Agents 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.

Beschränkungen

  • 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 (Ausgang) und Client-to-Agent (Eingang) gehostet werden. Alle Agent Runtime-Agents, die in demselben Projekt und derselben Region bereitgestellt werden, müssen jedoch an dieselben spezifischen Agent Gateway-Instanzen für Ausgang und Eingang gebunden werden.

    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 werden, dass sie dasselbe Gateway für den Egress verwenden. Entweder verwenden alle Agents egress-gateway-X oder alle Agents verwenden egress-gateway-Y. 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 innerhalb eines Projekts und einer Region.

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

  • Im Client-to-Agent-Modus (eingehend) kann das Agent Gateway nur die Methoden query und streamQuery der Agent Runtime steuern. Um andere nicht unterstützte Methoden (z. B. asyncQuery) zu schützen, können Sie Model Armor-Vorlagen direkt über Ihre Anwendung oder Ihren Agent anwenden. Weitere Informationen finden Sie unter Prompts und Antworten bereinigen oder in diesem Codelab zum Erstellen eines sicheren Agentensystems mit Model Armor.

Agent Runtime-Traffic über das Agent Gateway weiterleiten

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

  1. 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 (Ausgang) oder im Client-to-Agent-Modus (Eingang) erstellen. Der Agent und das Gateway müssen im selben Projekt und in derselben Region 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. Konfigurieren Sie Ihren Agenten so, dass der Traffic über das Agent Gateway weitergeleitet wird.

    • Für neue Agents

      Geben Sie die Gateway-Ressource beim Bereitstellen des Agents an. Wenn Sie den Agenten beispielsweise in der Agent Runtime bereitstellen möchten, verwenden Sie client.agent_engines.create, um das local_agent-Objekt zusammen mit allen optionalen Konfigurationen zu übergeben.

      Außerdem müssen Sie dafür sorgen, dass der Runtime-Instanz eine Agent-Identität zugewiesen wird. Verwenden Sie dazu den Parameter identity_type, wie in diesem Beispiel gezeigt.

      remote_agent = client.agent_engines.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME},
        # "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 AGENT_GATEWAY_TO_ANYWHERE_NAME durch den Namen des Agent-Gateways, das Sie im Agent-to-Anywhere-Modus (Egress) erstellt haben.

      Wenn Sie ein Gateway im Client-to-Agent-Modus (Ingress) erstellt haben, verwenden Sie stattdessen das Feld client_to_agent_config und ersetzen Sie AGENT_GATEWAY_CLIENT_TO_AGENT_NAME durch den Namen des Agent-Gateways, das Sie für den Ingress erstellt haben.

    • Für vorhandene Agents

      Agent zu beliebigem Ziel

      Mit der folgenden REST API-Anfrage können Sie einen vorhandenen Agent mit einem Agent-to-Anywhere-Gateway für den Egress 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/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      Ersetzen Sie Folgendes:

      • PROJECT_ID: die Projekt-ID
      • REGION: die Region, in der der Agent bereitgestellt wird
      • 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

      Mit der folgenden REST API-Anfrage können Sie einen vorhandenen Agenten einem Client-to-Agent-Gateway für den Ingress zuordnen.

      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/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      Ersetzen Sie Folgendes:

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

  3. Registrieren Sie sich bei der Agent Registry-Instanz im selben Projekt und in derselben Region wie der Agent und das Gateway.

    gcloud agent-registry services create SERVICE_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --endpoint-spec-type=no-spec \
  --interfaces='[{url="https://REGION-aiplatform.mtls.googleapis.com",protocolBinding="jsonrpc"}]' \
  --format="value(registryResource)"

    Ersetzen Sie Folgendes:

    • SERVICE_NAME: Der Name, den Sie Ihrer Ressource geben möchten, z. B. allow-aiplatform-region-eu3.
    • PROJECT_ID: die Projekt-ID
    • REGION: Die Registry-Region.
    • DISPLAY_NAME: Der für Menschen lesbare Name des Endpunkts.

    Weitere Informationen finden Sie unter Agent registrieren.

  4. Erstellen Sie eine IAM-Richtlinienbindung vom Agent zur Registry für den Agent.

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

    Ersetzen Sie Folgendes:

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

    • MEMBER: Das Hauptkonto der Agentenidentität, dem die Rolle zugewiesen werden soll. Das Format ist in der Regel: principal://TRUST_DOMAIN/resources/aiplatform/projects/PROJECT_ID/locations/REGION/reasoningEngines/ENGINE_ID.

  5. Ab diesem Zeitpunkt wird der Agent-Traffic über das Agent Gateway geleitet. Agent Gateway verwendet jedoch eine Standardablehnungsrichtlinie. Damit bestimmte Funktionen der Agent Platform aktiviert werden können, muss der Agent mit den folgenden Endpunkten kommunizieren können:

    • Wenn Cloud Trace aktiviert ist, muss das Agent Gateway Traffic zum Endpunkt https://telemetry.googleapis.com/ zulassen.

      Wenn die Umgebungsvariablen GOOGLE_API_USE_CLIENT_CERTIFICATE und GOOGLE_API_USE_MTLS_ENDPOINT festgelegt sind, muss auch Traffic zu https://telemetry.mtls.googleapis.com/ zugelassen werden.

    • Wenn Cloud Logging aktiviert ist, muss das Agent Gateway Traffic zum Endpunkt https://logging.googleapis.com/ zulassen.

      Wenn die Umgebungsvariablen GOOGLE_API_USE_CLIENT_CERTIFICATE und GOOGLE_API_USE_MTLS_ENDPOINT festgelegt sind, muss auch Traffic zu https://logging.mtls.googleapis.com/ zugelassen werden.

    Wenn Ihre Agents außerdem LLMs aufrufen oder Funktionen wie Sitzungen und Memory Bank verwenden, müssen Sie dafür sorgen, dass die Agents mit den von diesen Diensten verwendeten Endpunkten kommunizieren können. Beispiel:

    • 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. Außerdem müssen Sie dafür sorgen, dass der Agent die Rolle „IAP Egressor“ für diese Endpunkte hat. Eine Anleitung finden Sie unter Egress-Richtlinie für Agent-zu-Endpunkt erstellen.

  6. Überprüfen Sie die Agent-Konfiguration.

    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 Agents, den Sie bereitgestellt haben.

    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 ist, 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/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \
  | jq '.spec.deploymentSpec.agentGatewayConfig'

    Ersetzen Sie Folgendes:

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

Agent Runtime auf genehmigte KI-Agenten-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 (Egress) 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 in der vorab genehmigten Liste enthalten ist.

    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 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-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. Organisationsrichtlinie erzwingen

    gcloud org-policies set-policy EGRESS_POLICY_PATH

    Ersetzen Sie EGRESS_POLICY_PATH durch den vollständigen Pfad zur YAML-Datei der Organisationsrichtlinie, die Sie im vorherigen Schritt erstellt haben. 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 (eingehender Traffic) 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 wenn das angegebene Gateway in der vorab genehmigten Liste enthalten ist.

    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. Organisationsrichtlinie erzwingen

    gcloud org-policies set-policy INGRESS_POLICY_PATH

    Ersetzen Sie INGRESS_POLICY_PATH durch den vollständigen Pfad zur YAML-Datei der Organisationsrichtlinie, die Sie im vorherigen Schritt erstellt haben. 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.

Nächste Schritte

Codelab

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

Leitfaden

Informationen zum Delegieren der Autorisierung für Agent Gateway an IAP, Model Armor oder Ihren eigenen benutzerdefinierten Autorisierungsdienst.

Leitfaden

Informationen zum Überwachen des Agent Gateway

Fehlerbehebung

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