Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Ausgehender Agenten-Gateway-Traffic von Agent Runtime zu Google MCP

1. Einführung

In diesem Codelab wird die Agent Gateway-Ausgangsverwaltung für KI-Agenten untersucht, die auf Remote-MCP-Server (Model Context Protocol) von Google Cloud zugreifen.

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 erstellen. 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 vertrauliche Daten exfiltriert oder destruktive Befehle ausgeführt werden.

Um autonome Agents in großem Umfang 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 Modus „Ausgehend“ (agent-to-anywhere)
IAP-Autorisierungserweiterung (Identity-Aware Proxy)
ADK-Agent für Agent Runtime mit Agentenidentität
Agent Registry mit Google API- und MCP-Endpunkten
Autorisierungsrichtlinien mit IAM-Zugriffssteuerung
BigQuery-Dataset, das mit MCP abgefragt werden soll

Abbildung 1. Codelab-Architektur

Lerninhalte

KI-Agenten-Gateway in einer strukturierten Konfigurationssequenz bereitstellen
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

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

Wenn Sie Agent Gateway mit Governance-Kontrollen bereitstellen, ist es wichtig, eine strukturierte Konfigurationsreihenfolge einzuhalten, damit Agenten beim Initialisieren Zugriff auf die erforderlichen Ressourcen haben und Netzwerkanfragen erfolgreich sind.

In diesem Codelab wird die folgende Bereitstellungsreihenfolge verwendet:

Im Probebetrieb starten:Wenn eine Agent-Laufzeit so konfiguriert ist, dass ausgehende Anrufe an das Gateway weitergeleitet werden, bevor das Gateway vollständig bereitgestellt ist, kann die Arbeitslast nicht initialisiert werden. Wenn Sie die Gateway-Autorisierungserweiterung zuerst im DRY_RUN-Modus konfigurieren, wird sichergestellt, dass keine Anfragen verworfen werden, wenn Agent-Traffic am Gateway eingeht.
Alle Dienste registrieren:Alle Agenten, MCP-Server und Endpunkte, die Agent Gateway verwenden, müssen in der Agent Registry registriert sein. Anfragen von nicht registrierten Quellen oder Zielen werden abgelehnt. Auf Agent Runtime und Google MCP-Servern bereitgestellte Agents werden automatisch registriert. Jeder Google API-Endpunkt oder benutzerdefinierte MCP-Server muss manuell registriert werden.
Autorisierungsrichtlinien erzwingen:Autorisierungsrichtlinien werden verwendet, um registrierten Agents Zugriff auf Agent-Komponenten zu gewähren. Dazu wird dem Hauptkonto der Agent-Identität die Rolle roles/iap.egressor zugewiesen und es wird an die Zielregistrierungsressource gebunden. Bewerten Sie das Agent-Verhalten im Probelaufmodus und definieren Sie dann Richtlinien, um den ausgewählten ausgehenden Traffic über das Gateway zuzulassen. Sobald Richtlinien vorhanden sind, wechseln Sie in den ENFORCED-Modus, damit das Gateway die Governance-Richtlinien aktiv erzwingen kann.

Abbildung 2. Bereitstellungssequenz

Topologie für das Routing von ausgehendem Traffic

Gateways verwalten in der Regel eingehenden Traffic (Ingress) zu Backend-Diensten. Das Agent Gateway, das im Egress-Modus (agent-to-anywhere) arbeitet, fungiert als zentraler, Zero-Trust-Ausgangsproxy für Agenten-Workloads.

Wenn eine KI-App oder eine agentische Arbeitslast versucht, ein externes Tool oder eine externe API aufzurufen, wird die ausgehende Anfrage von Agent Gateway abgefangen und anhand von Governance-Richtlinien ausgewertet, bevor sie an ihr Ziel weitergeleitet wird:

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.

Abbildung 3. Topologie für ausgehendes Routing von Agent Gateway

In diesem Codelab geht es um ausgehenden Traffic von einem benutzerdefinierten Agenten in der Agent Runtime, der auf den Remote-Google-MCP-Serverendpunkt für BigQuery ausgerichtet ist.

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
BigQuery	`roles/bigquery.admin`	Schemas und Test-Datasets einrichten
Cloud Storage	`roles/storage.admin`	Bereitstellungs-Staging-Buckets verwalten
Logs und Prüfung	`roles/logging.viewer`	Traces und Audit-Logs prüfen

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:

Cloud Shell unter shell.cloud.google.com oder
Ein lokales Terminal mit installiertem gcloud CLI

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)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}

# 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-dj"
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}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}

# create local dir for config files
mkdir -p cfg

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 \
  discoveryengine.googleapis.com

Damit ist die Einrichtung abgeschlossen. Weiter geht es mit dem Abschnitt Gateway.

4. 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.

Gateway erstellen

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

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

# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

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

5. 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.

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.
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.
Bindungsebene:Die Dienst-Extension ist über eine Autorisierungsrichtlinie, die mit dem Profil REQUEST_AUTHZ konfiguriert ist, mit dem Agent Gateway verbunden.

Autorisierungserweiterung

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

# 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}

# show authz extension details (verify extension state)
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

# 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}

# show authz policy details (verify dry run mode)
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.

6. Codebasis

Der für dieses Codelab verwendete Agent-Code, das BigQuery-Dataset und das Registrierungsskript werden in einem Google Cloud-GitHub-Repository verwaltet. Bei den folgenden Schritten wird das Repository lokal geklont, die erforderlichen Dateien werden in die aktuelle Arbeitsverzeichnisstruktur kopiert und die nicht benötigten temporären 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_gmcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp

BigQuery-Dataset erstellen

# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
  --use_legacy_sql=false < agent-dj/setup.sql

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.

7. 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. Beim Agent Gateway-Ausgang (Modus agent-to-anywhere) wird das Datenmodell der Registry als Governance-Framework verwendet, um die Zugriffssteuerung für ausgehenden Traffic 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 starten und Agents zu unterstützen, die verschiedene Google-APIs und -Dienste verwenden, wird ein Skript verwendet, um schnell eine gemeinsame Gruppe von API-Endpunkten mit Hostnamen und Standorten aus endpoints/googleapis.txt zu registrieren.

Endpunkte registrieren

# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
  --multi-region=${MREGION} \
  --region=${REGION} \
  --mtls-endpoints=include

Endpunkte prüfen

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

Damit ist der Registrierungsabschnitt abgeschlossen. Weiter geht es mit dem Abschnitt Laufzeit.

8. Laufzeit

Der agent-dj-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

KI-Agent bereitstellen

# deploy agent runtime workload
uv --directory agent-dj 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 dj contact info" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

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 AGENT_UID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${AGENT_UID}

Registry-Eintrag überprüfen

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

agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
  agentregistry.googleapis.com/system/Framework:
    framework: google-adk
  agentregistry.googleapis.com/system/RuntimeIdentity:
    principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
  agentregistry.googleapis.com/system/RuntimeReference:
    uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
  type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'

Gateway-Konfiguration prüfen

# verify agent gateway routing specification
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}'

Agent-IAM-Rollen für Ressourcen gewähren

IAM-Rollenzuweisungen für Ressourcen ermöglichen dem Agent-Hauptkonto den Zugriff auf BigQuery, MCP-Tools (für Google-APIs) und andere erforderliche KI-Plattformdienste. Diese Richtlinien werden mit IAM auf Ressourcenebene erzwungen.

# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.user"

# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.dataViewer"

# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/mcp.toolUser"

# 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-Rollen des Agents für Ressourcen prüfen

# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="value(bindings.role)"

Damit schließen wir den Teil zur Laufzeit ab. Als Nächstes geht es mit dem Abschnitt Richtlinien weiter.

9. Richtlinien

Autorisierungsrichtlinien für die Agent-Governance erlauben Traffic von einem KI-Agenten über das Agent Gateway zum Ziel (z. B. Google Cloud MCP-Serverendpunkt für BigQuery). Sobald der Traffic das Ziel erreicht, wird der Datenzugriff durch reguläre IAM-Berechtigungen autorisiert (die im vorherigen Abschnitt aktiviert wurden).

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

IAM-Rollen für Agenten für den 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 set angewendet, wodurch allen Agentenidentitäten der Agent Runtime im Projekt die Berechtigung gewährt wird.

Die IAM-Richtlinien sind an die Zielressourcen gebunden, wie im Datenmodell der Agent Registry definiert. 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 registry-Ebene gebunden, wodurch die Berechtigung auf alle untergeordneten Ressourcen angewendet wird.

IAM-Richtlinie für regionale IAP-Registry konfigurieren

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

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

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

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

# verify iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

Damit sind wir mit den Richtlinien durch. Als Nächstes geht es um den Audit-Abschnitt.

10. Audit

Die Autorisierungserweiterung für Agent Gateway wird im Modus DRY_RUN ausgeführt. Ausgehende Anfragen werden beobachtet und protokolliert, aber nicht blockiert.

Agent-Anfragen testen

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

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

Alternativ können Sie diesen Terminalbefehl ausgeben und auf den Link klicken, um zum Agent-Playground 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.

How many DJs do we have on file?
What is the phone number of DJ Cosmopup?

Prüfen Sie, ob die Anfragen gültige Antworten zurückgeben (z. B. Es sind 12 DJs in der Datei).

Audit-Logs analysieren

Logs ansehen und die Richtlinienbewertungen im Probebetrieb prüfen

# query gateway logs for dry run
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
  )"

TIMESTAMP            METHOD  STATUS  IAP_AUTHZ  MCP_METHOD  URL
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp

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

11. Erzwingen

Der Agent konnte im DRY_RUN-Modus erfolgreiche Anfragen über das Gateway stellen. Stellen Sie die IAP-Autorisierungserweiterung des Agent Gateway auf den ENFORCE-Modus um, indem Sie die Autorisierungsrichtlinie aktualisieren.

Autorisierungserweiterung aktualisieren

# 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

# 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}

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

Autorisierungsrichtlinie aktualisieren

# 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

# 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}

# 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.

Senden Sie eine zusätzliche Testanfrage…

What DJ Fishfry's credit card number?

Die Agent-Anfragen an das Gemini Foundation Model (${REGION}-aiplatform.googleapis.com/...) und den MCP-Serverendpunkt (bigquery.googleapis.com/mcp) werden mit HTTP-Statuscodes 200 OK übergeben.

# 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
  )"

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

12. Bereinigen

# delete agent
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

# remove agent resource iam bindings
for ROLE in \
  "roles/bigquery.user" \
  "roles/bigquery.dataViewer" \
  "roles/mcp.toolUser" \
  "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 storage bucket
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds

# next

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

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

# next

# delete gateway resources
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}

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

# next

# clean up local working directories and generated configs
rm -rf cfg agent-dj endpoints

# end

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

13. Fazit

Glückwunsch! Sie haben die ausgehende Kommunikation für einen KI-Agenten, der über Agent Gateway auf Tools zugreift, erfolgreich bereitgestellt und verwaltet.

cosmopup

Cosmopup findet Codelabs super!

Wie geht es weiter?

In der Dokumentation zur Gemini Enterprise Agent Platform finden Sie erweiterte Funktionen und Tutorials.
Model Armor-Schutzmaßnahmen im Agent Gateway konfigurieren, um die KI-Sicherheit zu erhöhen
Semantische Governance-Richtlinien zur Durchsetzung von Geschäftsregeln und Compliance für Anfragen in natürlicher Sprache

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

Vielen Dank!