Diese Seite gilt für Apigee und Apigee Hybrid.
Apigee Edge-Dokumentation aufrufen
Auf dieser Seite wird beschrieben, wie Sie den Apigee-Erweiterungsprozessor mit einem Agent Gateway verbinden, damit Apigee-Richtlinien auf die Aufrufe angewendet werden, die ein KI-Agent an sein Modell, seine Tools und die von ihm verwendeten MCP-Server (Model Context Protocol) richtet, ohne dass der Agent geändert werden muss.
Ein Agent Gateway ist der Ein- und Ausgangspunkt für den Traffic eines Agenten. Es handelt sich nicht um einen Load-Balancer, daher wird keine Traffic-Erweiterung verwendet. Stattdessen delegiert das Gateway die Autorisierung an eine Autorisierungserweiterung und Sie konfigurieren den Erweiterungsprozessor als diese Erweiterung. Sobald die Verbindung hergestellt ist, sendet das Gateway jede Agent-Anfrage und -Antwort zur Verarbeitung an Apigee. Apigee gibt dann ein Ergebnis zurück.
Die folgende Abbildung zeigt die Ressourcen, die Sie auf dieser Seite erstellen, und den Pfad, den eine einzelne Agent-Anfrage durchläuft:
In Abbildung 1 wird eine Anfrage so verarbeitet:
- Der KI-Agent sendet eine normale HTTPS-Anfrage an sein Modell, ein Tool oder einen MCP-Server. Der Agent ist beim Erstellen an das Gateway gebunden und muss nicht geändert werden.
- Das Gateway hält die Anfrage zurück und ruft die Autorisierungserweiterung auf, um eine Entscheidung zu treffen.
- Der Callout verlässt das Netzwerk über die Netzwerkverbindung und stammt daher aus Ihrem VPC-Netzwerk.
- Ihre private DNS-Zone löst den Callout-Hostnamen in die interne IP-Adresse des Private Service Connect-Endpunkts auf.
- Der Endpunkt leitet den Callout an den Dienstanhang Ihrer Apigee-Instanz weiter.
- Die Umgebungsgruppe leitet den Callout anhand des Hostnamens an den Proxy ohne Ziel weiter, in dem Ihre Richtlinien ausgeführt werden.
- Der Proxy gibt ein Ergebnis an das Gateway zurück. Apigee leitet den Traffic des Agents nie weiter, da der Proxy kein Ziel hat.
- Wenn die Anfrage laut dem Ergebnis zulässig ist, sendet das Gateway die ursprüngliche Anfrage an das Ziel weiter.
Die AuthzPolicy und AuthzExtension in Abbildung 1 sind Konfigurationen und kein Traffic: Mit der Richtlinie wird die Erweiterung an das Gateway angehängt und mit den Erweiterungsnamen wird der Proxy des Erweiterungsprozessors benannt, der ausgeführt wird. Beide werden unter Autorisierungserweiterung konfigurieren erstellt.
Wenn Sie den Erweiterungsprozessor stattdessen mit einem Load-Balancer verbinden möchten, lesen Sie den Abschnitt Erste Schritte mit dem Apigee-Erweiterungsprozessor.
In den folgenden Abschnitten werden die einzelnen Schritte beschrieben:
- Apigee-Erweiterungsprozessor konfigurieren
- Agent Gateway mit Apigee verbinden
- Autorisierungserweiterung konfigurieren
- Verbindung prüfen
Hinweis
Führen Sie die folgenden Aufgaben aus, bevor Sie beginnen:
- Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie 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.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Apigee, Compute Engine, Network Services, Network Security, and Cloud DNS APIs.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Apigee, Compute Engine, Network Services, Network Security, and Cloud DNS APIs.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.Installieren Sie die Google Cloud CLI.
Führen Sie nach der Installation der Google Cloud CLI den Befehl
gcloud components updateaus, um die neuesten gcloud-Komponenten abzurufen.Stellen Sie eine Apigee-Instanz bereit, falls noch nicht geschehen.
Rufen Sie in der Google Cloud Console die Seite Apigee-Instanzen auf.
Stellen Sie ein Agent Gateway in derselben Region wie Ihre Apigee-Instanz bereit. Setzen Sie
governedAccessPathaufAGENT_TO_ANYWHERE, damit das Gateway den ausgehenden Traffic des KI-Agenten steuert. Weitere Informationen finden Sie unter Agent Gateway konfigurieren.Sie aktualisieren die Netzwerkkonfiguration dieses Gateways später in Agent Gateway aktualisieren, nachdem die DNS-Zone vorhanden ist.
Prüfen Sie, ob Sie ein VPC-Netzwerk und ein Subnetz haben, die sowohl vom Agent Gateway als auch vom Private Service Connect-Endpunkt verwendet werden können.
Erforderliche Rollen
Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, damit Sie die nötigen Berechtigungen zum Verbinden des Apigee-Erweiterungsprozessors mit einem Agent Gateway haben:
-
Apigee-Ressourcen erstellen und verwalten:
Apigee Org Admin (
roles/apigee.admin) in der Organisation -
Diensterweiterungen erstellen und verwalten:
Service Extensions Admin (
roles/networkservices.serviceExtensionsAdmin) in der Organisation -
Autorisierungsrichtlinien erstellen und verwalten:
Network Security Admin (
roles/networksecurity.admin) für die Organisation -
Netzwerkressourcen erstellen und verwalten, einschließlich Private Service Connect-Endpunkten und DNS:
Compute-Netzwerkadministrator (
roles/compute.networkAdmin) in der Organisation
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.
Umgebungsvariablen festlegen
Legen Sie die folgenden Umgebungsvariablen fest, um die Ressourcen zu identifizieren, die Sie unter Vorbereitung erstellt haben. In jedem späteren Abschnitt auf dieser Seite werden die zusätzlichen Variablen definiert, die benötigt werden, wenn Sie die dort genannte Ressource erstellen.
export PROJECT_ID=PROJECT_IDexport ORG_NAME=$PROJECT_IDexport REGION=REGIONexport INSTANCE=INSTANCEexport VPC_NETWORK_NAME=VPC_NETWORK_NAMEexport SUBNET=SUBNETexport GATEWAY=GATEWAY
Wobei:
PROJECT_IDist die ID des Projekts, das Ihre Apigee-Instanz enthält.REGIONist die Google Cloud Region Ihrer Apigee-Instanz.INSTANCEist der Name Ihrer Apigee-Instanz.VPC_NETWORK_NAMEundSUBNETsind das VPC-Netzwerk und das Subnetz, die vom Agent Gateway und vom Private Service Connect-Endpunkt verwendet werden.GATEWAYist der Name des Agent-Gateways, das Sie bereitgestellt haben.
Führen Sie den folgenden Befehl aus und prüfen Sie die Ausgabe, um zu bestätigen, dass die Umgebungsvariablen richtig festgelegt sind:
echo $PROJECT_ID $ORG_NAME $REGION $INSTANCE $VPC_NETWORK_NAME $SUBNET $GATEWAY
Hostname für den Aufruf auswählen
Das Gateway erreicht Apigee über einen privaten Hostnamen, den Sie auswählen. Sie wählen sie jetzt aus, bevor Sie etwas erstellen, da die erste Ressource, die Sie erstellen – die Apigee-Umgebungsgruppe – sie als Hostname verwendet. Die DNS-Zone, die sie auflöst, wird erst unter Private DNS-Zone erstellen erstellt.
export DNS_DOMAIN=DNS_DOMAINexport EXTPROC_HOST=apigee-extproc.$DNS_DOMAIN
Dabei ist DNS_DOMAIN eine private DNS-Domain, die nicht im öffentlichen Internet aufgelöst werden muss. Sie wird ohne nachgestellten Punkt geschrieben, z. B. internal.example.com. Das ergibt einen EXTPROC_HOST von apigee-extproc.internal.example.com. Sie können auch ein anderes Label als apigee-extproc verwenden, solange der Hostname innerhalb von DNS_DOMAIN bleibt.
Authentifizierungstoken konfigurieren
export TOKEN=$(gcloud auth print-access-token)echo $TOKEN
Apigee-Erweiterungsprozessor konfigurieren
Geben Sie die Namen der Apigee-Ressourcen an, die in diesem Abschnitt erstellt werden:
export EXTPROC_ENV=EXTPROC_ENVexport EXTPROC_ENVGROUP=EXTPROC_ENVGROUPexport PROXY_NAME=PROXY_NAME
Wobei:
EXTPROC_ENVundEXTPROC_ENVGROUPsind Namen, die Sie für eine Apigee-Umgebung und eine Umgebungsgruppe auswählen, die dem Erweiterungsprozessor gewidmet sind, z. B.extproc-envundextproc-envgroup. Jeder Name muss aus 2 bis 32 Kleinbuchstaben, Ziffern oder Bindestrichen bestehen, mit einem Buchstaben beginnen und darf nicht mit einem Bindestrich enden. Der Umgebungsname muss sich von allen anderen Umgebungsnamen in Ihrer Organisation unterscheiden.PROXY_NAMEist ein Name, den Sie für den Proxy des Erweiterungsprozessors auswählen, z. B.extproc-authz.
Die Apigee-Seite der Konfiguration ist dieselbe wie für einen Load Balancer. Folgen Sie der Kurzanleitung zum Konfigurieren des Apigee-Erweiterungsprozessors, um:
- Erstellen Sie eine Apigee-Umgebung, in der die Eigenschaft
apigee-service-extension-enabledauftruefestgelegt ist, hängen Sie sie an Ihre Instanz an und erstellen Sie eine Umgebungsgruppe, deren Hostname$EXTPROC_HOSTist. - Erstellen und stellen Sie einen no-target-Erweiterungsprozessor-Proxy in dieser Umgebung bereit.
Lassen Sie sich dann die Bereitstellungen in der Umgebung auflisten:
curl -s -H "Authorization: Bearer $TOKEN" \ "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/deployments"
In der Umgebung kann mehr als ein Proxy bereitgestellt werden. Suchen Sie in der Antwort nach dem Eintrag, dessen apiProxy $PROXY_NAME ist, und notieren Sie sich den revision.
Sie können den Proxy in der Google Cloud -Konsole ansehen:
Legen Sie die folgende Variable auf diese Revision fest, die Sie in Verbindung prüfen benötigen:
export REVISION=REVISION
KI-Agenten-Gateway mit Apigee verbinden
Das Gateway erreicht Apigee über einen Private Service Connect-Endpunkt in Ihrer VPC, den es durch Auflösen von $EXTPROC_HOST in einer privaten DNS-Zone findet.
Dienstanhang suchen
Suchen Sie den Dienstanhang Ihrer Apigee-Instanz:
curl -s -H "Authorization: Bearer $TOKEN" \ "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances"
Legen Sie die folgende Variable auf den serviceAttachment-Wert der Instanz in Ihrer Region fest:
export SERVICE_ATTACHMENT=SERVICE_ATTACHMENT
Netzwerkanhang erstellen
Der ausgehende Traffic des Agent-Gateways wird über einen Netzwerkanhang in Ihr VPC geleitet. Wählen Sie einen Namen dafür aus, z. B. agent-gateway-attachment, und erstellen Sie ihn:
export NETWORK_ATTACHMENT=NETWORK_ATTACHMENTgcloud compute network-attachments create $NETWORK_ATTACHMENT \ --region=$REGION --subnets=$SUBNET --connection-preference=ACCEPT_AUTOMATIC
Private Service Connect-Endpunkt erstellen
Reservieren Sie eine interne IP-Adresse und erstellen Sie den Private Service Connect-Endpunkt:
gcloud compute addresses create apigee-extproc-psc-ip \ --region=$REGION --subnet=$SUBNET --purpose=GCE_ENDPOINTgcloud compute forwarding-rules create apigee-extproc-psc-endpoint \ --region=$REGION --network=$VPC_NETWORK_NAME \ --address=apigee-extproc-psc-ip \ --target-service-attachment=$SERVICE_ATTACHMENT
Rufen Sie in der Google Cloud Console die Seite Private Service Connect auf.
Prüfen Sie, ob der Endpunkt pscConnectionStatus: ACCEPTED meldet, und legen Sie die folgende Variable auf seine IP-Adresse fest:
gcloud compute forwarding-rules describe apigee-extproc-psc-endpoint \ --region=$REGION --format="value(pscConnectionStatus,IPAddress)"export PSC_IP=PSC_IP
Wenn der Status PENDING lautet, befindet sich Ihr Projekt nicht in der consumerAcceptList der Apigee-Instanz und die Verbindung kann nicht akzeptiert werden.
Private DNS-Zone erstellen
Erstellen Sie eine private DNS-Zone für $DNS_DOMAIN und einen A-Eintrag, der $EXTPROC_HOST in die IP-Adresse des Endpunkts auflöst:
gcloud dns managed-zones create extproc-zone \ --dns-name=$DNS_DOMAIN. --visibility=private --networks=$VPC_NETWORK_NAME \ --description="Apigee extension processor callout host"gcloud dns record-sets create $EXTPROC_HOST. --type=A --ttl=300 \ --rrdatas=$PSC_IP --zone=extproc-zone
KI-Agenten-Gateway aktualisieren
Aktualisieren Sie das Agent Gateway unter Vorbereitung, damit der ausgehende Traffic über Ihre Netzwerkverbindung erfolgt und die von Ihnen erstellte Zone aufgelöst werden kann.
Aktuelle Konfiguration exportieren:
gcloud network-services agent-gateways export $GATEWAY \ --location=$REGION --destination=agent-gateway.yaml
Fügen Sie in
agent-gateway.yamlden folgendennetworkConfig-Block ein und ersetzen Sie jeden Platzhalter durch den Wert der entsprechenden Umgebungsvariablen. Die Datei wird direkt bearbeitet, sodass Shell-Variablen hier nicht ersetzt werden:networkConfig: egress: networkAttachment: projects/PROJECT_ID/regions/REGION/networkAttachments/NETWORK_ATTACHMENT dnsPeeringConfig: domains: [ DNS_DOMAIN. ] targetProject: PROJECT_ID targetNetwork: projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME
Lassen Sie den Rest der Datei, einschließlich
googleManaged.governedAccessPath,protocolsundregistries, wie exportiert.Importieren Sie die bearbeitete Konfiguration:
gcloud network-services agent-gateways import $GATEWAY \ --location=$REGION --source=agent-gateway.yaml
Eine vollständige Liste der Agent Gateway-Felder finden Sie unter Agent Gateway konfigurieren.
Autorisierungserweiterung konfigurieren
Zwei Ressourcen verbinden das Gateway mit Ihrem Erweiterungsprozessor-Proxy: eine Autorisierungserweiterung, die auf Apigee verweist, und eine Autorisierungsrichtlinie, mit der die Erweiterung an das Gateway angehängt wird.
Autorisierungserweiterung erstellen
Wählen Sie einen Namen für die Autorisierungserweiterung aus, z. B. apigee-authz-extension.
Mit den metadata-Feldern wird ausgewählt, welcher Apigee-Proxy ausgeführt wird und ob die Nachrichtentexte an ihn gesendet werden:
export AUTHZ_EXT=AUTHZ_EXTcat > authz-extension.yaml <<EOF name: projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT authority: $EXTPROC_HOST service: $EXTPROC_HOST timeout: 5s metadata: apigee-extension-processor: $PROXY_NAME apigee-request-body: 'true' apigee-response-body: 'true' EOFgcloud service-extensions authz-extensions import $AUTHZ_EXT \ --source=authz-extension.yaml --location=$REGION
Wobei:
apigee-extension-processorwählt den Proxy des Erweiterungsprozessors aus, der den Traffic verarbeitet.- Mit
apigee-request-bodyundapigee-response-bodywerden die Anfrage- und Antworttexte im Proxy alsrequest.contentundresponse.contentverfügbar gemacht. Ohne sie finden Richtlinien, die die Nutzlast untersuchen, nichts.
Autorisierungsrichtlinie erstellen
Wählen Sie einen Namen für die Autorisierungsrichtlinie aus, z. B. apigee-content-authz-policy. Mit der Richtlinie wird die Erweiterung an das Gateway angehängt und festgelegt, welcher Traffic an Apigee gesendet wird:
export AUTHZ_POLICY=AUTHZ_POLICYcat > authz-policy.yaml <<EOF name: projects/$PROJECT_ID/locations/$REGION/authzPolicies/$AUTHZ_POLICY action: CUSTOM policyProfile: CONTENT_AUTHZ customProvider: authzExtension: resources: - projects/$PROJECT_ID/locations/$REGION/authzExtensions/$AUTHZ_EXT httpRules: - to: operations: - paths: - prefix: "/" target: resources: - projects/$PROJECT_ID/locations/$REGION/agentGateways/$GATEWAY EOFgcloud beta network-security authz-policies import $AUTHZ_POLICY \ --source=authz-policy.yaml --location=$REGION
Verwenden Sie policyProfile: CONTENT_AUTHZ, damit die Nachrichtentexte geprüft werden.
Eine REQUEST_AUTHZ-Richtlinie wertet nur Anfrageheader aus.
Verbindung prüfen
Damit Traffic generiert werden kann, benötigen Sie einen KI-Agenten, dessen Egress von diesem Gateway gesteuert wird. Ein Agent ist an ein Gateway gebunden, wenn er erstellt wird, indem seine Agent Gateway-Konfiguration auf $GATEWAY gesetzt wird. Die Verbindung kann nicht über eine direkte HTTP-Anfrage an das Gateway hergestellt werden. Weitere Informationen finden Sie unter Agent Gateway konfigurieren.
Starten Sie eine Apigee-Fehlerbehebungssitzung für den Erweiterungsprozessor-Proxy und senden Sie dann eine Anfrage über den Agent:
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/apis/$PROXY_NAME/revisions/$REVISION/debugsessions?timeout=600" \ -d '{"count":15,"tracesize":5120,"filter":"(request.uri Like \"*generateContent*\")"}'
Prüfen Sie bei den erfassten Transaktionen Folgendes:
- Die Anfrage-URL ist die Adresse, die vom Agent aufgerufen wurde, z. B. der Modellendpunkt oder ein Tool-Host, und nicht ein Apigee-Basispfad.
request.contentundresponse.contentsind ausgefüllt. Das bestätigt, dass die Metadaten des Hauptteils in der Autorisierungserweiterung funktionieren.
Wenn keine Transaktionen angezeigt werden, prüfen Sie, ob der Hostname der Umgebungsgruppe, der DNS-Eintrag und die Felder authority und service der Erweiterung alle $EXTPROC_HOST sind, ob der Private Service Connect-Endpunkt ACCEPTED meldet und ob die governedAccessPath des Gateways AGENT_TO_ANYWHERE ist.
Nächste Schritte
- Übersicht über den Apigee-Erweiterungsprozessor
- Erste Schritte mit dem Apigee-Erweiterungsprozessor auf einem Load Balancer