Ausgehender Traffic des Agent-Gateways von Agent Runtime zum VPC-Netzwerk

1. Einführung

In diesem Codelab wird die Agent Gateway-Ausgangssteuerung für KI-Agents untersucht, die über ein privates VPC-Netzwerk auf Remote-Endpunkte zugreifen. Das Agent Gateway im Egress-Modus (agent-to-anywhere) unterstützt private Verbindungen zu einem VPC-Netzwerk über Private Service Connect-Schnittstellen (PSC). In diesem Szenario verwendet die Agent-Laufzeit Agent Gateway, um über einen Private Service Connect-Endpunkt (PSC) für Google APIs im VPC-Netzwerk auf einen Remote-streamable HTTP MCP-Server zuzugreifen, der in Cloud Run gehostet wird.

KI-Apps, von eigenständigen Chatbots bis hin zu autonomen Systemen mit Workflows mit mehreren Agenten, können externe Tools dynamisch aufrufen. Es ist wichtig, dass Agenten kontrollierten Zugriff haben, um Datenbanken abzufragen, Webinhalte abzurufen und Aktionen auszuführen. So können Sie sichere und produktive Agenten entwickeln. In Unternehmensumgebungen ist die Sicherung der Ausführung von Agent-Tools jedoch eine Herausforderung. Wenn ein Agent direkten Netzwerkzugriff hat, können durch Prompt-Injection-Angriffe oder Modellhalluzinationen sensible Daten exfiltriert oder destruktive Befehle ausgeführt werden.

Um autonome Agents im großen Maßstab zu verwalten, bietet Agent Gateway einen zentralen Zero-Trust-Durchsetzungspunkt, der direkt in die Architektur der Agent Platform integriert ist. Anstatt auf benutzerdefinierte Implementierungen zu setzen, die für jede Anwendung oder jeden Agentencode eindeutig sind, bietet Agent Gateway Netzwerkrouting, Agentenverwaltung und Laufzeitsicherheit auf Plattformebene.

Wenn das Agenten-Gateway im Ausgangsmodus (agent-to-anywhere) ausgeführt wird, werden alle ausgehenden Anfragen von Agenten, die für die Verwendung des Gateways konfiguriert sind, über das Gateway weitergeleitet. Jede Anfrage für die Arbeitslast eines Agenten wird mit der eindeutigen Agentenidentität authentifiziert und mit Identity-Aware Proxy (IAP)-Richtlinien autorisiert. MCP-Tool-Aufrufe werden dynamisch decodiert und auf die Einhaltung von Richtlinien geprüft. Sicherheitsadministratoren können detaillierte Berechtigungen zentral erzwingen, damit Agents nur genehmigte Endpunkte und Methoden aufrufen können.

Was Sie erstellen

  • Agent Gateway im Egress-Modus (agent-to-anywhere)
  • IAP-Autorisierungserweiterung (Identity-Aware Proxy)
  • ADK-Agent für Agent Runtime mit Agentenidentität
  • Streamfähiger HTTP-MCP-Server für Cloud Run
  • Agent Registry mit Google API und benutzerdefinierten MCP-Endpunkten
  • Autorisierungsrichtlinien mit IAM-Zugriffssteuerung
  • VPC-Netzwerkressourcen, Cloud DNS-Zone und PSC-Endpunkt für Google APIs
  • PSC-Netzwerkanhang für ausgehenden Agent Gateway-Traffic
  • Cloud Next Generation Firewall (NGFW)-Firewallrichtlinienregeln

figure1

Abbildung 1. Codelab-Architektur

Lerninhalte

  • KI-Agenten-Gateway in einer strukturierten Konfigurationssequenz bereitstellen
  • Agent Gateway mit privater VPC-Netzwerkverbindung konfigurieren
  • Autorisierungsrichtlinien vom Probelauf- in den Erzwingungsmodus umstellen
  • Google API-Endpunkte und MCP-Server in der Agent Registry registrieren
  • Agent Gateway-Logs prüfen, um die Ausgangssteuerung zu validieren
  • Agent Gateway-Egress-Traffic mit Cloud NGFW-Logs validieren

Voraussetzungen

  • Ein Google Cloud-Projekt mit aktivierter Abrechnung
  • IAM-Berechtigungen zum Bereitstellen von Netzwerkdiensten, BigQuery-Datasets und Agent Platform-Ressourcen
  • Eine POSIX-kompatible Shell (bash oder zsh) mit installierter Google Cloud CLI (gcloud- und bq-Komponenten)
  • Befehlszeilentools: git, curl, jq (JSON-Prozessor), Python 3 und uv (Python-Paketmanager)

2. Konzepte

Bereitstellungsreihenfolge

In diesem Codelab wird eine strukturierte Konfigurationsreihenfolge verwendet, damit Agents beim Initialisieren Zugriff auf die erforderlichen Ressourcen haben und die Verbindung bestätigt werden kann, bevor erzwungene Zugriffsrichtlinien angewendet werden.

In diesem Codelab wird die folgende Bereitstellungsreihenfolge verwendet:

  1. Im DRY_RUN-Modus starten:Achten Sie darauf, dass Agent-Anfragen erfolgreich am Gateway eingehen und durchlaufen werden (nur Prüfmodus).
  2. Alle Dienste registrieren:Registrieren Sie alle agentischen Komponenten in der Agent Registry und bestätigen Sie den Zugriff auf Agent-Tools. Verwenden Sie Cloud Logging und das Dashboard für die Beobachtbarkeit des Agent Gateway, um Anfragen an die Agent Registry aufzurufen.
  3. Autorisierungsrichtlinien erstellen:Erstellen und wenden Sie Autorisierungsrichtlinien an, um ausgehenden Traffic von Agents zu MCP-Servern und -Endpunkten zuzulassen.
  4. Zum ENFORCED-Modus wechseln:Aktualisieren Sie die Autorisierungserweiterungsrichtlinie, um Richtlinien zu erzwingen und nicht autorisierten ausgehenden Traffic zu blockieren.

figure2

Abbildung 2. Bereitstellungssequenz

Topologie für das Routing von ausgehendem Traffic

Der ausgehende Traffic des Agent-Gateways (agent-to-anywhere) fungiert als zentraler, Zero-Trust-Ausgangsproxy für agentische Arbeitslasten. Wenn ein Agent eine Anfrage an ein externes Tool oder eine externe API sendet, wird die ausgehende Anfrage von Agent Gateway abgefangen und anhand von Governance-Richtlinien ausgewertet, bevor sie an ihr Ziel weitergeleitet wird. In einer Google Cloud Agent Platform-Architektur bietet Agent Gateway Datenebenenkonnektivität für:

  • Private Netzwerke (VPC): Ausgehender Traffic, der auf interne Unternehmens-APIs, Microservices und Datenbanken ausgerichtet ist, die in privaten VPCs gehostet werden, sowie auf lokale oder cloudübergreifende Netzwerke, die über hybride Verbindungen erreichbar sind.
  • Externe Netzwerke (Internet): Ausgehender Traffic, der auf Webdienste von Drittanbietern, SaaS-APIs oder öffentliche Endpunkte ausgerichtet ist.
  • KI-Dienste und Agent Platform:Ausgehender Traffic, der auf verwaltete Google Cloud-APIs, Foundation Models, Google MCP-Endpunkte (z. B. BigQuery) und Plattform-Governance-Dienste (Agent Registry und IAP-Richtlinien) ausgerichtet ist.

figure3

Abbildung 3. Topologie für das Routing von ausgehendem Traffic über Agent Gateway

In diesem Codelab geht es um ausgehenden Traffic von einem benutzerdefinierten Agent in der Agent Runtime, der auf einen PSC-Endpunkt für Google APIs ausgerichtet ist, der in einem VPC-Netzwerk bereitgestellt wird. Diese Architektur ermöglicht den privaten Zugriff auf den MCP-Server, der in Cloud Run gehostet wird, indem der PSC-Netzwerk-Anhang für den Agent Gateway-Ausgang verwendet wird.

VPC-Konnektivität

Agent Gateway-Egress (agent-to-anywhere) kann eine Verbindung zu einem VPC-Netzwerk herstellen, indem Sie networkConfig: egress: networkAttachment: [URI] in der YAML-Konfigurationsdatei für das Deployment angeben. Mit dieser Einstellung werden Routingregeln im Agent Gateway konfiguriert, um Traffic, der in private IP-Adressen aufgelöst wird, über die PSC-Netzwerkverbindung in das VPC-Netzwerk zu senden.

figure4

Abbildung 4. VPC-Konnektivität für Agent Gateway

Agent Gateway kann private DNS-Hostnamen mithilfe von Cloud DNS-Peering zu einem angegebenen Zielprojekt und VPC-Netzwerk auflösen. Für alle privaten Zonen, die in der dnsPeeringConfig: domains: [NAME]-Konfiguration aufgeführt sind, werden Cloud DNS-Einträge im Zielprojekt verwendet. Für alle anderen DNS-Abfragen wird der öffentliche Standard-VPC-Cloud DNS-Resolver verwendet.

Damit sind wir mit den Konzepten fertig. Weiter geht es mit dem Abschnitt Einrichtung.

3. Einrichtung

Erforderliche IAM-Rollen

Die folgenden Rollen sind erforderlich, um die Ressourcen in diesem Codelab zu erstellen:

Kategorie

Erforderliche IAM-Rolle (ID)

Beschreibung

API-Verwaltung

roles/serviceusage.serviceUsageAdmin

Google Cloud API-Dienste aktivieren

Netzwerk und Gateway

roles/networkservices.admin

KI-Agenten-Gateway bereitstellen

Service Extensions

roles/serviceextensions.admin

Routing-Erweiterungen konfigurieren

Netzwerksicherheit

roles/networksecurity.admin

Autorisierungsrichtlinien bereitstellen

Agent Registry

roles/agentregistry.admin

Zulässige Hosts für Kataloge

Vertex AI und Agents

roles/aiplatform.admin

Agent Runtime-Arbeitslasten bereitstellen

Richtlinien für ausgehenden Traffic

roles/iap.admin

roles/iap.egressor-Richtlinien anwenden

Cloud Storage

roles/storage.admin

Bereitstellungs-Staging-Buckets verwalten

Logs und Prüfung

roles/logging.viewer

Traces und Audit-Logs prüfen

Cloud Run-Entwickler

roles/run.developer

Cloud Run-Dienste bereitstellen

Artifact Registry-Leser

roles/artifactregistry.reader

Container-Images abrufen

Compute-Netzwerkadministrator

roles/compute.networkAdmin

VPC-Netzwerkressourcen verwalten

DNS-Administrator

roles/dns.admin

Cloud DNS-Zonen und -Einträge verwalten

Alternativ können Sie eine allgemeine einfache Rolle wie roles/admin oder die alte Rolle roles/owner verwenden.

Auf Ihr Projekt zugreifen

In diesem Codelab wird ein einzelnes Google Cloud-Projekt verwendet. Bei den Konfigurationsschritten werden die gcloud-Befehlszeile und Linux-Shell-Befehle verwendet.

Rufen Sie zuerst die Befehlszeile Ihres Google Cloud-Projekts auf:

Projekt-ID festlegen

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Sitzung authentifizieren

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Shell-Umgebungsvariablen festlegen

# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}
echo ${USER_IDENTITY}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-weather"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
export MCP_NAME="mcp-weather"
export MCP_DISPLAY_NAME="${MCP_NAME}-${PROJ_NO}.${REGION}.run.app"
export MCP_URL="https://${MCP_DISPLAY_NAME}/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_NAME}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

Wenn Sie eine selbstverwaltete Installation des Google Cloud SDK ausführen (d. h. außerhalb von Cloud Shell), aktualisieren Sie die Komponenten auf die neueste Version.

# update gcloud cli
gcloud components update

API-Dienste aktivieren

# enable google apis (agent platform bundle, part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iamconnectors.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com

# enable google apis (all the rest)
gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com

Damit ist die Einrichtung abgeschlossen. Fahren Sie mit dem Abschnitt Netzwerk fort.

4. Netzwerk

Das VPC-Netzwerk wird im benutzerdefinierten Modus bereitgestellt, um reguläre Subnetze zu erstellen, die die PSC-Netzwerkverbindung für Agent Gateway und den ausgehenden Direct VPC-Traffic von Cloud Run unterstützen.

Der PSC-Endpunkt für Google APIs wird mit einer einzelnen /32globalen internen IPv4-Adresse bereitgestellt, um den privaten internen Zugriff auf Cloud Run zu unterstützen. Diese IP-Adresse wird keinem regionalen Subnetz zugewiesen.

Netzwerke erstellen

Globales VPC-Netzwerk erstellen.

# create vpc network
gcloud compute networks create vnet-${SLUG} --subnet-mode=custom

Erstellen Sie Subnetze für die PSC-Netzwerkverbindung des Agent Gateway und den ausgehenden direkten VPC-Traffic von Cloud Run.

# create subnet for agent gateway psc na
gcloud compute networks subnets create subnet-${REGION}-agw \
  --network=vnet-${SLUG} \
  --range=192.168.10.0/28 \
  --region=${REGION} \
  --enable-private-ip-google-access

# create subnet for cloud run dvpc egress
gcloud compute networks subnets create subnet-${REGION}-crun \
  --network=vnet-${SLUG} \
  --range=10.10.10.0/24 \
  --region=${REGION} \
  --enable-private-ip-google-access

Firewallregeln erstellen

Erstellen Sie eine Firewallrichtlinie und ‑regel, um den gesamten ausgehenden Traffic mit aktiviertem Logging zuzulassen. Damit wird der Traffic überwacht, der vom Agent Gateway zum VPC-Netzwerk übertragen wird.

# create fw policy
gcloud compute network-firewall-policies create fw-policy-${SLUG} --global

# create fw policy rule
gcloud compute network-firewall-policies rules create 1001 \
  --description="allow all out and log" \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --action=allow \
  --direction=EGRESS \
  --layer4-configs=all \
  --dest-ip-ranges=0.0.0.0/0 \
  --enable-logging

# associate fw policy to vpc network
gcloud compute network-firewall-policies associations create \
  --name=fw-policy-bind-${SLUG} \
  --firewall-policy=fw-policy-${SLUG} \
  --network=vnet-${SLUG} \
  --global-firewall-policy

PSC-Netzwerkanhang erstellen

Erstellen Sie einen PSC-Netzwerkanhang, der so konfiguriert ist, dass neue Produzentenverbindungen automatisch akzeptiert werden.

# create psc network attachment
gcloud compute network-attachments create psc-na-${REGION}-agw \
  --region=${REGION} \
  --subnets=subnet-${REGION}-agw \
  --connection-preference=ACCEPT_AUTOMATIC

PSC-Netzwerkanhang prüfen

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

# fetch psc na uri
export PSC_NA_URI=$(gcloud compute network-attachments describe psc-na-${REGION}-agw \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

PSC-Endpunkt erstellen

Erstellen Sie eine IP-Adressreservierung für den globalen PSC-Endpunkt. Die hier verwendete Adresse darf nicht aus einem vorhandenen Subnetz stammen oder sich damit überschneiden.

# set env var for psc ep ip address
export PSC_EP_IP="240.0.0.10"
echo ${PSC_EP_IP}

# reserve internal global ipv4 address
gcloud compute addresses create ip-psc2gapis \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=${PSC_EP_IP} \
  --network=vnet-${SLUG}

Erstellen Sie einen PSC-Endpunkt für Google APIs mit dem all-apis-Bundle, das Cloud Run (run.app) enthält.

# create psc endpoint for google apis
gcloud compute forwarding-rules create psc2gapis \
  --global \
  --network=vnet-${SLUG} \
  --address=ip-psc2gapis \
  --target-google-apis-bundle=all-apis

PSC-Endpunkt prüfen

# show psc endpoint details
gcloud compute forwarding-rules describe psc2gapis --global

DNS-Zone und ‑Einträge erstellen

Erstellen Sie eine private, von Cloud DNS verwaltete Zone für die Domain run.app.

# create private dns zone
gcloud dns managed-zones create priv-zone-run \
  --description="private zone for cloud run" \
  --dns-name="run.app." \
  --visibility=private \
  --networks=vnet-${SLUG}

Erstellen Sie einen Platzhalter-DNS-Eintrag vom Typ A für *.run.app., der auf die IP-Adresse des PSC-Endpunkts verweist.

# create dns record
gcloud dns record-sets create *.run.app \
  --zone=priv-zone-run \
  --type=A \
  --ttl=300 \
  --rrdatas=${PSC_EP_IP}

Erstellen Sie eine Cloud DNS-Richtlinie, um das Logging von DNS-Abfragen zu aktivieren.

# create dns policy (logging)
gcloud dns policies create dns-policy-${SLUG} \
  --description="dns logging for vnet-${SLUG}" \
  --networks=vnet-${SLUG} \
  --enable-logging

Cloud NAT erstellen

Erstellen Sie einen Cloud Router und ein Cloud NAT, um den direkten ausgehenden VPC-Traffic von Cloud Run zu unterstützen, damit der MCP-Server über das VPC-Netzwerk auf externe Wetterdaten zugreifen kann.

# create router for nat
gcloud compute routers create cr-nat-${SLUG}-${REGION} \
  --network=vnet-${SLUG} \
  --asn=16550 \
  --region=${REGION}

# create nat gateway
gcloud compute routers nats create nat-${SLUG}-${REGION} \
  --router=cr-nat-${SLUG}-${REGION} \
  --region=${REGION} \
  --auto-allocate-nat-external-ips \
  --nat-all-subnet-ip-ranges

Damit schließen wir den Netzwerkteil ab. Weiter geht es mit dem Abschnitt Gateway.

5. Gateway

Bevor Sie die Zugriffssteuerung erzwingen, stellen Sie Agent Gateway bereit und konfigurieren Sie die Autorisierungserweiterung im DRY_RUN-Modus. So können ausgehende Tool-Aufrufe erfolgreich ausgeführt werden, während die Bewertungsergebnisse zu Prüfzwecken protokolliert werden.

Hier verwendet Agent Gateway eine regionale Registry zur Unterstützung regionaler Agent Runtime-Ressourcen und gibt die Felder networkConfig für den PSC-Netzwerkanhang des VPC-Netzwerks und die DNS-Peering-Konfiguration an.

Gateway erstellen

# create new agent gateway config file (with network settings)
cat > cfg/${AGW_NAME}-networkConfig.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domains:
      - run.app.
    targetProject: ${PROJ_ID}
    targetNetwork: projects/${PROJ_ID}/global/networks/vnet-${SLUG}
EOF

# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}-networkConfig.yaml" \
  --location=${REGION}

Gateway überprüfen

# show agent gateway details
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

Prüfen Sie, ob ein akzeptierter Verbindungsendpunkt vorhanden ist.

connectionEndpoints:
- ipAddress: 192.168.10.2
  projectIdOrNum: '[AGW_PROJECT_NO]'
  status: ACCEPTED
  subnetwork: https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/regions/${REGION}/subnetworks/subnet-${REGION}-agw

Damit ist der Gateway-Teil abgeschlossen. Weiter geht es mit dem Abschnitt Autorisierung.

6. Autorisierung

Die Autorisierungserweiterung für das Agent Gateway für Identity-Aware Proxy (IAP) ist eine Art Diensterweiterung, die verwendet wird, um Autorisierungsentscheidungen für die gesamte Agent Platform zu delegieren.

  1. Delegierungsablauf:Wenn ein Agent versucht, einen externen Endpunkt oder MCP-Server aufzurufen, leitet er die Anfrage an das Agent Gateway weiter. Anstatt den Zugriff lokal zu prüfen, verwendet das Gateway die Autorisierungserweiterung, um einen Callout an den IAP-Bewertungsdienst zu senden. IAP bewertet die Identität des Agents (SPIFFE-basiert) anhand der IAM-Richtlinie der Zielressource in der Agent Registry. IAP gibt eine Entscheidung vom Typ ALLOW oder DENY an das Gateway zurück, das den Traffic entweder weiterleitet oder mit dem HTTP-Statuscode 403 Forbidden blockiert.
  2. Durchsetzungsmodi:Im Modus DRY_RUN werden Anfragen von IAP ausgewertet und Entscheidungen in Cloud Logging protokolliert, ohne den Traffic zu blockieren. Im ENFORCE-Modus wird jede Anfrage von einem nicht autorisierten Agent oder an ein nicht registriertes Ziel sofort blockiert.
  3. Bindungsebene:Die Dienst-Extension ist über eine Autorisierungsrichtlinie, die mit dem Profil REQUEST_AUTHZ konfiguriert ist, mit dem Agent Gateway verbunden.

Autorisierungserweiterung

Eine Autorisierungserweiterung gibt den Sicherheitsanbieterdienst mit Verbindungseinstellungen und anderen Parametern an, die definieren, wie der Dienst funktioniert und in Agent Gateway eingebunden wird.

Autorisierungserweiterung erstellen

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

Autorisierungserweiterung importieren

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml \
  --location=${REGION}

Autorisierungserweiterung überprüfen

# show authz extension details
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

Autorisierungsrichtlinie

Eine Autorisierungsrichtlinie bindet den Sicherheitsanbieter (IAP) an die Ziel-Gateway-Ressource und gibt das Abfangprofil (REQUEST_AUTHZ) an.

Autorisierungsrichtlinie erstellen

# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF

Autorisierungsrichtlinie binden

# import authz policy config file (enable authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

Autorisierungsrichtlinie prüfen

# show authz policy details
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Damit ist die Autorisierung abgeschlossen. Als Nächstes geht es mit dem Abschnitt Codebase weiter.

7. Codebasis

Der für dieses Codelab verwendete Agent, MCP-Server und Endpunktregistrierungscode werden in einem Remote-Google Cloud-GitHub-Repository verwaltet. Bei den folgenden Schritten wird das Repository lokal geklont, die erforderlichen Dateien werden in die aktuelle Arbeitsverzeichnisstruktur kopiert und temporäre Dateien werden gelöscht.

Für die Agent-Laufzeit wird ein Staging-Bucket für den Speicher erstellt, in den der verpackte Agent-Anwendungscode und seine Abhängigkeitsartefakte hochgeladen, erstellt und bereitgestellt werden.

Remote-Artefakte abrufen

# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_vpc

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/agent-weather ./agent-weather
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/mcp-weather ./mcp-weather

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_vpc

Staging-Bucket erstellen

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

Damit ist der Teil zur Codebasis abgeschlossen. Als Nächstes folgt der Abschnitt Registry.

8. Registry

Die Agent Registry ist ein zentrales Inventar aller KI-Agenten, MCP-Server und Endpunkte (APIs) im KI-Ökosystem. Außerdem ist es ein Katalog, in dem andere registrierte Tools und Dienste für die Verwendung durch KI-Anwendungen aufgeführt, gesucht und gefunden werden können. Agent Gateway verwendet das Registrierungsdatenmodell als Governance-Framework, um die Steuerung des ausgehenden Zugriffs zu erzwingen. IAM-Rollenzuweisungen für Hauptkonten, die Agents aufrufen, werden anhand der Richtlinie geprüft, die an die Registry-Ressource gebunden ist.

Um die Umgebung zu booten und den Agenten mit verschiedenen Google APIs und Diensten zu unterstützen, erstellen Sie einen einzelnen Registry-Endpunktdienst, der die für dieses Lab erforderlichen API-Kernschnittstellen bündelt. So lassen sich Governance-Richtlinien für gängige Toolsets, die die meisten KI-Agenten verwenden, einfacher verwalten.

Endpunkte registrieren

# create endpoint service (with multiple entries)
gcloud agent-registry services create core-gapi-services \
  --location=${REGION} \
  --display-name="gapi.core.services" \
  --description="core apis and services" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://telemetry.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://cloudresourcemanager.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://iamcredentials.googleapis.com

Endpunktregistrierung prüfen

# list registry regional endpoints
gcloud agent-registry endpoints list --location=${REGION} \
  --flatten="interfaces[]" \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces.url:label=URL)"

Damit schließen wir den Abschnitt zur Registry ab. Als Nächstes geht es mit dem Abschnitt zum MCP-Server weiter.

9. MCP-Server

IAM-Berechtigungen für die Bereitstellung gewähren

Gewähren Sie dem Standarddienstkonto für Compute Engine Berechtigungen, um die Bereitstellung von Cloud Run-Diensten aus Quellcode zu unterstützen.

# grant cloud run builder role to default compute sa
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

IAM-Berechtigungen überprüfen

# show iam policy on project for default compute sa
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members=serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

MCP-Server bereitstellen

# deploy cloud run service
gcloud -q run deploy ${MCP_NAME} \
  --source=mcp-weather/server \
  --region=${REGION} \
  --no-allow-unauthenticated \
  --min-instances=1 \
  --network=vnet-${SLUG} \
  --subnet=subnet-${REGION}-crun \
  --vpc-egress=all-traffic \
  --startup-probe=httpGet.path=/warmup

IAM-Berechtigungen für den Ingress gewähren

Richtlinie für Nutzerzugriff binden

Gewähren Sie dem Nutzerkonto (sich selbst) Berechtigungen zum Aufrufen des in Cloud Run gehosteten MCP-Servers. Dies ist erforderlich, um das toolspec-Generierungsskript auszuführen.

# grant run invoker role to user account on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --region=${REGION} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.invoker"

IAM-Berechtigungen überprüfen

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Benutzerdefiniertes Dienstkonto für den MCP-Aufruf erstellen

Erstellen Sie ein benutzerdefiniertes Dienstkonto zum Aufrufen des in Cloud Run gehosteten MCP-Servers. Dieses Dienstkonto wird vom Agent verwendet, um ein gültiges von Google signiertes OIDC-ID-Token für den Zugriff auf Cloud Run abzurufen.

# create custom sa for mcp server invocation
gcloud iam service-accounts create sa-${MCP_NAME}-invoker \
  --display-name="custom sa to invoke ${MCP_NAME}"

# set env var for service account identity
export MCP_INVOKER_SA="sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com"
echo ${MCP_INVOKER_SA}

Richtlinie für Dienstkonto binden

# grant run invoker role to custom sa on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --role="roles/run.invoker" \
  --member="serviceAccount:${MCP_INVOKER_SA}" \
  --region=${REGION}

IAM-Berechtigungen überprüfen

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

IAM-Berechtigungen für die Authentifizierung erteilen

Weisen Sie dem Standard-Compute-Dienstkonto Rollen für die Identitätsübernahme von Dienstkonten zu. Dadurch kann der Agent, der unter den Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) ausgeführt wird, im Namen des benutzerdefinierten Dienstkontos für den Aufrufer von Google signierte OIDC-ID-Tokens erstellen, um Aufrufe an Cloud Run zu authentifizieren.

Richtlinie für die Authentifizierung binden

# grant oidc token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

# grant service account token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

IAM-Berechtigungen überprüfen

# show iam policy for the custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

MCP toolspec erstellen

Beim manuellen Registrieren eines MCP-Servers muss eine Tool-Spezifikationsdatei enthalten sein. In einer toolspec.json-Datei werden alle Tools aufgeführt, die vom MCP-Server bereitgestellt werden. Andere Nutzer können sie nach der Registrierung finden.

Das test_mcp.py-Script, das im mcp-weather/-Code enthalten ist, generiert eine toolspec.json-Datei, indem es eine Verbindung zum Ziel-MCP-Server (über SSE oder HTTP) herstellt und list_tools() aufruft, um alle vom Server bereitgestellten verfügbaren Tools abzurufen.

# fetch oidc token for cloud run authentication
export OIDC_TOKEN=$(gcloud auth print-identity-token)

# generate toolspec for registry ingestion
uv --directory mcp-weather run test_mcp.py --toolspec=include --token="${OIDC_TOKEN}"

Ein Blick auf die generierte toolspec-Ausgabe zeigt die MCP-Attribute, die Agent Gateway für die Bewertung und Durchsetzung von Richtlinien für ausgehenden Traffic verwenden kann.

MCP toolspec bestätigen

# show toolspec mcp attributes
jq '.tools[] | {name, isReadOnly, isDestructive, isIdempotent, isOpenWorld}' mcp-weather/toolspec.json

Eingehenden Traffic für Cloud Run aktualisieren

Ändern Sie die Ingress-Einstellung für den Cloud Run-Dienst so, dass nur eingehende Anfragen aus dem VPC-Netzwerk akzeptiert werden. Dadurch wird der direkte öffentliche Zugriff auf den MCP-Endpunkt verhindert und nur internen Ressourcen der Zugriff darauf gestattet. Traffic, der für den PSC-Endpunkt für Google APIs im VPC-Netzwerk bestimmt ist, wird als interner Ingress betrachtet und ist zulässig.

# update cloud run service config
gcloud run services update ${MCP_NAME} \
  --region=${REGION} \
  --ingress=internal

Eingehenden Cloud Run-Traffic prüfen

# show cloud run service details
gcloud run services describe ${MCP_NAME} --region=${REGION} | grep -iE 'ingress|egress'

MCP-Server registrieren

Registrieren Sie den MCP-Server mit der toolspec in der regionalen Agent Registry.

# register mcp server
gcloud agent-registry services create ${MCP_NAME} \
  --location=${REGION} \
  --display-name="${MCP_DISPLAY_NAME}" \
  --description="mcp server for weather info" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=mcp-weather/toolspec.json \
  --interfaces=url=${MCP_URL},protocolBinding=JSONRPC

MCP-Registrierung bestätigen

# list registry regional mcp servers
gcloud agent-registry mcp-servers list --location=${REGION} --format="table(displayName, interfaces.url)"

# show mcp server registry details
gcloud agent-registry services describe ${MCP_NAME} --location=${REGION}

# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

Damit schließen wir den Abschnitt zum MCP-Server ab. Als Nächstes geht es mit dem Abschnitt zum ADK-Agenten weiter.

10. ADK-Agent

Der agent-weather-ADK-Agent, der in der Agent Runtime bereitgestellt wird, ist im Bereitstellungsskript mit den folgenden Einstellungen für die Integration in die Agent Platform konfiguriert:

  • "identity_type": types.IdentityType.AGENT_IDENTITY, um eine eindeutige SPIFFE-basierte Prinzipalidentität für den Agenten bereitzustellen
  • "agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } }, um den gesamten ausgehenden, vom Agenten initiierten Traffic zur Richtlinienbewertung und ‑durchsetzung an das Agent Gateway weiterzuleiten

Der Agent ist auch für die Verwendung des MCP-Servers konfiguriert, indem die URL und das Dienstkonto zum Abrufen des OIDC-ID-Tokens übergeben werden.

KI-Agent bereitstellen

# deploy agent runtime workload
uv --directory agent-weather run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for weather info" \
  --mcp-server-url="${MCP_URL}" \
  --mcp-invoker-sa="${MCP_INVOKER_SA}" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

Deployment prüfen

Deployment-Vitals abrufen

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export RE_AGENT_REGISTRY_ID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${RE_AGENT_REGISTRY_ID}

Registry-Eintrag überprüfen

# show agent resource registry details
gcloud agent-registry agents describe ${RE_AGENT_REGISTRY_ID} --location=${REGION}

Gateway-Konfiguration prüfen

# show agent config details (gateway config)
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

IAM-Berechtigungen für die Authentifizierung erteilen

Wenn ein Agent für die Verwendung von Agent Identity konfiguriert ist, erhält er ein Token (JWT-SVID-Format) vom föderierten Security Token Service (STS), das von sts.googleapis.com (dem SPIFFE-Identitätsanbieter) signiert ist.

Die integrierte Cloud Run IAM-Aufruferprüfung vertraut jedoch nur Standard-OIDC-ID-Tokens, die vom Haupt-Google-OIDC-Aussteller (accounts.google.com) signiert wurden, und kann diese nur prüfen.

Ein benutzerdefiniertes Dienstkonto wird also verwendet, um das föderierte STS-Token (JWT-SVID), das von der Agent-Identität abgerufen wurde, zur Laufzeit gegen ein Standard-Google-Token (OIDC) auszutauschen, das mithilfe der Identitätsübernahme des Dienstkontos abgerufen wird.

Erstellen Sie die für das benutzerdefinierte Dienstkonto erforderlichen Rollenbindungen.

Richtlinie für die Authentifizierung (Identitätsdiebstahl) binden

# grant service account token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

# grant service account openid token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

IAM-Berechtigungen überprüfen

# show iam policy for custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

IAM-Berechtigungen für die Laufzeit gewähren

Durch das Erteilen von IAM-Berechtigungen für die Laufzeit kann der Agent mit seiner SPIFFE-basierten Haupt-Agentenidentität auf AI Platform-Dienste und andere wichtige Google APIs und ‑Dienste zugreifen. Diese Richtlinien werden mit IAM auf Ressourcenebene erzwungen.

Erstellen Sie die Rollenbindungen, die für die Agent-Identität erforderlich sind.

Richtlinien für den Agent-Zugriff binden

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

IAM-Berechtigungen überprüfen

# show iam policy on project for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Damit schließen wir den Abschnitt zu ADK-Agenten ab. Als Nächstes geht es mit dem Abschnitt Richtlinien weiter.

11. Richtlinien

Mit Autorisierungsrichtlinien für die Agentenverwaltung kann Traffic von einem KI-Agenten über das Agenten-Gateway und zum endgültigen Ressourcenziel (z. B. einem privaten MCP-Serverendpunkt für den Datenabruf) weitergeleitet werden. Sobald Traffic das Ziel erreicht, wird der Datenzugriff durch reguläre Berechtigungen auf Dienst- oder Anwendungsebene autorisiert.

Durch das Zuweisen von IAM-Rollen für den Agent Gateway-Ausgang werden Zugriffsrichtlinien aktiviert, die der Identität des Agent-Hauptkontos den Zugriff auf registrierte Zielressourcen über das Agent Gateway ermöglichen. Richtlinien werden auf der Ebene des Agent Gateway erzwungen und mit IAM-Richtlinien für Identity-Aware Proxy (IAP) validiert.

IAM-Rollen für Agent Gateway-Ausgang gewähren

Agent Gateway prüft eingehende Anfragen, um zu validieren, ob die Identität des aufrufenden Agents die Berechtigung iap.webServiceVersions.egressViaIAP (gewährt durch die Rolle roles/iap.egressor) für die Zielressource hat.

Wenn Sie der Agent-Identität oder der Hauptkontogruppe „Agent Runtime“ die Berechtigung roles/iap.egressor für die ausgewählte Zielressource erteilen, ist dieser ausgehende Traffic zulässig. In diesem Codelab wird die Rolle auf das Hauptkonto agent angewendet, wodurch die Berechtigung für die spezifische Agent Runtime-Agentenidentität gewährt wird.

Die IAM-Richtlinien sind an die Zielressourcen gebunden, die im Datenmodell der Agent Registry definiert sind. Die iap_web/agentRegistry-Ressource stellt eine Ebene für die gesamte Registrierung in der IAM-Hierarchie dar. Dabei dient agentRegistry als übergeordnete Ressource für die einzelnen untergeordneten Ressourcen für agents, mcpServers und endpoints. In diesem Codelab ist die IAM-Richtlinie an die Ebenen mcpServer und endpoint gebunden, wodurch die Berechtigung auf die jeweiligen untergeordneten Ressourcen angewendet wird.

Agent für MCP-Serverrichtlinie konfigurieren

Richtlinie für die Kommunikation zwischen Agent und MCP-Server erstellen

# fetch active etag on policy for mcp server
export IAP_ETAG=$(gcloud beta iap web get-iam-policy \
  --resource-type=agent-registry --region=${REGION} \
  --mcp-server=${MCP_REGISTRY_ID} --format="value(etag)")
echo ${IAP_ETAG}

HINWEIS : etag: sollte den Standardwert ACAB zurückgeben, da noch keine Richtlinien definiert wurden.

# create policy config file
cat > cfg/iap-policy-agent-to-mcp.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ],
  "etag": "${IAP_ETAG}"
}
EOF

Richtlinie für Agenten an MCP-Server binden

# import policy file
gcloud beta iap web set-iam-policy cfg/iap-policy-agent-to-mcp.json \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

IAM-Berechtigungen überprüfen

# show iap iam policy on mcp server for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID}

Damit sind wir mit den Richtlinien fertig. Als Nächstes geht es mit dem Abschnitt Audit weiter.

12. Audit

Die Autorisierungserweiterung für Agent Gateway wird im Modus DRY_RUN ausgeführt. Ausgehende Anfragen werden beobachtet und protokolliert, aber nicht blockiert. Wenn Sie die Protokolle analysieren, bevor Sie in den ENFORCED-Modus wechseln, können Sie feststellen, welche Richtlinien konfiguriert werden müssen, um den gewünschten Traffic zuzulassen.

Agent-Anfragen testen

Öffnen Sie ein Browserfenster für die Google Cloud Console-UI und rufen Sie Folgendes auf:

  • Agent Platform → „Agents“ → „Deployments“ → agent-weather
  • Wählen Sie den Tab Playground aus.

Oder geben Sie diesen Terminalbefehl ein und klicken Sie auf den Link, um zum Playground des Agents zu gelangen:

# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"

Senden Sie einige Testanfragen.

  • What is the weather like in London?
  • How warm is it in New York?

Prüfen Sie, ob die Abfragen gültige Antworten zurückgeben.

Audit-Logs analysieren

Logs ansehen und die Richtlinienbewertungen im Probebetrieb prüfen

# show gateway logs for endpoints and authz status (duplicates removed)
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=50 \
  --freshness=24h \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    httpRequest.requestUrl.sub('(https?://[^/:]+).*', '\1'):label=ENDPOINT \
  )" | awk 'NR==1 {print; next} ! seen[$2,$3,$4]++'

TIMESTAMP            STATUS  AUTHZ    ENDPOINT
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://cloudresourcemanager.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://${REGION}-aiplatform.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://iamcredentials.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://telemetry.googleapis.com
YYYY-MM-DDTHH:MM:SS  202     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app

Richtlinie „Agent für Endpunkte“ konfigurieren

Da die wichtigsten Google APIs für agent-weather in der Registry unter einem gemeinsamen Endpunktdienst (gapi.core.services) registriert wurden, ist nur eine Richtlinie erforderlich, um Agentenberechtigungen für den Endpunktzugriff zu gewähren.

Richtlinie für Agent-zu-Endpunkt erstellen

# set var for endpoint display name
export ENDPOINT_DISPLAY_NAME="gapi.core.services"
echo ${ENDPOINT_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-agent-to-ep.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

Richtlinie für Agent an Endpunkt binden

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-agent-to-ep.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

IAM-Berechtigungen überprüfen

# show iap iam policy on endpoint for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID}

Damit ist der Audit-Teil abgeschlossen. Weiter geht es mit dem Abschnitt Erzwingen.

13. Erzwingen

Der Agent konnte im DRY_RUN-Modus erfolgreiche Anfragen über das Gateway stellen. Die Zugriffslogs und Endpunkte wurden analysiert, um eine Reihe von Governance-Richtlinien zu erstellen, die den erforderlichen ausgehenden Traffic vom Agent ermöglichen. Stellen Sie die IAP-Autorisierungserweiterung des Agent Gateway jetzt auf den ENFORCE-Modus um, indem Sie die Autorisierungsrichtlinie aktualisieren.

Autorisierungserweiterung aktualisieren

Autorisierungserweiterung erstellen

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

Autorisierungserweiterung importieren

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-enforced \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml \
  --location=${REGION}

Autorisierungserweiterung überprüfen

# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}

Autorisierungsrichtlinie aktualisieren

Autorisierungsrichtlinie erstellen

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

Autorisierungsrichtlinie binden

# import authz policy config file (enable new authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

Autorisierungsrichtlinie prüfen

# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Durchsetzung überprüfen

Kehren Sie in der Console-UI zum Playground des Agents zurück.

  • Klicken Sie auf die Schaltfläche + Neue Sitzung, um eine neue Chatsitzung zu erstellen.

Senden Sie eine zusätzliche Testanfrage…

  • What is the current temperature in Los Angeles?

Die Agent-Anfragen an das Gemini-Basismodell (${REGION}-aiplatform.googleapis.com/...) und den MCP-Serverendpunkt (mcp-weather-${PROJ_NO}.${REGION}.run.app/mcp) werden mit HTTP-Statuscodes 200 OK übergeben.

Gateway-Logs analysieren

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

Prüfen Sie, ob Anfragen blockiert werden. Suchen Sie in den Gateway-Prüfprotokollen nach abgelehnten Egress-Versuchen mit HTTP-Statuscodes 403 Forbidden.

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

Sehen Sie sich die MCP-Logs des Agent Gateway an und achten Sie darauf, wie die MCP-Anwendungsnutzlast (JSON-RPC) geprüft wird, um die Protokollmetadaten zu ermitteln, einschließlich der ausgeführten Tools.

# show gateway logs for mcp requests with method and tool name
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND jsonPayload.agentGatewayInfo.mcpInfo.method:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL_NAME,
    httpRequest.requestUrl:label=URL
  )"

Firewall-Logs analysieren

Logs für die Priorität 1001 der Netzwerk-Firewallrichtlinien-Regel ansehen.

# show firewall logs for rule 1001
gcloud logging read \
  "jsonPayload.rule_details.priority=1001" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.disposition:label=ACTION,
    jsonPayload.connection.src_ip:label=SRC_IP,
    jsonPayload.connection.dest_ip:label=DEST_IP,
    jsonPayload.connection.dest_port:label=DEST_PORT,
    jsonPayload.vpc.subnetwork_name:label=SUBNET
  )"

Hier sehen Sie die verschiedenen Traffic-Pfade auf Netzwerkebene:

  • Agent Gateway kommuniziert mit internen VPC-Netzwerkressourcen über subnet-${REGION}-agw
  • Der in Cloud Run gehostete MCP-Server ruft externe Wetter-APIs mit subnet-${REGION}-crun auf.
TIMESTAMP            ACTION   SRC_IP        DEST_IP        DEST_PORT  SUBNET
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw

DNS-Logs analysieren

DNS-Abfragelogs für Anfragen ansehen, die von der privaten DNS-Zone (priv-zone-run) aufgelöst wurden.

gcloud logging read \
  "resource.type=\"dns_query\" AND resource.labels.target_name=\"priv-zone-run\"" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.queryName:label=QUERY_NAME,
    jsonPayload.queryType:label=TYPE,
    jsonPayload.rdata:label=RESPONSE_RDATA,
    jsonPayload.sourceNetwork:label=NETWORK,
    resource.labels.source_type:label=SRC_TYPE
  )"

Hinweis: DNS-Lookups für den Cloud Run-Dienst (mcp-weather...run.app) stammen aus dem VPC-Netzwerk über DNS-Peering und werden erfolgreich in den internen PSC-Endpunkt für Google APIs (240.0.0.10) aufgelöst.

TIMESTAMP            QUERY_NAME                                     TYPE  RESPONSE_RDATA                                                     NETWORK   SRC_TYPE
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone

Damit schließen wir den Teil zur Erzwingung ab. Als Nächstes folgt der Abschnitt Bereinigung.

14. Bereinigen 

# delete agent runtime
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# delete agent resources
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

for ROLE in \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

# delete mcp (cloud run) resources
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

gcloud -q run services delete ${MCP_NAME} --region=${REGION}

gcloud -q artifacts repositories delete cloud-run-source-deploy --location=${REGION}

gcloud -q iam service-accounts delete sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com

gcloud -q agent-registry services delete ${MCP_NAME} --location=${REGION}

# next

# delete gateway resources (policy binding must be deleted synchronously first)
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION} --async

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-enforced --location=${REGION} --async

gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION} --async

# next

# remove policies
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

# next

# delete dns resources
gcloud -q dns record-sets delete *.run.app --type=A --zone=priv-zone-run

gcloud -q dns managed-zones delete priv-zone-run

gcloud -q dns policies update dns-policy-${SLUG} --networks=""

gcloud -q dns policies delete dns-policy-${SLUG}

# next

# delete router (includes nat) and psc resources
gcloud -q compute routers delete cr-nat-${SLUG}-${REGION} --region=${REGION}

gcloud -q compute forwarding-rules delete psc2gapis --global

gcloud -q compute addresses delete ip-psc2gapis --global

# next

# delete firewall resources
gcloud -q compute network-firewall-policies associations delete --name=fw-policy-bind-${SLUG} --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies rules delete 1001 --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies delete fw-policy-${SLUG} --global

# next

# delete network resources
gcloud -q compute networks subnets delete subnet-${REGION}-agw --region=${REGION}

gcloud -q compute networks subnets delete subnet-${REGION}-crun --region=${REGION}

gcloud -q compute network-attachments delete psc-na-${REGION}-agw --region=${REGION}

gcloud -q compute networks delete vnet-${SLUG}

# next

# clean up local working directories and generated configs
rm -rf cfg agent-weather mcp-weather

# end

Damit ist die Bereinigung abgeschlossen. Als Nächstes folgt das Fazit.

15. Fazit

Glückwunsch! Sie haben das Agenten-Gateway erfolgreich bereitgestellt und den ausgehenden KI-Agenten-Traffic gesteuert.

cosmopup

Cosmopup findet Codelabs einfach toll!

Wie geht es weiter?

Wenn Sie Anmerkungen, Fragen oder Korrekturen haben, können Sie uns diese gern über dieses Feedbackformular mitteilen.

Vielen Dank!