Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

KI-Agenten-Arbeitslasten mit dem KI-Agenten-Gateway auf der Gemini Enterprise Agent Platform verwalten

1. Einführung

Die Gemini Enterprise Agent Platform ist eine offene Plattform zum Erstellen, Skalieren, Verwalten und Optimieren von KI-Agenten auf Unternehmensniveau, die auf Ihren Daten basieren.

Die Agent Runtime bietet die verwaltete Ausführungsumgebung für die sichere Ausführung von Agenten in Google Cloud, z. B. von Agenten, die mit dem Open-Source-Agent Development Kit (ADK) erstellt wurden.

In diesem Codelab wird gezeigt, wie Sie diese grundlegenden Bausteine verwenden, um einen von einem Nutzer in Gemini Enterprise initiierten Agenten zu steuern, wenn er sicher auf interne Tools zugreift.

KI-Agenten-Gateway

Agent Gateway ist die Netzwerkkomponente der Agent Governance-Suite der Plattform. Sie fungiert als Netzwerk-Ein- und -Ausgangspunkt für alle Agent-Interaktionen. So können Sicherheitsadministratoren eine zentrale Governance erzwingen, ohne dass Entwickler komplexe Netzwerkprimitive verwalten müssen.

Es gibt zwei primäre geregelte Zugriffspfade:

Client-to-Agent (Ingress): Schützt die Kommunikation zwischen externen Clients (z. B. Cursor oder Gemini CLI) und Ihren Agents.
Agent-to-Anywhere (Egress): Sichert die Kommunikation zwischen Agents, die in Google Cloud ausgeführt werden, und Servern, Tools oder APIs, die an einem beliebigen Ort ausgeführt werden.

In diesem Codelab konzentrieren Sie sich auf den Modus Agent zu beliebigem Ziel (ausgehend).

Zugriffssteuerung mit Agent Gateway

Um Sicherheitsrichtlinien zu erzwingen, ist Agent Gateway eng in das restliche Ökosystem eingebunden:

Agent Registry:Eine zentrale Bibliothek mit genehmigten Agenten und Tools (einschließlich MCP-Servern von Drittanbietern).
Agent Identity:Eine eindeutige, nachverfolgbare Identität für jeden Agenten, die automatisch mit End-to-End-mTLS gesichert wird.
Identity-Aware Proxy (IAP) und IAM:Die Standardebene zur Erzwingung, die die Identität des Agents anhand detaillierter IAM-Berechtigungen validiert, bevor Aufrufe bestimmter Tools zugelassen werden.
Model Armor:Eine KI-Sicherheitsvorkehrung, die über Service Extensions integriert wird, um Inhalte zu bereinigen und vor Prompt-Injection-Angriffen oder Datenlecks zu schützen.

Bereitstellungsmodi (öffentliche vs. private Netzwerke für Cloud Run)

Damit dieses Codelab zugänglich ist, können Sie zwischen zwei Netzwerkpfaden für Ihre internen Tools (MCP-Server) wählen, die in Cloud Run bereitgestellt werden:

Standard (öffentlicher Ingress): Die MCP-Server werden in Cloud Run mit öffentlichen Hostnamen (ingress=all) bereitgestellt. Der Traffic wird vom Agent über Standard-*.run.app-URLs zu den Tools weitergeleitet. Hierfür sind keine benutzerdefinierten DNS-Domains erforderlich. Dies ist die schnellste Möglichkeit, die Governance-Konzepte kennenzulernen.
Sicher (Private Networking): Eine optionale, vollständig private Architektur. Die MCP-Server sind eingeschränkt (ingress=internal-and-cloud-load-balancing) und werden über einen internen Application Load Balancer mit einer serverlosen NEG bereitgestellt. Dazu müssen Sie eine öffentliche DNS-Domain besitzen, um ein von Google verwaltetes Zertifikat bereitzustellen.

Sie wählen den bevorzugten Pfad bei der Konfiguration von Terraform aus.

Weitere Informationen zum Netzwerk-Endpunkt-Ingress für Cloud Run

Aufgaben

Kerninfrastruktur-Stack mit Terraform bereitstellen
Interne Tools als MCP-Server in Cloud Run erstellen und bereitstellen
ADK-Agent in Agent Runtime bereitstellen und PSC-Schnittstelle für ausgehenden Traffic verwenden
Agent Gateway-Diensterweiterungen für identitätsbasierten Zugriff (IAM) und Inhaltsprüfung (Model Armor) konfigurieren
Sichere End-to-End-Ausführung des Agents nachvollziehen und validieren

Voraussetzungen

Ein Webbrowser wie Chrome
Ein Google Cloud-Projekt mit aktivierter Abrechnung und Inhaberzugriff
IAM-Berechtigungen auf Organisationsebene (im Codelab werden Rollen mit Organisationsbereich gewährt)
Eine Domain, die Sie verwalten und die an Cloud DNS delegiert ist (für das öffentliche verwaltete Zertifikat)
Vertrautheit mit Terraform, gcloud und grundlegenden Google Cloud-Netzwerken

Codelab-Topologie

End-to-End-Architektur: Gemini Enterprise – Agent Runtime – Agent Gateway – MCP-Server in Cloud Run

In diesem Codelab stellen Sie einen End-to-End-Agenten für die Hypothekenprüfung bereit, der sicher mit drei internen Tools kommuniziert.

Zuerst stellen Sie die grundlegende Netzwerkinfrastruktur bereit, einschließlich einer VPC und eines internen Application Load Balancers, der als Agent Gateway konfiguriert ist. Als Nächstes stellen Sie drei MCP-Server (Model Context Protocol) in Cloud Run bereit. Diese Tools dienen als Ihre internen proprietären Tools:

Dokumentenmanagement (legacy-dms)
Geschäftliche E-Mail-Adresse (corporate-email)
Einkommensüberprüfung (income-verification)

Nachdem Sie die Tools eingerichtet haben, stellen Sie einen mit dem ADK erstellten Mortgage Assistant (mortgage-agent) in der Agent Runtime bereit. Sie konfigurieren diesen Agent so, dass er ein PSC-Interface für den privaten ausgehenden Traffic verwendet, und aktivieren die Laufzeit-Tool-Erkennung über die Agent Registry.

Um den Ablauf zu sichern, konfigurieren Sie Ihr Agent Gateway mit zwei Dienst-Extensions. Zuerst wird die Identität des Agents anhand von IAM-Richtlinien für das jeweilige Tool überprüft. So wird sichergestellt, dass der Agent nur auf autorisierte Tools zugreift.REQUEST_AUTHZ Zweitens werden die Prompts und Antworten des Agents mit einer CONTENT_AUTHZ-Erweiterung mit Model Armor geprüft.

Schließlich registrieren Sie den Agenten in Gemini Enterprise, lösen als Endnutzer eine Aufgabe zur Hypothekenbewertung aus und prüfen die sichere, geregelte Ausführung mit Cloud Trace.

Dieses Codelab richtet sich an Plattform- und Sicherheitstechniker aller Erfahrungsstufen. Die Bearbeitung dauert etwa 100 Minuten.

2. Hinweis

Projekt erstellen und authentifizieren

Erstellen Sie ein neues GCP-Projekt (oder verwenden Sie ein vorhandenes) mit aktivierter Abrechnung und authentifizieren Sie dann Cloud Shell oder Ihren lokalen Computer:

gcloud auth login
gcloud auth application-default login
gcloud config set project <your-project-id>

Bootstrap-APIs aktivieren

Das Fundamentmodul von Terraform aktiviert beim ersten Anwenden etwa 30 APIs. Für terraform init und den GCS-Status-Bucket ist jedoch ein kleiner Bootstrap-Satz erforderlich:

gcloud services enable \
  compute.googleapis.com \
  serviceusage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  storage.googleapis.com \
  dns.googleapis.com

Erforderliche Tools installieren

Installieren Sie die Toolchain. In Cloud Shell sind die meisten dieser Tools bereits vorhanden. Auf einer Workstation müssen Sie sie so installieren:

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
  sudo install skaffold /usr/local/bin/

# envsubst (gettext)
sudo apt-get install -y gettext-base

Außerdem benötigen Sie Terraform >= 1.12.2, Python 3.12+ und das Google Cloud SDK (gcloud).

Umgebungsvariablen festlegen

Im weiteren Verlauf des Codelabs wird davon ausgegangen, dass diese in Ihre Shell exportiert werden.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export ORG_ID=$(gcloud projects get-ancestors $PROJECT_ID | awk '$2 == "organization" {print $1}')
export REGION="us-central1"

# Only required if using the secure private networking path
export DOMAIN_NAME="agw.example.com"

Prüfen Sie, ob alle Variablen korrekt ausgefüllt wurden. Es sollten drei Werte zurückgegeben werden.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

Wenn Ihre Organisations-ID nicht automatisch ausgefüllt wird, können Sie sie manuell suchen und festlegen.

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. Repository klonen

git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git
cd cloud-networking-solutions
cd demos/agent-gateway

Kurzübersicht über die Inhalte des Demoverzeichnisses:

src/                MCP servers (legacy-dms, corporate-email, income-verification-api) + mortgage-agent
terraform/          Root Terraform config + modules (foundation, networking, agent-gateway, model-armor, ...)
cloudrun/           Cloud Run service definitions (rendered from .yaml.tmpl via envsubst)
scripts/            grant_agent_mcp_egress.sh — per-MCP IAP egressor binding
skaffold.yaml.tmpl  Skaffold pipeline that builds + deploys all three MCP services to Cloud Run

4. Terraform-Zustands-Bucket und Backend-Konfiguration erstellen

Erstellen Sie einen GCS-Bucket zum Speichern des Remote-Zustands und kopieren Sie dann die Backend-Vorlage:

gcloud storage buckets create gs://${PROJECT_ID}-tfstate \
  --location=${REGION} \
  --uniform-bucket-level-access

cp terraform/example.backend.conf terraform/backend.conf

Bearbeiten Sie terraform/backend.conf mit Ihren Werten:

bucket = "<your-project-id>-tfstate"
prefix = "agent-gateway"

5. (Optional) Öffentliche Cloud DNS-Zone erstellen

Standardmäßig ist für dieses Lab die Ingress-Konfiguration von Cloud Run auf all festgelegt und in der Agent Registry wird jeder MCP-Server unter seiner öffentlichen *.run.app-URL registriert. Es sind keine zusätzlichen DNS-, Zertifikats- oder Load-Balancer-Konfigurationen erforderlich. Wenn Sie zu privater Vernetzung wechseln möchten (Cloud Run mit ingress = internal-and-cloud-load-balancing hinter einem internen Application Load Balancer), benötigen Sie auch eine öffentliche Cloud DNS-Zone, damit Zertifikatmanager das LB-Zertifikat validieren kann.

Allgemeiner Ablauf des privaten Netzwerks

Allgemeiner Ablauf der Option für private Netzwerke

So verwenden Sie den Ansatz für private Netzwerke:

Öffentliche Cloud DNS-Zone erstellen – Zertifikatmanager validiert das regionale verwaltete Zertifikat, indem CNAMEs darin geschrieben werden:

gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

Die entsprechende private-Zone für mcp.${DOMAIN_NAME} (die vom internen Lastenausgleich und DNS-Peering von Agent Runtime verwendet wird) wird automatisch von Terraform erstellt. Sie müssen sie nicht manuell erstellen. Wenn das private Netzwerk deaktiviert ist, wird weder die öffentliche noch die private Zone bereitgestellt.

6. Terraform-Variablen konfigurieren

Kopieren Sie die Beispiel-TFVARS-Datei und bearbeiten Sie sie:

cp terraform/example.tfvars terraform/terraform.tfvars

Es gibt zwei Demopfade, die durch enable_cloud_run_private_networking gesteuert werden.

Standardpfad: Cloud Run mit öffentlichem Ingress

Einfachste Einrichtung:Für den Standardpfad müssen Sie nur drei Werte in terraform.tfvars bearbeiten. Jede andere Variable in der Datei hat bereits einen demofreundlichen Standardwert.

# GCP project ID where all resources will be created.
project_id = "my-gcp-project-id"

# GCP organization ID (numeric).
organization_id = "123456789012"

# Members granted demo-wide roles
platform_admin_members = ["user:admin@example.com"]

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = "DRY_RUN"

Privates Netzwerk (optional)

Legen Sie enable_cloud_run_private_networking = true fest und fügen Sie die folgenden Variablen hinzu, um den vollständigen sicheren Stack bereitzustellen:

Interner Application Load Balancer
Von Google verwaltetes Zertifikat
Cloud Run mit ingress = internal-and-cloud-load-balancing
DNS-Peering für Agent Gateway.

enable_cloud_run_private_networking = true

# DNS — must end with a trailing dot, must match a Cloud DNS zone you own
dns_zone_domain            = "agw.example.com."
enable_certificate_manager = true

# mcp_internal_dns_zone.domain MUST be a real subdomain of dns_zone_domain so
# Certificate Manager can issue a Google-managed cert.
mcp_internal_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

# Must match mcp_internal_dns_zone.domain so Agent Engine resolves MCP
# hostnames over the PSC interface peering.
psc_interface_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

mcp_lb_protocol = "HTTPS"

7. Infrastruktur mit Terraform bereitstellen

Initialisieren, überprüfen und anwenden:

cd terraform
terraform init -backend-config=backend.conf
terraform plan -out=tfplan
terraform apply tfplan

terraform apply stellt etwa 40 Ressourcen auf dem Standardpfad bereit und dauert bei einem neuen Projekt 8–10 Minuten (etwa 60 Ressourcen / 15–20 Minuten bei enable_cloud_run_private_networking = true). Es werden folgende Ressourcen erstellt:

Projektgrundlage (APIs, Dienstidentitäten, Kontingente)
VPC, Subnetze (primär, nur Proxy, PSC, PSC-Schnittstelle, Agent Gateway-Colocation), Cloud NAT, Firewallregeln
Artifact Registry-Repository für Cloud Run-Images
Drei Cloud Run-Dienste + Laufzeit-Dienstkonten pro Dienst (Eingang = all standardmäßig; internal-and-cloud-load-balancing, wenn privates Netzwerk aktiviert ist)
Model Armor-Vorlage + IAM
Agent Gateway, PSC-I-Netzwerkverbindung, IAP- und Model Armor-Erweiterungen, beide Autorisierungsrichtlinien und die roles/iap.egressor-Gewährung auf Projektebene
Agent Registry-Endpunkte (Vertex AI, IAP, Discovery Engine usw.) sowie die drei MCP-Server (standardmäßig unter *.run.app/mcp registriert; unter ./mcp, wenn das private Netzwerk aktiviert ist)

Nur, wenn enable_cloud_run_private_networking = true:

Interner regionaler Application Load Balancer mit serverloser NEG (URL-Masken-Routing) + private DNS-A-Einträge
Private DNS-Zone für MCP (mcp..), die an die VPC angehängt ist
Modul für öffentliche DNS-Zonen (DNS-Autorisierungen für Zertifikatmanager) + regionales von Google verwaltetes Zertifikat
PSC-Schnittstellen-DNS-Zone (verwaist, wenn keine privaten Hostnamen aufgelöst werden müssen, daher auch vom Master-Flag abhängig)
Agent Gateway DNS-Peering für mcp.. (automatisch vorangestellt)

8. Agent Registry-Endpunkte prüfen

Agent Registry ist ein projektbezogener Katalog von Diensten (Google-APIs und Ihre eigenen MCP-Server), die ein Agent zur Laufzeit erkennt. Der Hypotheken-Agent liest sie beim Start und bindet Tools dynamisch. Es sind keine MCP-URLs im Agentencode oder im Bereitstellungsbefehl enthalten.

Endpunkte

Was Terraform in Ihrem Namen ausgeführt hat: Für jede Google API in agent_registry_google_apis wurden fünf Varianten registriert (global, globales mTLS, regional, regionales mTLS, regionales REP). Zum Beispiel für aiplatform:

gcloud alpha agent-registry services create aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-mtls \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform mTLS" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.mtls.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create ${REGION}-aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Locational" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://${REGION}-aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-${REGION}-rep \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Regional (REP)" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.${REGION}.rep.googleapis.com,protocolBinding=JSONRPC"

MCP-Server

Mit Terraform werden auch die drei MCP-Server für Sie registriert. Wenn Sie andere MCP-Server registrieren möchten, können Sie der Anleitung in der Dokumentation folgen.

gcloud alpha agent-registry services create legacy-dms \
--project=${PROJECT_ID} \
--location=${REGION} \
--display-name="Legacy DMS" \
--mcp-server-spec-type=tool-spec \
--mcp-server-spec-content=src/legacy-dms/toolspec.json \
--interfaces=url=https://dms.${DOMAIN_NAME}/mcp,protocolBinding=JSONRPC

Prüfen Sie die registrierten Endpunkte und MCP-Server.

gcloud alpha agent-registry services list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

Quelle: terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl

9. Konfiguration des KI-Agenten-Gateways prüfen

Das Agent Gateway ist eine von Google verwaltete Governance-Ebene zwischen der Agent Runtime und Ihren Tools. Im AGENT_TO_ANYWHERE-Modus ist es an die Agenten-Registry des Projekts gebunden und der ausgehende Traffic erfolgt über eine kundeneigene PSC-Schnittstelle, sodass private MCP-Server in Ihrer VPC erreicht werden können.

Wenn Sie dieses Gateway manuell importieren würden, sähe das YAML so aus:

# agent-gateway.yaml — for reference only, Terraform already created this
name: agent-gateway
protocols: [MCP]
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJECT_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/agent-gateway-na
  dnsPeeringConfig:
    domains:
      - mcp.${DOMAIN_NAME}.
    targetProject: ${PROJECT_ID}
    targetNetwork: projects/${PROJECT_ID}/global/networks/gateway-vpc

gcloud alpha network-services agent-gateways import agent-gateway \
  --source=agent-gateway.yaml \
  --location=${REGION}

Prüfen Sie, ob das Gateway von Terraform erstellt wurde:

gcloud alpha network-services agent-gateways describe agent-gateway \
  --location=${REGION}

10. IAP- und Model Armor-Autorisierung prüfen

Agent Gateway delegiert die Autorisierung an Diensterweiterungen. Für die Demo gelten zwei Richtlinienprofile:

REQUEST_AUTHZ: Wird einmal pro Anfrage in der Header-Phase ausgewertet. Wird hier verwendet, um IAP aufzurufen. Damit wird geprüft, ob die Identität des aufrufenden Agents roles/iap.egressor auf dem Ziel-MCP-Server hat.
CONTENT_AUTHZ: Streamt Body-Ereignisse zur Bereinigung von Inhalten an die Erweiterung. Wird hier verwendet, um Model Armor aufzurufen, das über Sensitive Data Protection (SDP) nach Prompt Injections, Jailbreaks, Verstößen gegen die Grundsätze für verantwortungsvolle KI und (optional) personenidentifizierbaren Informationen sucht.

IAP-Erweiterung REQUEST_AUTHZ

cat > iap-authz