Privater Zugriff auf Apigee über die Gemini Enterprise Agent Platform

Diese Seite gilt für Apigee, aber nicht für Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

In diesem Dokument wird beschrieben, wie Sie private Verbindungen von einem Agent konfigurieren, der in der Gemini Enterprise Agent Platform-Agent-Laufzeit bereitgestellt wird, zu APIs und MCP-Tools (Model Context Protocol), die mit Private Service Connect in Apigee veröffentlicht werden. Bei diesem Muster bleibt der Traffic vom Agent zu Apigee vollständig privat und durchläuft nicht das öffentliche Internet.

Übersicht

Agent Runtime stellt Ihren Agent in einem sicheren, von Google verwalteten Netzwerk ohne Zugriff auf Ihr VPC-Netzwerk (Virtual Private Cloud) bereit. Apigee wird ebenfalls in einem sicheren, von Google verwalteten Netzwerk ausgeführt. Wenn die Aufrufe eines Agents an ein Large Language Model (LLM) oder an MCP-Tools, die über Apigee bereitgestellt werden, privat erfolgen sollen, benötigen Sie eine Möglichkeit, diese beiden von Google verwalteten Netzwerke über ein VPC-Netzwerk zu verbinden, das Sie steuern.

In diesem Dokument wird das folgende Muster für diese Bridge beschrieben:

  • Agent Runtime stellt eine Private Service Connect-Schnittstelle (PSC-Schnittstelle) bereit, die eine Verbindung zu einem Netzwerkanhang in einem Subnetz Ihrer Nutzer-VPC herstellt. Ausgehender Traffic von Ihrem Agent wird in diese VPC geleitet.
  • In derselben VPC des Nutzers erstellen Sie einen Private Service Connect-Endpunkt, der auf den Dienstanhang verweist, den Ihre Apigee-Instanz bereitstellt.
  • Sie erstellen eine private Cloud DNS-Zone in der VPC des Nutzers, in der der Hostname der Apigee-Umgebungsgruppe in die IP-Adresse des Private Service Connect-Endpunkts aufgelöst wird.
  • Agent Runtime verwendet DNS-Peering, um den Hostnamen aus der Agent Runtime-Umgebung aufzulösen. Dazu wird die private Zone in Ihrer Consumer-VPC verwendet.

Wenn Ihr Agent mit dieser Konfiguration https://APIGEE_HOSTNAME/... aufruft, wird die Anfrage an die IP-Adresse des Private Service Connect-Endpunkts in Ihrer VPC weitergeleitet, über den Dienstanhang an Ihre Apigee-Instanz gesendet und vom API-Proxy verarbeitet, der dem Anfragepfad entspricht.

Hinweis

In diesem Dokument werden die folgenden Platzhalter in Befehlen verwendet. Ersetzen Sie sie durch Werte aus Ihrer Umgebung.

  • APIGEE_PROJECT_ID: die Google Cloud Projekt-ID, die Ihre Apigee-Organisation enthält.
  • SERVICE_PROJECT_ID: die Google Cloud Projekt-ID, in der Sie Ihren Agent in der Agent Runtime bereitstellen. Das kann dasselbe wie APIGEE_PROJECT_ID oder ein anderes Projekt sein, je nachdem, wie Sie Ihre Google Cloud-Ressourcen organisieren.
  • SERVICE_PROJECT_NUMBER: die numerische Projektnummer für SERVICE_PROJECT_ID. Sie können sie mit gcloud projects describe SERVICE_PROJECT_ID --format="value(projectNumber)" abrufen.
  • HOST_PROJECT_ID: die Google Cloud Projekt-ID, die das VPC-Netzwerk, das Subnetz und die private Cloud DNS-Zone des Nutzers enthält. Das ist dasselbe wie SERVICE_PROJECT_ID, es sei denn, Sie verwenden eine gemeinsam genutzte VPC. In diesem Fall ist es das Hostprojekt, an das das Dienstprojekt angehängt wird.
  • REGION: Die Region Ihrer Apigee-Instanz (z. B. us-west1).
  • VPC_NAME: der Name des Nutzer-VPC-Netzwerk in HOST_PROJECT_ID.
  • SUBNET_NAME: der Name eines Subnetzes in VPC_NAME, das sich in REGION befindet.
  • APIGEE_HOSTNAME: Der Hostname, den Sie in der Apigee-Umgebungsgruppe konfiguriert haben (z. B. api.internal.example.com).
  • BASE_PATH: Der Basispfad des API-Proxy, der in Apigee bereitgestellt wird (z. B. /mcp oder /orders).
  • PARENT_DNS_NAME: die übergeordnete DNS-Domain von APIGEE_HOSTNAME, die Sie über die private Zone bereitstellen möchten (z. B. internal.example.com.). Der Wert muss mit einem Punkt enden.
  • APIGEE_INSTANCE_NAME: Der Name Ihrer Apigee-Instanz in REGION.

Sie benötigen Folgendes:

  • Ein oder mehrere Google Cloud-Projekte (wie in der vorherigen Anmerkung beschrieben) mit aktivierter Abrechnung.
  • Eine vorhandene Apigee-Organisation in APIGEE_PROJECT_ID mit mindestens einer Instanz. In diesem Dokument werden alle Netzwerkressourcen des Nutzers (Netzwerkanhang, Private Service Connect-Endpunkt, Agent Runtime-Bereitstellung) in derselben Region wie Ihre Apigee-Instanz erstellt. Dies ist die einfachste Konfiguration.
  • Eine Umgebungsgruppe, deren Umgebungen auf dieser Apigee-Instanz bereitgestellt werden und die den Hostnamen enthält, den Ihr Agent aufrufen soll. In diesem Dokument wird dieser Hostname als APIGEE_HOSTNAME bezeichnet.
  • Mindestens ein API-Proxy, der in einer Umgebung in dieser Umgebungsgruppe bereitgestellt wird. Alle Proxys, die der Agent aufrufen soll, müssen unter https://APIGEE_HOSTNAME/BASE_PATH erreichbar sein.
  • Ein VPC-Netzwerk und ein Subnetz in HOST_PROJECT_ID in derselben Region wie die Apigee-Instanz. In diesem Dokument werden sie als VPC_NAME und SUBNET_NAME bezeichnet. Agent Runtime erfordert ein Subnetz mit mindestens /28 und unterliegt zusätzlichen Bereichseinschränkungen. Weitere Informationen finden Sie in der Dokumentation zur Agent Platform unter Anforderungen an den IP-Bereich des Subnetzes.
  • Die folgenden APIs sind im entsprechenden Projekt aktiviert:
    • Apigee (apigee.googleapis.com) in APIGEE_PROJECT_ID.
    • Compute Engine (compute.googleapis.com) und Cloud DNS (dns.googleapis.com) in HOST_PROJECT_ID.
    • Agent Platform (aiplatform.googleapis.com) in SERVICE_PROJECT_ID.
  • Ausreichende IAM-Berechtigungen zum Erstellen von Cloud DNS-Zonen und -Einträgen, Compute Engine-Adressen, Netzwerkverbindungen und Private Service Connect-Weiterleitungsregeln in HOST_PROJECT_ID sowie zum Aktualisieren der Apigee-Instanz- und Umgebungsgruppenkonfiguration in APIGEE_PROJECT_ID. Weitere Informationen zu den erforderlichen Rollen finden Sie unter Apigee-Rollen, Cloud DNS-Zugriffssteuerung und Compute Engine-IAM-Rollen.

Architektur

In den folgenden Schritten wird der Traffic-Fluss zwischen einem in der Agent Runtime bereitgestellten Agent und einem in Apigee gehosteten API-Proxy beschrieben, wobei ein Private Service Connect-Endpunkt in einer VPC des Nutzers als Brücke dient.

  1. Der in der Agent Runtime ausgeführte Agent sendet eine HTTPS-Anfrage an APIGEE_HOSTNAME.
  2. Das auf der PSC-Schnittstelle der Agent Runtime konfigurierte DNS-Peering leitet den Lookup an die private Cloud DNS-Zone in Ihrer Consumer-VPC weiter, die die IP-Adresse des Private Service Connect-Endpunkts zurückgibt.
  3. Die Anfrage des Agents wird über die PSC-Schnittstelle in Ihr Nutzer-VPC-Netzwerk übertragen und erreicht den Private Service Connect-Endpunkt an dieser IP-Adresse.
  4. Der Private Service Connect-Endpunkt leitet die Anfrage über die Dienstverbindung an den Dienstanhang der Apigee-Instanz weiter.
  5. Die Apigee-Instanz beendet TLS, gleicht den Hostnamen der Anfrage mit der Umgebungsgruppe ab und leitet die Anfrage an den richtigen API-Proxy weiter.

Schritt 1: Netzwerk im Nutzer-VPC konfigurieren

In diesem Abschnitt werden Ressourcen in zwei Projekten konfiguriert. Jeder Befehl enthält ein explizites --project-Flag, sodass Sie die Befehle über jede aktive gcloud-Konfiguration ausführen können:

  • Cloud DNS-Ressourcen (private Zone und Eintrag) werden in HOST_PROJECT_ID erstellt, da die private Zone an das VPC-Netzwerk des Verbrauchers angehängt wird.
  • Die Private Service Connect-Endpunktressourcen (statische interne IP-Adresse und Weiterleitungsregel) und die Netzwerkverbindung werden in SERVICE_PROJECT_ID erstellt. Für jeden dieser Befehle wird ein projektübergreifender Verweis auf das freigegebene Subnetz oder VPC-Netzwerk in HOST_PROJECT_ID verwendet. Bei einer Bereitstellung in einem einzelnen Projekt sind SERVICE_PROJECT_ID und HOST_PROJECT_ID identisch. Es gibt also keine Änderungen des Inhabers zwischen den Schritten. Weitere Informationen zum Modell für freigegebene VPC für Private Service Connect-Endpunkte finden Sie unter Endpunkt in einem freigegebene VPC-Dienstprojekt erstellen.

Private Cloud DNS-Zone erstellen

Erstellen Sie eine private Cloud DNS-Zone, die nur für Ihre Consumer-VPC sichtbar ist. Der Agent verwendet diese Zone (über DNS-Peering), um APIGEE_HOSTNAME in eine private IP-Adresse aufzulösen. 

gcloud dns managed-zones create apigee-private \
  --project=HOST_PROJECT_ID \
  --dns-name="PARENT_DNS_NAME" \
  --description="Private zone for Apigee PSC access" \
  --visibility=private \
  --networks=VPC_NAME

Weitere Informationen zu privaten Cloud DNS-Zonen finden Sie unter Private Zonen.

Netzwerkanhang erstellen

Erstellen Sie einen Netzwerkanhang in derselben Region und demselben Subnetz, in dem die PSC-Schnittstelle der Agent Runtime angezeigt werden soll. Die PSC-Schnittstelle der Agent Runtime wird an diesen Anhang gebunden, wenn der KI-Agent bereitgestellt wird.

Erstellen Sie in einer Bereitstellung mit einem einzelnen Projekt die Netzwerkverbindung in SERVICE_PROJECT_ID (das auch HOST_PROJECT_ID ist). In einer Bereitstellung mit freigegebene VPC können Sie die Netzwerkverbindung entweder im Dienstprojekt oder im Hostprojekt erstellen. Die Agent-Plattform empfiehlt das Dienstprojekt, um Berechtigungen zu vereinfachen. Informationen zur Auswahl und den entsprechenden IAM-Rollen finden Sie unter Private Service Connect-Schnittstelle mit gemeinsam genutzter VPC verwenden.

Mit dem folgenden Befehl wird die Netzwerkverbindung in SERVICE_PROJECT_ID erstellt. Bei einer Bereitstellung mit freigegebene VPC muss der Subnetzverweis die Hostprojekt-ID enthalten. 

gcloud compute network-attachments create agent-network-attachment \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnets=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \
  --connection-preference=ACCEPT_AUTOMATIC

Statische interne IP-Adresse reservieren

Reservieren Sie eine interne IP-Adresse, die als IP-Adresse des Private Service Connect-Endpunkts verwendet wird, mit dem der Agent eine Verbindung herstellt. Erstellen Sie die Adressressource in SERVICE_PROJECT_ID und verweisen Sie in HOST_PROJECT_ID auf das freigegebene Subnetz, damit der Adresswert aus dem Bereich dieses Subnetzes zugewiesen wird. Dies entspricht den Richtlinien für freigegebene VPC unter Statische interne IP-Adresse mit gemeinsam genutzter VPC verwenden. 

gcloud compute addresses create apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnet=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME

Rufen Sie die reservierte Adresse ab, die Sie in späteren Schritten verwenden: 

gcloud compute addresses describe apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(address)"

In diesem Dokument wird diese Adresse als PSC_ENDPOINT_IP bezeichnet.

Dienstanhang für die Apigee-Instanz abrufen

Rufen Sie den URI des Dienstanhangs für Ihre Apigee-Instanz mit der Methode organizations.instances.get der Apigee API ab. Sie verwenden diesen URI als Ziel für den Private Service Connect-Endpunkt. 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

Die Antwort enthält ein Feld serviceAttachment. In diesem Dokument wird dieser Wert als APIGEE_SERVICE_ATTACHMENT bezeichnet. Weitere Informationen dazu, wie Apigee einen Dienstanhang für jede Instanz bereitstellt, finden Sie unter Instanzen verwalten.

Private Service Connect-Endpunkt erstellen

Erstellen Sie eine Weiterleitungsregel, die als Private Service Connect-Endpunkt fungiert. Sie ist auf den Apigee-Dienstanhang ausgerichtet und verwendet die statische IP-Adresse, die Sie reserviert haben. Erstellen Sie die Weiterleitungsregel in SERVICE_PROJECT_ID und verweisen Sie auf das gemeinsam genutzte VPC-Netzwerk in HOST_PROJECT_ID und die Adresse in SERVICE_PROJECT_ID. 

gcloud compute forwarding-rules create apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --network=projects/HOST_PROJECT_ID/global/networks/VPC_NAME \
  --address=projects/SERVICE_PROJECT_ID/regions/REGION/addresses/apigee-psc-endpoint-ip \
  --target-service-attachment=APIGEE_SERVICE_ATTACHMENT

Prüfen Sie, ob der Apigee-Dienst die Verbindung akzeptiert hat: 

gcloud compute forwarding-rules describe apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(pscConnectionStatus)"

Der Status muss ACCEPTED sein, bevor der Endpunkt Traffic weiterleiten kann. Weitere Informationen zu Private Service Connect-Endpunkten finden Sie unter Zugriff auf veröffentlichte Dienste über Endpunkte.

DNS-Eintrag für den Hostnamen hinzufügen

Erstellen Sie in der privaten Zone einen A-Eintrag, der APIGEE_HOSTNAME in PSC_ENDPOINT_IP auflöst. Dieser Eintrag ist nur in VPC_NAME sichtbar. Externe Clients lösen den Hostnamen also weiterhin über das öffentliche DNS auf. 

gcloud dns record-sets create APIGEE_HOSTNAME. \
  --project=HOST_PROJECT_ID \
  --zone=apigee-private \
  --type=A \
  --ttl=60 \
  --rrdatas=PSC_ENDPOINT_IP

Schritt 2: Apigee konfigurieren

Dienstprojekt der Nutzerannahmeliste der Instanz hinzufügen

Die Apigee-Instanz akzeptiert nur Private Service Connect-Verbindungen von Nutzerprojekten, die sich in der consumerAcceptList befinden. Die Nutzerseite der Verbindung ist mit SERVICE_PROJECT_ID verknüpft, da der Agent in diesem Projekt bereitgestellt wird.

Standardmäßig ist das mit der Apigee-Organisation (APIGEE_PROJECT_ID) verknüpfte Projekt bereits in der Liste enthalten. Wenn SERVICE_PROJECT_ID mit APIGEE_PROJECT_ID übereinstimmt, ist keine Änderung erforderlich und Sie können diesen Abschnitt überspringen. Fügen Sie andernfalls SERVICE_PROJECT_ID der Liste hinzu.

Prüfen Sie zuerst den aktuellen Wert von consumerAcceptList mit der Methode organizations.instances.get: 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

Suchen Sie in der Antwort nach dem Feld consumerAcceptList.

Aktualisieren Sie dann die Liste, indem Sie die Methode organizations.instances.patch mit einer Aktualisierungsmaske für consumerAcceptList aufrufen. Da das Feld die vorhandene Liste ersetzt, müssen Sie jede Projekt-ID angeben, die weiterhin Zugriff haben soll, einschließlich APIGEE_PROJECT_ID und aller zusätzlichen Dienstprojekte, in denen Agents bereitgestellt werden: 

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"consumerAcceptList": ["APIGEE_PROJECT_ID", "SERVICE_PROJECT_ID"]}' \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME?updateMask=consumerAcceptList"

Bestätigen Sie das Update, indem Sie den Befehl get noch einmal ausführen und prüfen, ob SERVICE_PROJECT_ID jetzt in consumerAcceptList enthalten ist.

Hostname der Umgebungsgruppe überprüfen

Prüfen Sie, ob APIGEE_HOSTNAME in der Umgebungsgruppe aufgeführt ist, in der Ihre API-Proxys gehostet werden. Falls nicht, fügen Sie sie hinzu.

Eine Anleitung finden Sie unter Mit Umgebungsgruppen arbeiten.

Schritt 3: Agent mit einer PSC-Schnittstelle und DNS-Peering bereitstellen

Wenn Sie Ihren Agent in der Agent Runtime bereitstellen, konfigurieren Sie ihn mit einer PSC-Schnittstelle, die auf den von Ihnen erstellten Netzwerkanhang verweist, und konfigurieren Sie das DNS-Peering für Ihre private Zone. Die vollständige Bereitstellungsprozedur und die unterstützten Frameworks finden Sie in der Agent Platform-Dokumentation unter Private Service Connect-Schnittstelle mit Agent Runtime verwenden und Agents bereitstellen.

Konfigurieren Sie die folgenden beiden Felder in der PSC-Schnittstellenkonfiguration des Agenten (siehe PscInterfaceConfig):

  • networkAttachment: Legen Sie diesen Wert auf den vollständigen Ressourcennamen des Netzwerkanhangs fest, den Sie in Schritt 1 erstellt haben, im Format projects/SERVICE_PROJECT_ID/regions/REGION/networkAttachments/agent-network-attachment. Wenn Sie den Netzwerk-Anhang stattdessen im Hostprojekt erstellt haben, verwenden Sie HOST_PROJECT_ID in diesem Pfad.
  • dnsPeeringConfigs: Fügen Sie einen Eintrag mit den folgenden Feldern hinzu, damit die Agent Runtime APIGEE_HOSTNAME über Ihre private Zone auflöst:
    • domain: PARENT_DNS_NAME. Der Wert muss mit einem Punkt enden.
    • targetProject: HOST_PROJECT_ID. Das ist das Projekt, das die VPC des Nutzers und die private Zone enthält.
    • targetNetwork: VPC_NAME.

Der Agent Platform Service Agent für SERVICE_PROJECT_ID (service-SERVICE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) muss die Berechtigung haben, DNS-Peering zu konfigurieren und die Netzwerkverbindung zu aktualisieren. Weisen Sie die erforderlichen Rollen wie unter Erforderliche Rolle für den Dienst-Agenten der Agent Platform beschrieben zu. In einer Bereitstellung mit freigegebene VPC gelten zusätzliche Rollen für das Hostprojekt. Weitere Informationen finden Sie unter Private Service Connect-Schnittstelle mit gemeinsam genutzter VPC verwenden.

Rufen Sie den API-Proxy aus dem Agent-Code unter https://APIGEE_HOSTNAME/BASE_PATH auf. In der Agent Runtime-Umgebung wird dieser Hostname über DNS-Peering in PSC_ENDPOINT_IP aufgelöst. Die Anfrage durchläuft den Private Service Connect-Endpunkt in Ihre VPC und weiter zu Apigee.

Privaten Pfad überprüfen

Nachdem Sie den Agent bereitgestellt haben, prüfen Sie, ob Anfragen über den privaten Pfad an Apigee gesendet werden:

  • Prüfen Sie mit dem Befehl in Private Service Connect-Endpunkt erstellen, ob der Status der Weiterleitungsregel ACCEPTED ist.
  • Führen Sie dig +short APIGEE_HOSTNAME auf einer Compute Engine-VM aus, die an VPC_NAME in REGION angehängt ist. In einer Bereitstellung mit freigegebene VPC kann sich diese VM entweder im Hostprojekt oder in einem Dienstprojekt befinden, das an die gemeinsam genutzte VPC angehängt ist. Das Ergebnis muss PSC_ENDPOINT_IP lauten. So wird bestätigt, dass die private Zone den Hostnamen in der VPC richtig auflöst.
  • Senden Sie von derselben VM aus eine Anfrage an einen bereitgestellten API-Proxy unter https://APIGEE_HOSTNAME/BASE_PATH und prüfen Sie, ob Sie die erwartete Antwort erhalten.
  • Rufen Sie den bereitgestellten Agenten auf und bestätigen Sie, dass die Anfrage bearbeitet wird. Verwenden Sie dann Apigee Analytics oder Debug, um zu bestätigen, dass die Anfrage am erwarteten API-Proxy auf dem Hostnamen der Umgebungsgruppe eingegangen ist.

Nächste Schritte