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.

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, sodass Sicherheitsadministratoren eine zentrale Governance erzwingen können, ohne dass Entwickler komplexe Netzwerkprimitiven verwalten müssen.

Es ermöglicht zwei primäre kontrollierte Zugriffspfade:

  • Client-to-Agent (Ingress): Sichert die Kommunikation zwischen externen Clients (z. B. Cursor oder Gemini CLI) und Ihren Agents.
  • Agent-to-Anywhere (ausgehender Traffic): 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 (ausgehender Agententraffic).

Zugriffssteuerung mit Agent Gateway

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

  • Agent Registry:Eine zentrale Bibliothek mit genehmigten Agents und Tools (einschließlich MCP-Servern von Drittanbietern).
  • Agentenidentität: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 Durchsetzung, die die Identität des Agenten 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:

  1. 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 geleitet. Hierfür sind keine benutzerdefinierten DNS-Domains erforderlich. Dies ist die schnellste Möglichkeit, die Governance-Konzepte kennenzulernen.
  2. 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 den Egress 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 Hypothekenassistenten (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 die einzelnen Tools ü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. Bucket für den Terraform-Zustand und Back-End-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

Ersetzen Sie terraform/backend.conf durch Ihre Werte:

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 Agenten-Registry wird jeder MCP-Server unter seiner öffentlichen *.run.app-URL registriert. Es sind keine zusätzlichen DNS-, Zertifikate oder Load Balancer 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 Load Balancer-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:

  1. Ö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 MCP-LB und vom 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 eingeschränkt werden.

Standardpfad: Cloud Run mit öffentlichem Ingress

**Einfachste Einrichtung**: Für den Standardpfad müssen Sie nur drei Werte in terraform.tfvars bearbeiten. Für alle anderen Variablen in der Datei ist bereits ein demofreundlicher Standardwert festgelegt.

# 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
terraform apply

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 durch das Master-Flag gesteuert)
  • Agent Gateway DNS-Peering für mcp.. (automatisch vorangestellt)

8. Agent Registry-Endpunkte prüfen

Die 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-Laufzeit und Ihren Tools. Im AGENT_TO_ANYWHERE-Modus ist es an die Agenten-Registry des Projekts gebunden und wird über eine vom Kunden bereitgestellte PSC-Schnittstelle ausgegeben, damit es private MCP-Server in Ihrer VPC erreichen kann.

Wenn Sie dieses Gateway manuell importieren, sieht 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 Körperereignisse zur Bereinigung von Inhalten an die Erweiterung. Wird hier verwendet, um Model Armor aufzurufen, das Prompts auf Prompt Injection, Jailbreaks, Verstöße gegen die Grundsätze für verantwortungsvolle KI und (optional) personenidentifizierbare Informationen über Sensitive Data Protection (SDP) prüft.

IAP-Erweiterung REQUEST_AUTHZ

cat > iap-authz-extension.yaml <<EOF
name: agent-gateway-iap-authz
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-iap-authz \
  --source=iap-authz-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

Binden Sie es mit einer REQUEST_AUTHZ-Richtlinie an das KI-Agenten-Gateway:

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-iap-policy" \
  -d '{
    "name": "agent-gateway-iap-policy",
    "policyProfile": "REQUEST_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-iap-authz"
        ]
      }
    }
  }'

Model Armor-Erweiterung CONTENT_AUTHZ

Die metadata.model_armor_settings der Erweiterung enthält die Vorlagen-IDs für Anfragen und Antworten, die von Model Armor zum Bewerten der einzelnen Callouts verwendet werden:

cat > ma-extension.yaml <<EOF
name: agent-gateway-ma-authz
service: modelarmor.${REGION}.rep.googleapis.com
failOpen: true
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id":  "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-request-template",
      "response_template_id": "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-response-template"
    }
  ]'
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-ma-authz \
  --source=ma-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-ma-policy" \
  -d '{
    "name": "agent-gateway-ma-policy",
    "policyProfile": "CONTENT_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-ma-authz"
        ]
      }
    }
  }'

Benutzerdefinierte DLP-Vorlagen

sdpSettings.basicConfig von Model Armor verwendet eine integrierte Liste von Informationstypen. Für eine genauere Steuerung (benutzerdefinierte InfoTypes, Teilmaskierung, Surrogate-Ersetzung, Entfernung nach Wahrscheinlichkeit) verweisen Sie Model Armor über sdpSettings.advancedConfig auf Ihre eigenen Cloud DLP-Vorlagen für inspect und de-identify.

Erstellen Sie eine Prüfvorlage, die US-Sozialversicherungsnummern mit einer Wahrscheinlichkeit von POSSIBLE oder höher kennzeichnet:

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates" \
  -d '{
    "templateId": "agw-ssn-inspect-template",
    "inspectTemplate": {
      "displayName": "SSN Inspect Template",
      "inspectConfig": {
        "infoTypes": [
          { "name": "US_SOCIAL_SECURITY_NUMBER" }
        ],
        "minLikelihood": "POSSIBLE"
      }
    }
  }'

Erstellen Sie eine Vorlage zum De-Identifizieren, die jedes Ergebnis durch das entsprechende InfoType-Token ersetzt, z.B. [US_SOCIAL_SECURITY_NUMBER]:

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates" \
  -d '{
    "templateId": "agw-ssn-redaction-template",
    "deidentifyTemplate": {
      "displayName": "SSN Redaction Template",
      "deidentifyConfig": {
        "infoTypeTransformations": {
          "transformations": [{
            "primitiveTransformation": { "replaceWithInfoTypeConfig": {} }
          }]
        }
      }
    }
  }'

Weisen Sie dann die Antwortkonfiguration einer Model Armor-Vorlage über sdpSettings.advancedConfig dem Paar zu (hier würde das Terraform-Modul model_armor advanced_config festlegen, wenn Sie es eingerichtet hätten):

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate":    "projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template",
        "deidentifyTemplate": "projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template"
      }
    }
  }
}

IAP-Egressor-IAM (nur pro MCP-Server)

Terraform erstellt keine projektweite roles/iap.egressor-Bindung in der impliziten IAP-Agent-Registrierung. Die Bindung, die IAP REQUEST_AUTHZ tatsächlich auswertet, gilt pro MCP-Server und pro Reasoning Engine. Sie wird gewährt, nachdem der Agent bereitgestellt wurde und Sie die Agent-ID kennen. Im Schritt „Grant the agent per-MCP-server egress“ (Agenten-Egress pro MCP-Server gewähren) wird scripts/grant_agent_mcp_egress.sh ausgeführt.

11. MCP-Server erstellen und in Cloud Run bereitstellen

In den Dateien cloudrun/*.yaml.tmpl und skaffold.yaml.tmpl wird auf ${PROJECT_ID}, ${REGION} und ${MCP_INGRESS} (die Cloud Run-Ingress-Annotation) verwiesen. MCP_INGRESS aus einer Terraform-Ausgabe abrufen, damit die gerenderten Manifeste mit enable_cloud_run_private_networking synchronisiert bleiben, und dann mit envsubst rendern:

Cloud Run-Konfiguration für eingehenden Traffic exportieren

  • all
  • internal-and-cloud-load-balancing (bei Verwendung des Ansatzes für private Netzwerke)
export MCP_INGRESS=all

envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < skaffold.yaml.tmpl > skaffold.yaml
for f in cloudrun/*.yaml.tmpl; do
  envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < "$f" > "${f%.tmpl}"
done

Jeder Cloud Run-Dienst wird als Laufzeit-SA pro Dienst ausgeführt, die von Terraform erstellt wurde (z.B. mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com). Wenn Sie als diese SAs bereitstellen möchten, benötigen Sie roles/iam.serviceAccountUser:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="user:$(gcloud config get-value account)" \
  --role="roles/iam.serviceAccountUser"

Mit Cloud Build erstellen und mit Skaffold bereitstellen:

skaffold run

Skaffold erstellt drei Images (legacy-dms, corporate-email, income-verification-api) in Ihrem Artifact Registry-Repository und aktualisiert jeden Cloud Run-Dienst, sodass er auf den neuen Digest verweist.

Bestätigen:

gcloud run services list --region=${REGION}

Alle drei Dienste sollten den Status ACTIVE haben.

12. Hypotheken-Agent in der Laufzeit für KI-Agenten bereitstellen

Installieren Sie die Abhängigkeiten des Agents und stellen Sie ihn bereit:

cd src/mortgage-agent
uv sync

uv run python deploy_agent.py \
  --project=${PROJECT_ID} \
  --region=${REGION} \
  --enable-agent-identity \
  --agent-name=mortgage-agent \
  --agent-gateway=projects/${PROJECT_ID}/locations/${REGION}/agentGateways/agent-gateway \
  --model-endpoint-location=global

Wenn das Skript abgeschlossen ist, kopieren Sie die ausgegebene reasoningEngines/ in Ihre Shell:

export AGENT_ID=<numeric-id-from-output>
cd ../..

13. Ausgehender Traffic pro MCP-Server für den Agenten gewähren

Die IAP-Erweiterung REQUEST_AUTHZ autorisiert jeden Tool-Aufruf, indem sie die roles/iap.egressor des KI-Agents auf dem bestimmten MCP-Server oder Endpunkt prüft, den er aufruft. Weitere Informationen finden Sie unter Egress-Richtlinie für die Verbindung zwischen Agent und MCP-Server erstellen.

Das Script (scripts/grant_agent_mcp_egress.sh) listet die MCP-Server in der Agent Registry unter projects/${PROJECT_ID}/locations/${REGION} auf und führt eine roles/iap.egressor-Bindung für das Agent-Hauptkonto in die IAM-Richtlinie jedes Servers ein (entsprechend der gcloud add-iam-policy-binding-Semantik).

Anwendungsfall 1: Bedingungslose Gewährung mit Beschränkung auf bestimmte MCP-Server

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "legacy-dms income-verification"

Anwendungsfall 2: Bedingte Gewährung (CEL), die auf einen bestimmten MCP-Server beschränkt ist

Wenn Sie den Zugriff des Agenten auf eine Teilmenge von Tools auf einem einzelnen MCP-Server beschränken möchten, hängen Sie eine IAM-Bedingung an. Das Agent Gateway veröffentlicht Attribute pro Tool, die von IAP REQUEST_AUTHZ für CEL verfügbar gemacht werden, darunter:

  • iap.googleapis.com/mcp.toolName
  • iap.googleapis.com/mcp.tool.isReadOnly
  • iap.googleapis.com/request.auth.type.

Beschränken Sie den Agent auf schreibgeschützte Tools auf corporate-email:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "corporate-email" \
  --condition-expression "api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

Danach geben Schreibtools auf corporate-email 403 PermissionDenied von IAP REQUEST_AUTHZ zurück. Nur-Lese-Tools funktionieren weiterhin.

Bindungen prüfen

Rufen Sie den Tab „Richtlinien“ auf. Dort sehen Sie die Liste der Richtlinien, die für die Endpunkte und MCP-Server erstellt wurden.

Weitere Anwendungsfälle:

Bedingungslose Erteilung auf jedem MCP-Server, beschränkt auf einen Agenten

Führen Sie diesen Befehl nach jeder erneuten Bereitstellung des Agents aus. Ohne Filter und ohne Bedingung erhält der benannte Agent roles/iap.egressor auf jedem MCP-Server in der Registry:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID}

14. KI‑Agenten in der Agent Platform Console testen

Die Agent Platform-Konsole enthält einen Playground, in dem Sie direkt mit dem bereitgestellten Agenten chatten können. So können Sie Tool-Aufrufe am schnellsten testen und Traces prüfen, bevor Sie den Agent in Gemini Enterprise einbinden.

  1. Öffnen Sie in der Google Cloud Console die Seite Agent Platform Deployments (Bereitstellungen der Agent-Plattform).
  2. Verwenden Sie das Feld Filter, um die Liste der Laufzeiten einzugrenzen, und klicken Sie dann auf die gewünschte mortgage-agent-Laufzeit.
  3. Öffnen Sie den Tab Playground.
  4. Geben Sie einen Prompt ein, um mit dem KI-Agenten zu chatten:
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Sie sollten eine Antwort vom Dokumentverwaltungstool und vom Tool zur Einkommensüberprüfung erhalten. Sozialversicherungsnummern sollten in dieser Antwort unkenntlich gemacht werden. 5. Geben Sie eine weiterführende Frage ein:

Can you send a summary of this to my email jane@example.com

Der Agent sollte erkennen, dass er keinen Zugriff auf das Tool „send_email“ hat, und entsprechend reagieren.

Da der Agent mit OpenTelemetry-Instrumentierung bereitgestellt wurde, bietet das Playground vier Seitenleistenansichten, zwischen denen Sie während der Antwort des Agents wechseln können:

  • Trace: Vollständige Traces der Unterhaltung, einschließlich der Spans für Agent Gateway, IAP REQUEST_AUTHZ und Model Armor CONTENT_AUTHZ
  • Ereignis: Ein Diagramm der aufgerufenen Tools und Ereignisdetails für den aktuellen Zug
  • Status: Der Sitzungsstatus des KI-Agenten und die Tool-Ein- und ‑Ausgaben
  • Sitzungen: Jede Sitzung, die Sie für diese Laufzeit gestartet haben

15. IAP-Autorisierung erzwingen

Nachdem wir die Bereitstellung validiert haben, können wir den IAP-Erzwingungsmodus auf null aktualisieren, um die Richtlinien zu erzwingen. Öffnen Sie terraform.tfvars und ändern Sie den Modus von DRY_RUN in null.

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

Übernehmen Sie die Änderung.

terraform apply

Kehren Sie zum Playground zurück und versuchen Sie die Unterhaltung noch einmal.

  1. Öffnen Sie in der Google Cloud Console die Seite Agent Platform Deployments (Bereitstellungen der Agent-Plattform).
  2. Verwenden Sie das Feld Filter, um die Liste der Laufzeiten einzugrenzen, und klicken Sie dann auf die gewünschte mortgage-agent-Laufzeit.
  3. Öffnen Sie den Tab Playground.
  4. Geben Sie einen Prompt ein, um mit dem KI-Agenten zu chatten:
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Sie sollten eine Antwort vom Dokumentverwaltungstool und vom Tool zur Einkommensüberprüfung erhalten. Sozialversicherungsnummern sollten in dieser Antwort unkenntlich gemacht werden. 5. Geben Sie eine weiterführende Frage ein:

Can you send a summary of this to my email jane@example.com

Wenn alles richtig eingerichtet wurde, sollte der Agent antworten, dass er die E‑Mail aufgrund der Autorisierungsrichtlinie nicht senden kann.

16. Gemini Enterprise einrichten und testen

Gemini Enterprise einrichten

Folgen Sie der Anleitung für die ersten Schritte mit Gemini Enterprise.

ADK-Agenten bei Gemini Enterprise registrieren

Folgen Sie dieser Anleitung, um unseren Agenten in Gemini Enterprise zu registrieren.

  1. Rufen Sie in der Google Cloud Console die Seite Gemini Enterprise auf.
  2. Wählen Sie die Gemini Enterprise-App aus, in der der Agent registriert ist.
  3. Öffnen Sie die URL, die im Bereich Ihre Gemini Enterprise-Webanwendung ist bereit angezeigt wird.
  4. Wählen Sie im Menü auf der linken Seite den Tab Agent aus, um die Agentengalerie zu öffnen.
  5. Wählen Sie Mortgage Assistant Agent aus und beginnen Sie mit dem Chatten.

Probieren Sie dieselben Prompts aus dem Agent Runtime Playground aus:

Ausgangsprompt:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Weiterführende Frage:

Can you send a summary of this to my email jane@example.com

Wenn Sie in der Konsole zum Abschnitt „Agent Deployment“ (Agent-Bereitstellung) zurückkehren, unsere Agent-Bereitstellung auswählen und zum Tab „Traces“ (Traces) wechseln, sehen Sie jetzt den Gemini Assistant-Agenten im Bereich, in dem der Aufruf von Gemini Enterprise stammt.

17. Fehlerbehebung und häufige Lösungen

  • terraform apply schlägt im Agent-Gateway mit der Meldung „resource is being created and therefore can not be updated“ (Ressource wird erstellt und kann daher nicht aktualisiert werden) fehl: Es dauert etwa 30 Sekunden, bis das Mandantenprojekt des Gateways bereit ist, bevor Autorisierungsrichtlinien angehängt werden können. Das Modul time_sleep.wait_for_gateway übernimmt das. Führen Sie einfach terraform apply noch einmal aus.
  • Der KI‑Agent meldet „Keine MCP-Server gefunden“ oder wird nur mit Dienstprogrammen gestartet – bestätigen Sie enable_agent_registry_endpoints = true in terraform.tfvars und gehen Sie dann so vor:
    gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION}
    Sie sollten drei Einträge sehen (einen pro Cloud Run-MCP-Dienst). Wenn die Liste leer ist, prüfen Sie, ob die MCP-Dienste innerhalb der VPC erreichbar sind und ob das Agent Gateway die Registry gefüllt hat. Das geschieht erst beim ersten Proxied Tool List-Aufruf.
  • Tool-Aufrufe geben „403 PermissionDenied“ zurück – führen Sie scripts/grant_agent_mcp_egress.sh noch einmal aus. Die häufigste Ursache ist, dass die Berechtigungen nach der erneuten Bereitstellung des Agents nicht neu erteilt wurden. Die reasoningEngines/ ändert sich bei jeder Bereitstellung.
  • skaffold run schlägt mit „Berechtigung für Dienstkonto verweigert“ fehl – Sie benötigen roles/iam.serviceAccountUser. Führen Sie die Selbsterteilung im vorherigen Schritt noch einmal aus.
  • DNS-Peering-Fehler von Agent Gateway zu MCP LB: Prüfen Sie, ob agent_gateway_dns_peering_config.target_network genau mit projects/${PROJECT_ID}/global/networks/${VPC_NAME} übereinstimmt und ob jeder domains-Eintrag mit einem nachgestellten Punkt endet.
  • terraform plan möchte immer wieder Cloud Run-Image-Tags aktualisieren – das sollte aufgrund der lifecycle { ignore_changes }-Regel nicht passieren. Wenn das der Fall ist, prüfen Sie, ob Sie mcp_services[*].image in terraform.tfvars nach skaffold run bearbeitet haben.

18. Bereinigen

Die Reasoning Engine wird nicht von Terraform verwaltet (sie wird vom ADK SDK erstellt). Manuell löschen:

gcloud beta ai reasoning-engines delete ${AGENT_ID} \
  --region=${REGION} --project=${PROJECT_ID}

Entfernen Sie alle von Terraform erstellten Ressourcen:

cd terraform
terraform destroy
cd ..

Wenn Sie die öffentliche DNS-Zone nur für dieses Codelab erstellt haben:

gcloud dns managed-zones delete agw-example-com

Löschen Sie schließlich den Terraform-Zustands-Bucket:

gcloud storage rm -r gs://${PROJECT_ID}-tfstate

19. Glückwunsch

Glückwunsch! Sie haben mithilfe von Agent Gateway eine umfassende Agent-Governance für einen ADK-Agenten mit mehreren Tools implementiert. Als zentralisierte Netzwerksteuerungsebene ermöglichte das Agent Gateway einen sicheren Ausgangspfad zu privaten Tools, die Durchsetzung detaillierter identitätsbasierter IAM-Richtlinien über Identity-Aware Proxy und die Bereinigung von Inhaltsinteraktionen mithilfe integrierter Model Armor-Schutzmaßnahmen.

Das haben Sie gelernt

  • So stellen Sie das Agent Gateway als zentrale Governance-Ebene für den ausgehenden Traffic von Agenten zu beliebigen Zielen bereit und konfigurieren es.
  • So integrieren Sie die Agent Registry für die kontrollierte, dynamische Ermittlung von Laufzeittools.
  • So schreiben und erzwingen Sie tool- und bedingungsbasierte IAM-Richtlinien, um die Ausführungspfade von Agents streng zu kontrollieren.
  • Wie Sie Agent Gateway-Diensterweiterungen nutzen, um Model Armor-Richtlinien anzuwenden und sensiblen Agent-Traffic automatisch abzufangen und zu entfernen.

Referenzdokumente