KI-Agenten mit Agent Gateway verwalten

Mit Agent Gateway können Sie ausgehenden Traffic von KI-Agenten steuern, die Sie in Cloud Run erstellen und hosten. Wenn Sie ausgehenden Traffic von Ihrem Cloud Run-Dienst über ein selbstverwaltetes Agent Gateway weiterleiten, das auf Secure Web Proxy ausgeführt wird, können Sie zentrale Zugriffsrichtlinien erzwingen, Nutzlasten auf Inhaltssicherheit prüfen und Beobachtbarkeitstelemetrie für Ihre agentischen Arbeitslasten erfassen.

In diesem Dokument wird beschrieben, wie Sie eine zentralisierte Architektur für Agent Gateway in Cloud Run konfigurieren. Es werden folgende Themen behandelt:

Architektur

In einer zentralisierten, selbstverwalteten Bereitstellung fungiert Secure Web Proxy als Richtlinienerzwingungspunkt und wird in Ihrem VPC-Netzwerk (Virtual Private Cloud) ausgeführt. Der Sidecar-Container für Ambient Networking fängt ausgehenden Traffic von Ihrem Cloud Run-Agenten ab und leitet ihn über Direct VPC-Ausgang an Ihre Secure Web Proxy-Instanz weiter. Secure Web Proxy erzwingt Zugriffs- und Inhaltsregeln von Richtlinienentscheidungspunkten wie Identity-Aware Proxy (IAP) und Model Armor.

Architekturdiagramm, das einen Cloud Run-Dienst mit einem Agentencontainer und einem Ambient-Sidecar-Proxy-Container zeigt, der Traffic über ausgehenden Direct VPC-Traffic an ein selbstverwaltetes Agent Gateway weiterleitet, das von Secure Web Proxy in einem VPC-Netzwerk unterstützt wird.
Abbildung 1. Selbstverwaltete Agent Gateway-Architektur für einen Cloud Run-Agenten.

Zum Weiterleiten und Verwalten des Traffics in dieser Architektur konfigurieren Sie die folgenden Komponenten:

  • Ausgehender Direct VPC-Traffic und Ambient Networking: Ihr Cloud Run-Dienst stellt mit --vpc-egress=all und --ambient-networking eine Verbindung zu Ihrem VPC-Netzwerk her. Dabei wird standardmäßig der regionale Bereich verwendet und der gesamte ausgehende Traffic wird in Ihr VPC-Netzwerk geleitet.
  • Selbstverwaltetes Agent Gateway: Eine logische Agent Gateway-Ressource im selbstverwalteten Modus verweist auf die Secure Web Proxy-Instanz in Ihrem VPC-Netzwerk.
  • Routingrichtlinie für ausgehenden Traffic: Eine EgressRouting-Richtlinie der Network Services API leitet ausgehenden Traffic von Ihrem Cloud Run-Dienst an Ihre Secure Web Proxy-Instanz weiter.

Hinweis

  1. Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie einfach ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

  12. Aktivieren Sie die Cloud Run Admin API, die Network Services API, die Netzwerksicherheit API, die Service Extensions API, die Model Armor API, die Certificate Authority Service API, die Certificate Manager API, die Cloud Resource Manager API, die App Hub API, die Identity and Access Management API, die Identity-Aware Proxy API, die Compute Engine API, die Traffic Director API, die Cloud DNS API, die Network Connectivity API und die Agent Registry API, falls diese noch nicht aktiviert sind.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

    APIs aktivieren

  13. Erstellen Sie ein VPC-Netzwerk und ein Subnetz, wobei der private Google-Zugriff für das Subnetz aktiviert ist.
  14. Richten Sie Agent Registry in Ihrem Projekt oder Ihrer Organisation ein.
  15. Installieren und initialisieren Sie die Google Cloud CLI.
  16. Aktualisieren Sie die gcloud CLI-Komponenten: 
    gcloud components update

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren des Agent-Gateways für Cloud Run benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Wenn Sie eine projektübergreifende Bereitstellung mit einer freigegebene VPC konfigurieren, bitten Sie Ihren Administrator, Ihnen roles/compute.xpnAdmin auf Organisations- oder Ordnerebene zu gewähren.

Selbstverwaltetes Agent-Gateway erstellen

Bevor Sie die Agent-Gateway-Ressource erstellen, müssen Sie eine Secure Web Proxy-Instanz in Ihrem VPC-Netzwerk bereitstellen und konfigurieren, wie unter Secure Web Proxy als Agent-Gateway bereitstellen beschrieben:

  1. Richten Sie die TLS-Prüfung ein und erstellen Sie eine Gateway-Sicherheitsrichtlinie, die Ihre TlsInspectionPolicy anhängt. Sie benötigen keine Sicherheitsrichtlinienregeln oder URL-Listen für Secure Web Proxy.
  2. Erstellen Sie eine ServerTlsPolicy-Ressource mit allowOpen: false und mtlsPolicy.clientValidationMode: ALLOW_INVALID_OR_MISSING_CLIENT_CERT. Legen Sie clientValidationTrustConfig nicht fest.
  3. Stellen Sie eine Secure Web Proxy-Instanz im expliziten Proxy-Routing-Modus bereit, wobei addresses, ports, certificateUrls, gatewaySecurityPolicy und serverTlsPolicy beim Erstellen des Gateways konfiguriert werden, damit Cloud Run die Workload Identity Ihres Agents an Secure Web Proxy und IAP über mTLS übergibt.

Sobald Ihre Secure Web Proxy-Instanz bereit ist, erstellen Sie eine selbstverwaltete Agent Gateway-Ressource, die auf Ihre Secure Web Proxy-Instanz verweist:

  1. Erstellen Sie eine YAML-Konfigurationsdatei mit dem Namen my-agent-gateway.yaml:

    name: AGENT_GATEWAY_NAME
registries:
  - "//agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGION"
selfManaged:
  resourceUris:
    - "projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME"

    Ersetzen Sie Folgendes:

    • AGENT_GATEWAY_NAME: Der Name, den Sie Ihrer Agent Gateway-Ressource zuweisen möchten.
    • PROJECT_ID: die Projekt-ID, die Ihre Secure Web Proxy-Instanz hostet.
    • REGION: die Region Ihrer Secure Web Proxy-Instanz, z. B. us-central1.
    • SWP_NAME: der Name Ihrer Secure Web Proxy-Instanz.

  2. Importieren Sie die Konfiguration des KI-Agenten-Gateways:

    gcloud beta network-services agent-gateways import AGENT_GATEWAY_NAME \
   --source="my-agent-gateway.yaml" \
   --location=REGION \
   --project=PROJECT_ID

  3. Prüfen Sie Ihre Agent-Gateway-Ressource:

    gcloud beta network-services agent-gateways describe AGENT_GATEWAY_NAME \
   --location=REGION \
   --project=PROJECT_ID

    Prüfen Sie, ob in der Ausgabe Ihre selfManaged-Konfiguration und der Ressourcen-URI Ihrer Secure Web Proxy-Instanz angezeigt werden, bevor Sie mit dem nächsten Abschnitt fortfahren.

Cloud Run Ambient Networking für den Zugriff auf die Traffic Director API konfigurieren

Wenn Sie einen Cloud Run-Dienst mit Direct VPC-Traffic und --vpc-egress=all konfigurieren, werden alle ausgehenden Verbindungen von der Containerinstanz über Ihr VPC-Netzwerk weitergeleitet. Dazu gehört die Envoy-Sidecar-Verbindung zu trafficdirector.REGION.rep.googleapis.com.

Damit der Sidecar die Traffic Director API auflösen und erreichen kann, konfigurieren Sie eine private Cloud DNS-Zone in Ihrem VPC-Netzwerk. Dies hängt davon ab, ob Ihre Umgebung VPC Service Controls verwendet:

Ohne VPC Service Controls

Wenn Ihr Projekt VPC Service Controls nicht verwendet, erstellen Sie eine private Cloud DNS-Zone, die Anfragen für trafficdirector.REGION.rep.googleapis.com an die IP-Adresse Ihres Secure Web Proxy-Gateways weiterleitet, damit Secure Web Proxy den Traffic durchlässt:

  1. Rufen Sie die interne IP-Adresse Ihres Secure Web Proxy-Gateways ab:

    SWP_IP=$(gcloud network-services gateways describe SWP_NAME \
 --project="PROJECT_ID" \
 --location="REGION" \
 --format="value(addresses[0])")

    Ersetzen Sie Folgendes:

    • SWP_NAME: der Name Ihrer Secure Web Proxy-Instanz.
    • PROJECT_ID: Projekt-ID in Google Cloud .
    • REGION: die Region Ihrer Bereitstellung.

  2. Erstellen Sie eine private, von Cloud DNS verwaltete Zone für die Traffic Director API:

    gcloud dns managed-zones create td-swp-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone routing control plane traffic to SWP" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

    Ersetzen Sie VPC_NETWORK_NAME durch den Namen Ihres VPC-Netzwerks.

  3. Fügen Sie einen A-Eintrag hinzu, der die regionale Domain der Traffic Director API auf die IP-Adresse Ihres Secure Web Proxy verweist:

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-swp-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${SWP_IP}"

  4. Prüfen Sie, ob der DNS-Eintragssatz in der privaten Zone aktiv ist:

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-swp-zone"

    Prüfen Sie, ob der A-Eintrag für trafficdirector.REGION.rep.googleapis.com. in die IP-Adresse Ihres Secure Web Proxy aufgelöst wird.

Mit VPC Service Controls

Stellen Sie für VPC Service Controls-Umgebungen einen regionalen Private Service Connect-Endpunkt bereit, der auf die regionale Traffic Director API in Ihrem VPC-Subnetz verweist, und ordnen Sie die Domain mithilfe einer privaten Cloud DNS-Zone zu:

  1. Erstellen Sie einen regionalen Private Service Connect-Endpunkt, der auf die regionale Traffic Director API ausgerichtet ist:

    gcloud network-connectivity regional-endpoints create td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --network="projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME" \
 --subnetwork="projects/PROJECT_ID/regions/REGION/subnetworks/VPC_SUBNET_NAME" \
 --target-google-api="trafficdirector.REGION.rep.googleapis.com"

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Projekt-ID in Google Cloud .
    • REGION: die Region Ihrer Bereitstellung.
    • VPC_NETWORK_NAME: der Name des VPC-Netzwerk.
    • VPC_SUBNET_NAME: der Name Ihres VPC-Subnetzes.

  2. Rufen Sie die interne IP-Adresse des regionalen Endpunkts ab:

    TD_ENDPOINT_IP=$(gcloud network-connectivity regional-endpoints describe td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --format="value(address)")

  3. Erstellen Sie eine private, von Cloud DNS verwaltete Zone für die Traffic Director API:

    gcloud dns managed-zones create td-psc-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone for regional endpoint" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

  4. Fügen Sie einen A-Eintrag hinzu, der die regionale Domain der Traffic Director API in die IP-Adresse des regionalen Endpunkts auflöst:

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-psc-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${TD_ENDPOINT_IP}"

  5. Prüfen Sie den regionalen Endpunkt und den DNS-Eintragssatz:

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-psc-zone"

    Prüfen Sie, ob der A-Eintrag für trafficdirector.REGION.rep.googleapis.com. auf die IP-Adresse des regionalen Endpunkts verweist.

Cloud Run-Dienst mit Ambient Networking und Direct VPC-Ausgang bereitstellen oder aktualisieren

Wenn Sie Ihren Cloud Run-Agenten mit der Secure Web Proxy-Instanz in Ihrem VPC-Netzwerk verbinden möchten, aktivieren Sie sowohl ausgehenden Direct VPC-Traffic als auch regionales Ambient Networking und konfigurieren Sie den Dienst mit einer Agentenidentität. Wenn Sie mit --functional-type=agent und --identity-type=agent-identity bereitstellen, gewährt Cloud Run roles/run.agentDefaultAccess, einschließlich der Berechtigungen roles/trafficdirector.client und roles/cloudtrace.agent:

  1. Stellen Sie einen neuen Cloud Run-Agent-Dienst bereit oder aktualisieren Sie einen vorhandenen Dienst, um regionales Ambient Networking, ausgehenden Direct VPC-Traffic für den gesamten ausgehenden Traffic und die Agent-Identität zu aktivieren:

    Neuer Dienst

    gcloud beta run deploy SERVICE_NAME \
 --image=IMAGE_URL \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    Vorhandener Dienst

    gcloud beta run services update SERVICE_NAME \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --update-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    Ersetzen Sie Folgendes:

    • SERVICE_NAME: der Name Ihres Cloud Run-Agentendienstes.
    • IMAGE_URL: ein Verweis auf das Container-Image, z. B. us-docker.pkg.dev/cloudrun/container/hello:latest Wenn Sie Artifact Registry verwenden, muss das Repository REPO_NAME bereits erstellt sein. Die URL hat das Format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • VPC_NETWORK_NAME: der Name des VPC-Netzwerk, in dem Ihre Secure Web Proxy-Instanz gehostet wird. Informationen zum Erstellen eines VPC-Netzwerk und -Subnetzes finden Sie unter VPC-Netzwerke erstellen und verwalten.
    • VPC_SUBNET_NAME: der Name des VPC-Subnetzes, in dem Ihre Secure Web Proxy-Instanz erreichbar ist.
    • REGION: die Region Ihres Dienstes.
    • PROJECT_ID: Projekt-ID in Google Cloud .

  2. Prüfen Sie, ob Ihr Cloud Run-Dienst Ambient Networking, Direct VPC-Ausgang und Agent Identity verwendet:

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID

    Prüfen Sie, ob in der Ausgabe das Subnetz für ausgehenden Direct VPC-Traffic, ausgehender Traffic von all-traffic, regionales Ambient Networking und das zugewiesene Agent-Identitäts-Hauptkonto angezeigt werden.

Cloud Run-Agenten so konfigurieren, dass er dem KI-Agenten-Gateway vertraut

Damit Secure Web Proxy HTTPS-Nutzlasten prüfen und Richtlinien erzwingen kann, muss er ausgehende TLS-Sitzungen von Ihrem Agent beenden. Der Cloud Run-Agent-Container muss dem Zertifikat der Stamm- oder untergeordneten Zertifizierungsstelle (CA) vertrauen, das mit Ihrer Secure Web Proxy-TLS-Prüfungsrichtlinie im CA Service oder Ihrer privaten Unternehmens-PKI verknüpft ist:

  1. Exportieren Sie das PEM-codierte CA-Zertifikat aus dem CA Service-Pool für Ihre Secure Web Proxy-Instanz:

    gcloud privateca pools get-ca-certs CA_POOL_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --output-file=agent-gateway-root.crt

    Ersetzen Sie Folgendes:

    • CA_POOL_NAME: der Name des CA-Pools, der mit Ihrer TLS-Prüfungsrichtlinie für Secure Web Proxy verknüpft ist.
    • REGION: die Region Ihres CA-Pools.
    • PROJECT_ID: Projekt-ID in Google Cloud .

  2. Aktualisieren Sie Ihren Cloud Run-Dienst, um den Zertifikatsinhalt in einer Umgebungsvariablen zu übergeben:

    gcloud beta run services update SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --update-env-vars="AGENT_GATEWAY_ROOT_CERT=$(cat agent-gateway-root.crt)"

    Ersetzen Sie Folgendes:

    • SERVICE_NAME: der Name Ihres Cloud Run-Agentendienstes.
    • REGION: die Region Ihres Dienstes.
    • PROJECT_ID: Projekt-ID in Google Cloud .

    Mit dem folgenden Debian- oder Ubuntu-Container-Einstiegspunkt-Skript entrypoint.sh wird beispielsweise AGENT_GATEWAY_ROOT_CERT im Trust Store des Systems installiert und die CA-Bundle-Pfade für Python- und gRPC-Clients werden exportiert, bevor Ihre Anwendung gestartet wird:

    #!/usr/bin/env bash
set -e
if [ -n "${AGENT_GATEWAY_ROOT_CERT}" ]; then
 printf '%s\n' "${AGENT_GATEWAY_ROOT_CERT}" > /usr/local/share/ca-certificates/agent-gateway.crt
 update-ca-certificates
 export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
 export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
 export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt
fi
exec "$@"

  3. Prüfen Sie, ob Ihr Dienst die Umgebungsvariable AGENT_GATEWAY_ROOT_CERT festlegt:

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --format="yaml(spec.template.spec.containers[0].env)"

Ausgehenden Traffic an das Agent Gateway weiterleiten

Nachdem Sie Ihren Cloud Run-Dienst und das Agent-Gateway konfiguriert haben, erstellen Sie eine Network Services API-Richtlinie (EgressRouting), um ausgehenden Traffic von Ihrem Cloud Run-Dienst an Ihr Secure Web Proxy-Gateway weiterzuleiten:

  1. Erstellen Sie die Ressource EgressRouting:

    gcloud alpha network-services egress-routings create my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME"

    Ersetzen Sie Folgendes:

    • REGION: Die Region Ihres Cloud Run-Dienstes und -Gateways.
    • PROJECT_ID: Projekt-ID in Google Cloud .
    • SWP_NAME: der Name der zugrunde liegenden Secure Web Proxy-Ressource Gateway, nicht der Ressource AgentGateway.
    • SERVICE_NAME: der Name Ihres Cloud Run-Agentendienstes. Wenn Sie alle Cloud Run-Dienste im Projekt mit einer einzigen Richtlinie über das Gateway weiterleiten möchten, setzen Sie workloadUri auf //run.googleapis.com/projects/PROJECT_ID oder //run.googleapis.com/projects/PROJECT_NUMBER.

    Nachdem EgressRouting wirksam geworden ist, wird der gesamte ausgehende Traffic von Ihrem Cloud Run-Dienst über Secure Web Proxy weitergeleitet. Konfigurieren Sie im nächsten Abschnitt Richtlinien, um ausgehende Anfragen zuzulassen und zu steuern.

  2. Prüfen Sie, ob die Ressource EgressRouting aktiv ist:

    gcloud alpha network-services egress-routings describe my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID

    Prüfen Sie, ob in sources der URI Ihrer Cloud Run-Arbeitslast aufgeführt ist und in gateway auf Ihre Secure Web Proxy-Gateway-Ressource verwiesen wird.

Richtlinien für das KI-Agenten-Gateway konfigurieren

Nachdem Sie den ausgehenden Traffic über das Agent Gateway weitergeleitet haben, können Sie die ausgehenden Anfragen Ihres KI-Agenten steuern, indem Sie Autorisierungsrichtlinien und Service Extensions-Erweiterungsbindungen an Ihre Agent Gateway-Ressource anhängen:

  • Baseline-Traffic und MCP-Tool-Filterung: Modellendpunkte und genehmigte MCP-Methoden und -Tools (Model Context Protocol) mit ALLOW-Autorisierungsrichtlinien zulassen.
  • Identitätsbasierte Zugriffssteuerung: Binden Sie IAP an eine ExtensionBinding-Ressource und konfigurieren Sie eine einheitliche IAM-Zugriffsrichtlinie, um zu steuern, welche KI-Agenten bestimmte MCP-Server, Tools oder Endpunkte aufrufen können.
  • Inhaltssicherheit: Binden Sie Model Armor an eine ExtensionBinding-Ressource, um Prompts und Antworten auf Prompt Injection, Datenlecks oder Richtlinienverstöße zu prüfen und zu bereinigen.

Alle Autorisierungsrichtlinien oder Gateway-Sicherheitsrichtlinienregeln, die an die zugrunde liegende Secure Web Proxy-Ressource Gateway angehängt sind, werden ignoriert. Nachdem Sie eine ExtensionBinding-Ressource erstellt oder aktualisiert haben, kann es bis zu fünf Minuten dauern, bis die Änderungen an das Gateway weitergegeben werden. Informationen zur Reihenfolge der Regelauswertung für Netzwerkregeln, TLS-Prüfung, Erweiterungsbindungen und HTTP-Regeln finden Sie unter Reihenfolge der Auswertung für Autorisierungsregeln.

Ausgehenden Baseline-Traffic und MCP-Traffic zulassen

Secure Web Proxy lehnt standardmäßig den gesamten ausgehenden Traffic mit 403 Forbidden-Fehlern ab, bis eine ALLOW-AuthzPolicy für Ihre Agent Gateway-Ressource dies zulässt.

Da Ihr Cloud Run-Dienst --vpc-egress=all verwendet, wird der gesamte ausgehende Container-Traffic, einschließlich MCP-Toolaufrufen und LLM-Anfragen, über das Gateway weitergeleitet. Hängen Sie ALLOW-Autorisierungsrichtlinien für beide Traffictypen an Ihre Agent Gateway-Ressource an:

IAP-Richtlinien für ausgehenden Traffic konfigurieren

Agent Gateway verwendet IAP als Richtlinienentscheidungs-Engine, um IAM Unified Access Policies auszuwerten. Wenn Sie Richtlinien für die Identität von KI-Agenten erzwingen möchten, definieren Sie Ihre Zugriffsregeln in einer IAM Unified Access Policy und binden Sie IAP an Ihr Gateway:

  1. Erstellen Sie eine einheitliche IAM-Zugriffsrichtlinie mit dem Hauptkonto Agent-Identität (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME) Ihres Cloud Run-Dienstes und binden Sie die Richtlinie an Ihr Projekt oder Gateway. Folgen Sie dazu den Anleitungen unter IAM-Zugriffsrichtlinien erstellen und Einheitliche Zugriffsrichtlinie an ein Projekt binden.
  2. Binden Sie IAP (iap.googleapis.com) mit einer ExtensionBinding an Ihr Agent Gateway. Folgen Sie dazu der Anleitung unter IAP an Ihr Agent Gateway binden.

Da --vpc-egress=all Modellaufrufe wie REGION-aiplatform.googleapis.com über das Gateway sendet, müssen Sie den Bereich matchConditions in Ihrer IAP-ExtensionBinding auf prefix: "urn:mcp" festlegen, damit Modellaufrufe die IAP-Bewertung umgehen. Wenn Sie auch den Traffic zwischen KI-Agenten verwalten möchten, fügen Sie prefix: "urn:agent" hinzu. Wenn Ihre Erweiterungsbindung mit anderen Hosts übereinstimmt, fügen Sie in Ihrer IAM Unified Access Policy für jeden Host eine Zulassungsregel hinzu, z. B. destination.unregistered.host == 'REGION-aiplatform.googleapis.com'. Ein Beispiel finden Sie unter Richtlinie für Agent-zu-nicht registriertem Endpunkt erstellen.

Model Armor-Richtlinien konfigurieren

Wenn Sie Prompts und Antworten, die über Ihr Agent Gateway geleitet werden, prüfen und bereinigen möchten, erstellen Sie Model Armor-Vorlagen und binden Sie sie an Ihr Gateway:

  1. Erstellen Sie regionale Model Armor-Anfrage- und Antwortvorlagen und weisen Sie dem Service Extensions-Dienst-Agent die erforderlichen Rollen zu. Folgen Sie dazu der Anleitung unter Model Armor auf einem Gateway konfigurieren.
  2. Hängen Sie Ihre Vorlagen mit einem ExtensionBinding an Ihr Agent Gateway an. Folgen Sie dazu der Anleitung unter Model Armor für die Bereinigung von Prompts und Antworten binden.

Zentrale projektübergreifende Bereitstellung mit freigegebene VPC konfigurieren

In einer Organisation mit mehreren Projekten können Sie Ihre Cloud Run-Agents in einem oder mehreren Dienstprojekten bereitstellen und gleichzeitig ein Agent Gateway, eine Secure Web Proxy-Instanz und eine Agent Registry in einem dedizierten Netzwerk-Hostprojekt mit einer gemeinsam genutzten VPC hosten:

  • Projekt A, Agent-Dienstprojekt: Hostet den Cloud Run-Agent-Dienst und die lokale EgressRouting-Richtlinie.
  • Projekt B, Gateway- und Netzwerk-Hostprojekt: Fungiert als Hostprojekt der freigegebene VPC und muss das Agent-Gateway, die Secure Web Proxy-Instanz, die Agent-Registry, ExtensionBinding-Ressourcen und IAM-Richtlinienbindungen hosten.
Projektübergreifendes Architekturdiagramm, das Projekt A mit einem Cloud Run-Dienst und einer Routingrichtlinie für ausgehenden Traffic zeigt, das über ein freigegebene VPC-Netzwerk mit Projekt B verbunden ist, in dem das Agent-Gateway, der Secure Web Proxy und die Agent-Registry gehostet werden.
Abbildung 2. Projektübergreifende Agent-Gateway-Bereitstellung mit gemeinsam genutzter VPC.

Bevor Sie mit diesen Schritten beginnen, aktivieren Sie run.googleapis.com, compute.googleapis.com, networkservices.googleapis.com und trafficdirector.googleapis.com in Projekt A sowie aiplatform.googleapis.com, wenn Ihr Agent Vertex AI aufruft. Stellen Sie in Projekt B die Secure Web Proxy-Instanz und die Agent Gateway-Ressource im freigegebene VPC-Netzwerk bereit, wie unter Selbstverwaltetes Agent Gateway erstellen beschrieben. Konfigurieren Sie das DNS- oder Private Service Connect-Routing, wie unter Cloud Run-Ambient-Netzwerk für den Zugriff auf die Traffic Director API konfigurieren beschrieben, damit Ambient-Sidecars in Projekt A die Traffic Director API erreichen können.

So konfigurieren Sie eine projektübergreifende Bereitstellung:

  1. Konfigurieren Sie Projekt B als Hostprojekt für eine freigegebene VPC, hängen Sie Projekt A als Dienstprojekt an und geben Sie das Subnetz frei, in dem Ihre Secure Web Proxy-Instanz gehostet wird. Zum Aktivieren einer gemeinsam genutzten VPC und zum Anhängen von Dienstprojekten ist roles/compute.xpnAdmin auf Organisations- oder Ordnerebene erforderlich. Eine Anleitung finden Sie unter Traffic mit ausgehendem Direct VPC-Traffic an ein gemeinsam genutztes VPC-Netzwerk senden und Gemeinsam genutzte VPC bereitstellen.

  2. Gewähren Sie in Projekt B dem Cloud Run-Dienst-Agent aus Projekt A die Berechtigung roles/compute.networkUser für das freigegebene Subnetz:

    gcloud compute networks subnets add-iam-policy-binding SHARED_SUBNET_NAME \
   --project=PROJECT_B_ID \
   --region=REGION \
   --member="serviceAccount:service-PROJECT_A_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
   --role="roles/compute.networkUser"

    Ersetzen Sie Folgendes:

    • SHARED_SUBNET_NAME: der Name des freigegebenen Subnetzes in Projekt B.
    • PROJECT_B_ID: die Projekt-ID von Projekt B, dem Gateway und dem freigegebene VPC-Hostprojekt.
    • REGION: die Region des freigegebenen Subnetzes.
    • PROJECT_A_NUMBER: die Projektnummer von Projekt A, dem Agent-Dienstprojekt.

  3. Stellen Sie den Cloud Run-Agent-Dienst in Projekt A bereit und verweisen Sie auf das freigegebene Subnetz in Projekt B:

    gcloud beta run deploy SERVICE_NAME \
   --project=PROJECT_A_ID \
   --image=IMAGE_URL \
   --subnet=projects/PROJECT_B_ID/regions/REGION/subnetworks/SHARED_SUBNET_NAME \
   --vpc-egress=all \
   --functional-type=agent \
   --identity-type=agent-identity \
   --ambient-networking \
   --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
   --region=REGION

    Ersetzen Sie Folgendes:

    • SERVICE_NAME: der Name Ihres Cloud Run-Agent-Dienstes in Projekt A.
    • PROJECT_A_ID: die Projekt-ID von Projekt A, dem Agent-Dienstprojekt.
    • IMAGE_URL: ein Verweis auf das Container-Image, z. B. us-docker.pkg.dev/cloudrun/container/hello:latest Wenn Sie Artifact Registry verwenden, muss das Repository REPO_NAME bereits erstellt sein. Die URL hat das Format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

    Nachdem Sie den Dienst bereitgestellt haben, konfigurieren Sie Ihren Agenten in Projekt A so, dass er dem Root-CA-Zertifikat der Secure Web Proxy-Instanz in Projekt B vertraut. Folgen Sie dazu der Anleitung unter Cloud Run-Agenten so konfigurieren, dass er Agent Gateway vertraut.

  4. Erstellen Sie in Projekt A eine EgressRouting-Richtlinie, die auf das Secure Web Proxy-Gateway in Projekt B verweist. Sie benötigen roles/networkservices.admin in Projekt A:

    gcloud alpha network-services egress-routings create my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_B_ID/locations/REGION/gateways/CENTRAL_SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_A_ID/locations/REGION/services/SERVICE_NAME"

    Ersetzen Sie CENTRAL_SWP_NAME durch den Namen des Secure Web Proxy-Gateways in Projekt B. Wenn Sie alle Cloud Run-Dienste in Projekt A über das Gateway von Projekt B weiterleiten möchten, setzen Sie workloadUri auf //run.googleapis.com/projects/PROJECT_A_ID oder //run.googleapis.com/projects/PROJECT_A_NUMBER.

  5. Prüfen Sie, ob die projektübergreifende EgressRouting-Ressource in Projekt A aktiv ist:

    gcloud alpha network-services egress-routings describe my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID

  6. Konfigurieren Sie zentrale Baseline-, IAP- und Model Armor-Richtlinien für die Agent Gateway-Ressource in Projekt B, wie unter Richtlinien für Agent Gateway konfigurieren beschrieben:

    • Lassen Sie Baseline-MCP- und Modell-Traffic für die Agent Gateway-Ressource in Projekt B zu, indem Sie die Anleitung unter Baseline-Traffic für ausgehenden Traffic und MCP-Traffic zulassen befolgen.
    • Wenn Sie den KI-Agenten in Projekt A autorisieren möchten, in Projekt B registrierte MCP-Server aufzurufen, erstellen Sie in Projekt B eine IAM Unified Access Policy, deren principals-Liste auf die Projektnummer von Projekt A (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_A_NUMBER/locations/REGION/services/SERVICE_NAME) verweist. Binden Sie die Richtlinie an Projekt B oder die zugehörige Agent Gateway-Ressource und hängen Sie die IAP-ExtensionBinding in Projekt B an.
    • Wenn Sie zentralisierte Model Armor-Schutzmaßnahmen in Projekt B anwenden möchten, erstellen Sie Ihre regionalen Model Armor-Vorlagen, weisen Sie dem Dienst-Agent für Diensterweiterungen von Projekt B die erforderlichen Rollen zu und hängen Sie die Model Armor-ExtensionBinding an die Agent Gateway-Ressource in Projekt B an.

Logs und Traces ansehen

Ausgehende KI-Agenten-Interaktionen, die über das Agent Gateway weitergeleitet werden, generieren Logs und verteilte Traces, sodass Sie Richtlinienentscheidungen überwachen und das Verhalten des KI-Agenten debuggen können:

Wenn ausgehende Anfragen fehlschlagen oder das Gateway umgehen, finden Sie weitere Informationen unter Fehlerbehebung beim Agent-Gateway.

Unterstützte Regionen

Sie können das Agent Gateway in Cloud Run in den folgenden Regionen verwenden:

  • europe-west1
  • us-central1

Beschränkungen

Zusätzlich zu den Einschränkungen für Ambient Networking und den Überlegungen zu Secure Web Proxy unter Secure Web Proxy als Agent Gateway bereitstellen gelten die folgenden Einschränkungen, wenn Sie Agent Gateway mit Cloud Run verwenden:

  • Ausgehende Agent-Anfragen, die über eine TLS-Prüfinstanz von Secure Web Proxy an die Endpunkte *.mtls.googleapis.com und *.mtls.run.app weitergeleitet werden, schlagen mit 503-Fehlern fehl, da Secure Web Proxy TLS-Sitzungen beendet und neu startet, ohne das Clientzertifikat weiterzuleiten.
  • Jedes regionale selbstverwaltete Agent Gateway unterstützt höchstens eine regionale Agent Registry in seiner registries-Liste.
  • Standardmäßig unterstützt jedes Projekt bis zu 10 regionale AgentGateway-Ressourcen und 10 regionale EgressRouting-Ressourcen pro Region. Neue Projekte beginnen möglicherweise mit einem Limit von 2 pro Region. Wenden Sie sich an Ihr Account-Management-Team, um eine Kontingenterhöhung anzufordern.
  • Sie müssen das Stamm- oder untergeordnete Zertifikat aus Ihrem CA Service-Pool oder Ihrer privaten Unternehmens-PKI exportieren und Ihren Agent-Container so konfigurieren, dass er ihm vertraut.

Nächste Schritte