KI-Agenten-Gateway einrichten

Wenn Sie die Zugriffssteuerung und die sichere Verbindung für Ihre Agentic Workflows zentralisieren möchten, können Sie eine Agent Gateway-Ressource einrichten, um eingehenden oder ausgehenden Traffic zu verwalten.

Bevor Sie ein Gateway einrichten, sollten Sie sich die konzeptionellen Grundlagen und Kernkomponenten in der Übersicht über Agent Gateway ansehen.

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Agent-Gateways zu erstellen und zu verwalten. Sie können diese Berechtigungen entweder mit benutzerdefinierten Rollen oder mit anderen vordefinierten Rollen erhalten.

Erforderliche APIs

Aktivieren Sie die folgenden mindestens erforderlichen APIs im Projekt Cloud de Confiance , in dem Sie Agent Gateway bereitstellen:

• Compute Engine API (compute.googleapis.com): Stellt die grundlegende Netzwerkinfrastruktur, Subnetze, Routing und Private Service Connect-Netzwerkanhänge (PSC) bereit.
• Netzwerksicherheits-API (networksecurity.googleapis.com): Erstellt und erzwingt Autorisierungsrichtlinien (authzPolicies) für Gateway-Traffic.
• Network Services API (networkservices.googleapis.com): Verwaltet Agent Gateway-Ressourcen (agentGateways), Verbindungsvorlagen (agentConnectivityTemplates) und Autorisierungserweiterungen (authzExtensions).
• Identity and Access Management API (iam.googleapis.com): Verwaltet Dienstkonten und IAM Unified Access Policies (UAP) für Agent-Identitäten.
• Identity-Aware Proxy API (iap.googleapis.com): Authentifiziert und verifiziert Agenten-, Endpunkt- und Server-Traffic.
• Agent Registry API (agentregistry.googleapis.com): Registriert und verwaltet KI-Agenten, MCP-Server und Tool-Endpunkte, die vom Gateway gesteuert werden.

Führen Sie den folgenden Befehl aus, um die mindestens erforderlichen APIs zu aktivieren:

gcloud services enable \
    compute.googleapis.com \
    networksecurity.googleapis.com \
    networkservices.googleapis.com \
    iam.googleapis.com \
    iap.googleapis.com \
    agentregistry.googleapis.com \
    --project=PROJECT_ID

Ersetzen Sie PROJECT_ID durch die Projekt-ID, unter der Sie das Agent-Gateway bereitstellen.

Je nach den Funktionen, Beobachtbarkeitstools und Agent-Laufzeiten, die Sie mit Agent Gateway verwenden, müssen Sie möglicherweise auch optionale APIs aktivieren:

Bereitstellung des KI-Agenten-Gateways planen

In diesem Abschnitt können Sie die Bereitstellung Ihres Agent Gateways planen und sich über die Anforderungen an die Governance-Architektur informieren. Sie können diese Schritte wiederholen, wenn Sie neue Ziele registrieren, neue Zugriffssteuerungsrichtlinien hinzufügen oder weitere Agents bereitstellen.

Bereitstellungsmodus auswählen

Agent Gateway unterstützt zwei Bereitstellungsmodi:

• Client zu Agent (eingehend): Sichert die Kommunikation von Clients zu Ihren Agenten, die auf Cloud de Confianceausgeführt werden.
• Agent-to-Anywhere (ausgehend): Sichert die Kommunikation von Ihren Agenten zu externen Zielen, öffentlichen APIs und MCP-Servern.

Laufzeit, Projekt und Region für die Bereitstellung auswählen

Agent Gateway steuert den Traffic von KI-Agenten, die in Gemini Enterprise und Runtime ausgeführt werden.

• Agent Runtime: Agent Gateway unterstützt sowohl den Modus „Agent zu beliebigem Ziel“ (ausgehend) als auch den Modus „Client zu Agent“ (eingehend). Im Agent-to-Anywhere-Modus können sich die Agents entweder im selben Projekt wie das Gateway oder in einem anderen Projekt befinden. Im Client-zu-Agent-Modus müssen sich die Agents im selben Projekt wie das Gateway befinden. In beiden Modi müssen sich die Agents in derselben Region wie das Gateway befinden.

• Gemini Enterprise: Das Agent Gateway unterstützt nur den Modus „Agent zu beliebigem Ziel“ (ausgehend). Bei Gemini Enterprise steuert jedes Gateway agentische Interaktionen nur im Rahmen des Projekts und der Region, in der es bereitgestellt wird.

Wenn Sie Agenten in Gemini Enterprise und Runtime verwalten möchten, können Sie eine einzelne Agent Gateway-Instanz verwenden. Alternativ können Sie auch unabhängige Agent Gateway-Instanzen für Gemini Enterprise und Runtime bereitstellen.

Beispielhafte Bereitstellungsmuster

Hier sind einige Beispiel-Bereitstellungsmuster, die Sie berücksichtigen sollten:

Projektübergreifende Governance für Runtime-Agenten

In diesem Bereitstellungsmuster stellen Sie ein Agent-to-Anywhere-Agent-Gateway (für ausgehenden Traffic) in einem dedizierten Governance-Projekt bereit. Laufzeit-Agents werden in separaten Projekten in derselben Region wie das Gateway bereitgestellt und können zu einem beliebigen Ordner in Ihrer Organisation gehören.

Wenn Sie die projektübergreifende Governance für ausgehenden Traffic einrichten möchten, konfigurieren Sie die folgenden Ressourcen:

Im zentralen Governance-Projekt:

• Erstellen Sie das KI-Agenten-Gateway. Achten Sie darauf, dass das Gateway mit einer Agent Registry-Instanz verknüpft ist.
• Registrieren Sie projektübergreifende KI-Agenten zusammen mit allen Tools, Servern oder Endpunkten in der Agent Registry, die mit dem Gateway verbunden ist.
• Erteilen Sie dem Laufzeit-Dienst-Agenten jedes Projekts, in dem sich die Agenten befinden, projektübergreifende IAM-Berechtigungen, damit sich Agenten in diesen Projekten an das Gateway im Governance-Projekt binden können. Ein Beispiel finden Sie unter Laufzeit-Traffic über das Agent Gateway weiterleiten.
• Konfigurieren Sie IAP-Richtlinien, Principal Access Boundaries und SPIFFE-kompatible Workload Identities, um ausgehenden Traffic zu autorisierten Endpunkten zu steuern und zu sichern.
• Erstellen Sie alle Model Armor-Vorlagen, die Sie für ausgehenden Traffic verwenden möchten.
• Wenn Sie ausgehenden Traffic an ein VPC-Netzwerk senden möchten, können Sie den PSC-Netzwerkanhang, benutzerdefinierte TLS-Trust-Anchor (tlsConfig) für private CAs und die DNS-Peering-Konfiguration im Governance-Projekt erstellen.

In den Agent Runtime-Projekten:

• Stellen Sie die Agenten bereit und binden Sie sie an das zentrale Gateway im Governance-Projekt.

Die projektübergreifende Governance wird nur für die Laufzeit mit Agent-to-Anywhere-Gateways (ausgehend) unterstützt. Gemini Enterprise wird nicht unterstützt.

Gemeinsame Governance für Gemini Enterprise- und Runtime-Agenten

In diesem Bereitstellungsmuster wird der gesamte Traffic von Gemini Enterprise Apps und Runtime-Agenten über ein einziges Agent Gateway geleitet.

Hier ein Beispiel für eine Bereitstellung:

• Die Gemini Enterprise-App wird als global-Deployment bereitgestellt.
• Laufzeit-KI-Agenten werden in einer einzelnen Region (us-central1) bereitgestellt, die der Gemini Enterprise-Bereitstellung entspricht.
• Das Agent Gateway wird in derselben Region (us-central1) bereitgestellt.
• Sowohl global- als auch us-central1-Agent Registry-Instanzen können mit dem Agent Gateway verknüpft werden. Agenten und Ziele müssen bei den Agent Registry-Instanzen registriert sein, die mit dem Gateway verknüpft sind.

Unabhängige Governance für Gemini Enterprise- und Runtime-Agenten

In diesem Bereitstellungsmuster hat jede Region ein dediziertes Agent Gateway, um den Agenten-Traffic zu überwachen und zu steuern, was für eine regionale Isolation sorgt:

• Die Gemini Enterprise-App wird als globale oder multiregionale Bereitstellung (in global, us oder eu) bereitgestellt.
• Laufzeit-Agents werden in jeder Region bereitgestellt, in der sie benötigt werden.
• Agent Gateway-Instanzen werden in jeder Region bereitgestellt, in der sich Agenten und Anwendungen befinden.
• Sie müssen Ihre Agenten und Ziele in den Agent Registry-Instanzen registrieren, die mit den einzelnen Gateways verknüpft sind.

Identität des KI‑Agenten einrichten

Jeder KI-Agent, der von Agent Gateway verwaltet wird, benötigt eine eigene eindeutige Agentenidentität (eine SPIFFE-ID). Da IAM-Zugriffsrichtlinien von dieser Workload Identity abhängen, wird Traffic von nicht identifizierten Agents standardmäßig blockiert.

Sie können eine Agentenidentität bereitstellen, wenn Sie einen Agenten in der Laufzeit bereitstellen oder ihn vorhandenen Agentenarbeitslasten zuweisen. Eine ausführliche Anleitung finden Sie unter Agent-Identität mit Laufzeit verwenden.

KI-Agenten und Zielressourcen registrieren

Um eine sichere Kommunikation zu ermöglichen, müssen Sie Ihre Agent Registry-Instanz identifizieren und die Ressourcen registrieren, die von Ihrem Gateway verwaltet werden.

1. Identifizieren Sie die Agent Registry-Instanzen, die Sie verwenden möchten. Ein Agent Gateway kann mit bis zu zwei Registries verknüpft werden (einer globalen Registry und einer regionalen oder multiregionalen Registry):

   • Agent Runtime-Agenten sind regionale Ressourcen und werden in der Regel in regionalen Registries registriert, die ihrer Bereitstellungsregion entsprechen. Projektübergreifende KI-Agenten müssen in der Registry registriert sein, die mit dem zentralen Governance-Projekt verknüpft ist, in dem das Agent Gateway bereitgestellt wird.
   • Gemini Enterprise-Agenten sind globale oder multiregionale Ressourcen und werden in globalen oder multiregionalen Registries (z. B. global, us oder eu) registriert.

   Achten Sie darauf, dass die Registry-Instanzen, die Sie mit Ihrem Agent Gateway verknüpfen, diejenigen sind, in denen Ihre Agenten, Endpunkte und Server registriert sind.

2. Registrieren Sie Ihre Agenten in der Agent Registry. Wenn Sie den Agenten noch nicht erstellt haben, müssen Sie diesen Schritt später ausführen. Eine Anleitung finden Sie unter Agents registrieren.

3. Empfohlen: Identifizieren und registrieren Sie alle Tools, MCP-Server und API-Endpunkte, die Ihre KI-Agenten aufrufen werden (einschließlich wichtiger Plattform-APIs). Für den Zugriff des KI-Agenten auf Ziele ist immer eine IAM-Zugriffsrichtlinie erforderlich, die der Identität des KI-Agenten die Berechtigung iap.resources.egressViaIAP gewährt. Wir empfehlen, Ressourcen in der Agent Registry zu registrieren, damit Sie detaillierte, ressourcenspezifische Richtlinien und Steuerelemente auf Toolebene erzwingen können. Für nicht registrierte Ziele müssen Sie dem Agenten diese Berechtigung erteilen, indem Sie Richtlinien für nicht registrierte Endpunkte konfigurieren.

   Ziele in einem anderen Projekt als dem Gateway müssen in der Agent Registry im Gateway-Projekt registriert sein. Solche Ziele sind nur für Laufzeit-Agenten im Agent-to-Anywhere-Modus gültig.

   Eine Anleitung finden Sie in den folgenden Leitfäden:

   • MCP-Server registrieren
   • Endpunkte registrieren

Richtlinien zur Zugriffssteuerung konfigurieren

Für jedes Agent Gateway ist eine zugehörige Autorisierungsrichtlinie erforderlich.

IAM (nur Agent-to-Anywhere-Modus)

Konfigurieren Sie eine IAM-Richtlinie, die dem Hauptkonto Ihrer Agentenidentität die Berechtigung iap.resources.egressViaIAP für jede der Zielressourcen zuweist, die Sie in Agent Registry registriert haben.

Standardmäßig blockiert Agent Gateway den gesamten Traffic, es sei denn, eine IAM-Zugriffsrichtlinie autorisiert den Agentenzugriff auf Zielressourcen explizit, indem der Agentenidentität die Berechtigung iap.resources.egressViaIAP gewährt wird.

Es wird empfohlen, Ziele in Agent Registry zu registrieren, da Sie so Richtlinien auf bestimmte Ressourcen beschränken und detaillierte Tool-Steuerelemente anwenden können. Wenn Ziele nicht in der Agent Registry registriert sind, müssen Sie dem Agent die Berechtigung iap.resources.egressViaIAP erteilen, indem Sie eine Richtlinie für nicht registrierte Endpunkte konfigurieren.

Da Registries global, multiregional oder regional sein können, müssen alle Registry-weiten Bindungen mit den Registry-Instanzen übereinstimmen, die für Ihr Agent Gateway konfiguriert sind.

Eine Anleitung finden Sie unter IAM-Agent-Richtlinien erstellen.

Wenn Sie Ihre Konfiguration validieren möchten, ohne Traffic zu blockieren, empfehlen wir, IAP zuerst im Probelaufmodus bereitzustellen.

Model Armor

(Optional) Wenn Ihre Bereitstellung Schutz vor Prompt-Injection-Angriffen, Jailbreaks, toxischen Inhalten oder dem Verlust sensibler Daten erfordert, sollten Sie die Integration von Model Armor-Sicherheitsmaßnahmen planen und Vorlagen mit den erforderlichen Sicherheitsfiltern erstellen.

Weitere Informationen finden Sie in folgenden Dokumenten:

• Model Armor auf einem Gateway konfigurieren
• Autorisierung mit Diensterweiterungen delegieren

Semantische Governance-Richtlinien

(Optional) Sie können Ihren Agenten kontextsensitive Steuerelemente auf Basis natürlicher Sprache hinzufügen, um Schutz vor schädlichen Kombinationen von Tools zu ermöglichen.

Wir empfehlen, semantische Governance-Richtlinien zuerst im Probelaufmodus bereitzustellen, damit Sie Ihre Konfiguration validieren können, ohne den Traffic zu blockieren. Weitere Informationen finden Sie unter Semantische Governance-Richtlinien konfigurieren.

Benutzerdefinierte Autorisierungs-Engines

(Optional) Wenn Sie die Autorisierung mithilfe von Diensterweiterungen an benutzerdefinierte Autorisierungs-Engines oder Drittanbietersysteme delegieren möchten, müssen Sie dafür sorgen, dass die benutzerdefinierten Autorisierungs-Engines beim Bereitstellen des Gateways verfügbar sind.

Model Armor, semantische Governance-Richtlinien und andere benutzerdefinierte Autorisierungs-Engines können entweder während der Ersteinrichtung des Agent Gateways aktiviert oder nach der Bereitstellung als inkrementelles Sicherheitsrichtlinien-Update angehängt werden.

Agent Gateway im Modus „Agent zu beliebigem Ziel“ (ausgehend) konfigurieren

Wenn Sie das Agent Gateway im Agent-to-Anywhere-Modus (Ausgang) einrichten, können Sie konfigurieren, wie der verwaltete Traffic die Zielendpunkte und ‑tools erreicht. Wählen Sie je nach Ihren Netzwerk- und Sicherheitsanforderungen eine der folgenden Bereitstellungsoptionen aus:

• Ausgehender Internet-Traffic: Das Gateway leitet den Agent-Traffic sicher über das Internet an öffentlich zugängliche Endpunkte und APIs weiter. Wenn Sie ein Agent-Gateway mit ausgehendem Internet-Traffic konfigurieren möchten, können Sie die Anleitung auf dieser Seite verwenden.

• Ausgehender Traffic aus dem VPC-Netzwerk: Das Gateway leitet den KI-Agenten-Traffic über Private Service Connect-Netzwerkanhänge privat in ein VPC-Netzwerk weiter. Sie können entweder den gesamten Traffic über das VPC-Netzwerk (ALL_TRAFFIC) oder nur den Traffic an private IP-Adressbereiche (PRIVATE_RANGES_ONLY) weiterleiten.

  Wenn Sie ein Agent Gateway mit ausgehendem VPC-Traffic konfigurieren möchten, müssen Sie die Anleitung unter VPC-Verbindung für Agent Gateway einrichten verwenden.

So erstellen Sie eine Agent Gateway-Ressource für die Agent-to-Anywhere-Kommunikation:

1. Nachdem ein Agent-Gateway erstellt wurde, dient es als primärer Verbindungspunkt für das Routing des Agent-Traffics innerhalb Ihres Projekts und der ausgewählten Region. Sie können diesen Endpunkt jetzt verwenden, um sichere, verschlüsselte und authentifizierte Kommunikationskanäle zwischen Agenten und ihren Zielen (Tools, anderen Agenten oder anderen Endpunkten) einzurichten.

   Lesen Sie sich den Abschnitt Agent Gateway-Bereitstellung planen auf dieser Seite noch einmal durch und prüfen Sie, ob Ihre Agenten bei Agent Registry registriert sind und ob Ihrem Agenten die Berechtigung iap.resources.egressViaIAP für alle Ziele gewährt wurde, zu denen er eine Verbindung herstellen möchte. Wenn Verbindungsprobleme auftreten, lesen Sie den Abschnitt Verbindungsprobleme mit dem Agent-Gateway beheben.

Als Nächstes erfahren Sie, wie Sie Agenten bereitstellen und Traffic über das Agent Gateway weiterleiten.

Agent Gateway im Client-zu-Agent-Modus (eingehend) konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie ein Agent-Gateway für die Client-zu-Agent-Kommunikation einrichten.

So erstellen Sie eine Agent-Gateway-Ressource:

resource "google_network_services_agent_gateway" "ingress_gateway" {
  project   = "PROJECT_ID"
  location  = "LOCATION"
  name      = "AGENT_GATEWAY_NAME"
  protocols = ["MCP"]

  google_managed {
    governed_access_path = "CLIENT_TO_AGENT"
  }
}

Nachdem ein Agent-Gateway erstellt wurde, dient es als primärer Verbindungspunkt für das Routing von Traffic zu Agenten in Ihrem Projekt und der ausgewählten Region.

Als Nächstes erfahren Sie, wie Sie KI-Agenten bereitstellen und Traffic über das Agent Gateway weiterleiten.

Agenten bereitstellen und Traffic über Agent Gateway weiterleiten

Informationen zum Bereitstellen eines Agent Runtime-Agenten, der Traffic über das Agent Gateway weiterleitet, finden Sie unter Traffic über das Agent Gateway weiterleiten.

Informationen zum Bereitstellen eines Gemini Enterprise-Agenten, der Traffic über Agent Gateway weiterleitet, finden Sie unter Gemini Enterprise-Traffic über Agent Gateway weiterleiten.

Codelabs

Eine End-to-End-Demonstration zum Einrichten und Verwenden von Agent Gateway finden Sie in den folgenden Codelabs:

• Agentische Arbeitslasten mit der Agent Platform verwalten: Hier erfahren Sie, wie Sie einen verwalteten ADK-Agenten in der Agent Runtime bereitstellen.
• Ausgehender Traffic von Agent Gateway von Agent Runtime zu Google Cloud-MCP-Servern: Hier erfahren Sie, wie Sie Agent Gateway im Agent-to-Anywhere-Modus konfigurieren, um ADK-Agent-Aufrufe an Google Cloud-MCP-Server zu steuern.
• Ausgehender Agent Gateway-Traffic von Agent Runtime zu externen MCP-Servern: Hier erfahren Sie, wie Sie Agent Gateway im Agent-to-Anywhere-Modus konfigurieren, um ADK-Agentenaufrufe an externe MCP-Server zu steuern.
• Ausgehender Traffic von Agent Gateway von Agent Runtime zum VPC-Netzwerk: Hier erfahren Sie, wie Sie Agent Gateway im Agent-to-Anywhere-Modus konfigurieren, um ADK-Agentenaufrufe an Ziele in einem VPC-Netzwerk zu steuern.
• Agent Gateway-Governance für projektübergreifende Agent Runtime-Agenten: Hier erfahren Sie, wie Sie Agent Gateway im Agent-to-Anywhere-Modus konfigurieren, um projektübergreifende Agent Runtime-Agenten zu verwalten.
• Ausgehender Traffic über ein privates Agent Gateway von Gemini Enterprise: Hier erfahren Sie, wie Sie die Governance für ausgehenden Traffic über ein privates Agent Gateway für Gemini Enterprise einrichten.

Nächste Schritte