Apigee-Erweiterungsprozessor mit einem Agent Gateway verbinden

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:

Eine Agent-Anfrage wird am Agent Gateway gehalten, über Private Service Connect zur Entscheidung an Apigee gesendet und dann weitergeleitet.
Abbildung 1. Komponenten und Anfragestrom, wenn der Apigee-Erweiterungsprozessor die Autorisierungserweiterung für ein Agent Gateway ist.

In Abbildung 1 wird eine Anfrage so verarbeitet:

  1. 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.
  2. Das Gateway hält die Anfrage zurück und ruft die Autorisierungserweiterung auf, um eine Entscheidung zu treffen.
  3. Der Callout verlässt das Netzwerk über die Netzwerkverbindung und stammt daher aus Ihrem VPC-Netzwerk.
  4. Ihre private DNS-Zone löst den Callout-Hostnamen in die interne IP-Adresse des Private Service Connect-Endpunkts auf.
  5. Der Endpunkt leitet den Callout an den Dienstanhang Ihrer Apigee-Instanz weiter.
  6. Die Umgebungsgruppe leitet den Callout anhand des Hostnamens an den Proxy ohne Ziel weiter, in dem Ihre Richtlinien ausgeführt werden.
  7. Der Proxy gibt ein Ergebnis an das Gateway zurück. Apigee leitet den Traffic des Agents nie weiter, da der Proxy kein Ziel hat.
  8. 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:

Hinweis

Führen Sie die folgenden Aufgaben aus, bevor Sie beginnen:

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

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

  3. 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.enable permission. 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.

    Enable the APIs

  4. Installieren Sie die Google Cloud CLI.

    Führen Sie nach der Installation der Google Cloud CLI den Befehl gcloud components update aus, um die neuesten gcloud-Komponenten abzurufen.

  5. Stellen Sie eine Apigee-Instanz bereit, falls noch nicht geschehen.

    Rufen Sie in der Google Cloud Console die Seite Apigee-Instanzen auf.

    Zu „Apigee-Instanzen“

  6. Stellen Sie ein Agent Gateway in derselben Region wie Ihre Apigee-Instanz bereit. Setzen Sie governedAccessPath auf AGENT_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.

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

    Zur Seite VPC-Netzwerke

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_ID
export ORG_NAME=$PROJECT_ID
export REGION=REGION
export INSTANCE=INSTANCE
export VPC_NETWORK_NAME=VPC_NETWORK_NAME
export SUBNET=SUBNET
export GATEWAY=GATEWAY

Wobei:

  • PROJECT_ID ist die ID des Projekts, das Ihre Apigee-Instanz enthält.
  • REGION ist die Google Cloud Region Ihrer Apigee-Instanz.
  • INSTANCE ist der Name Ihrer Apigee-Instanz.
  • VPC_NETWORK_NAME und SUBNET sind das VPC-Netzwerk und das Subnetz, die vom Agent Gateway und vom Private Service Connect-Endpunkt verwendet werden.
  • GATEWAY ist 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_DOMAIN
export 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_ENV
export EXTPROC_ENVGROUP=EXTPROC_ENVGROUP
export PROXY_NAME=PROXY_NAME

Wobei:

  • EXTPROC_ENV und EXTPROC_ENVGROUP sind Namen, die Sie für eine Apigee-Umgebung und eine Umgebungsgruppe auswählen, die dem Erweiterungsprozessor gewidmet sind, z. B. extproc-env und extproc-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_NAME ist 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:

  1. Erstellen Sie eine Apigee-Umgebung, in der die Eigenschaft apigee-service-extension-enabled auf true festgelegt ist, hängen Sie sie an Ihre Instanz an und erstellen Sie eine Umgebungsgruppe, deren Hostname $EXTPROC_HOST ist.
  2. 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:

Zu „API-Proxys“

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_ATTACHMENT
gcloud 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_ENDPOINT
gcloud 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.

Zu Private Service Connect

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.

  1. Aktuelle Konfiguration exportieren:

    gcloud network-services agent-gateways export $GATEWAY \
    --location=$REGION --destination=agent-gateway.yaml

  2. Fügen Sie in agent-gateway.yaml den folgenden networkConfig-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, protocols und registries, wie exportiert.

  3. 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_EXT
cat > 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'
EOF
gcloud service-extensions authz-extensions import $AUTHZ_EXT \
    --source=authz-extension.yaml --location=$REGION

Wobei:

  • apigee-extension-processor wählt den Proxy des Erweiterungsprozessors aus, der den Traffic verarbeitet.
  • Mit apigee-request-body und apigee-response-body werden die Anfrage- und Antworttexte im Proxy als request.content und response.content verfü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_POLICY
cat > 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
EOF
gcloud 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.content und response.content sind 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