Connetti il processore di estensioni Apigee a un Agent Gateway

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive come connettere il processore di estensione Apigee a un Agent Gateway, in modo che le norme Apigee vengano applicate alle chiamate che un agente AI effettua al suo modello, ai suoi strumenti e ai server Model Context Protocol (MCP) che utilizza, senza modificare l'agente.

Un Agent Gateway è il punto di ingresso e di uscita della rete per il traffico di un agente. Non è un bilanciatore del carico, quindi non utilizza un'estensione del traffico. Il gateway delega l'autorizzazione a un'estensione di autorizzazione e configuri il processore di estensione come estensione. Una volta connesso, il gateway invia ogni richiesta e risposta dell'agente ad Apigee per l'elaborazione e Apigee restituisce un verdetto.

La figura seguente mostra le risorse che crei in questa pagina e il percorso che una singola richiesta dell'agente segue al loro interno:

Una richiesta dell'agente viene trattenuta all'Agent Gateway, inviata ad Apigee tramite Private Service Connect per un verdetto e poi inoltrata.
Figura 1. Componenti e flusso di richieste quando il processore di estensioni Apigee è l'estensione di autorizzazione per un Agent Gateway.

Nella figura 1, una richiesta viene gestita nel seguente modo:

  1. L'agente effettua una normale richiesta HTTPS al suo modello, a uno strumento o a un server MCP. L'agente è associato al gateway al momento della creazione e non richiede modifiche.
  2. Il gateway contiene la richiesta e chiama l'estensione di autorizzazione per un verdetto.
  3. Il callout esce tramite il collegamento di rete, quindi ha origine all'interno della rete VPC.
  4. La zona DNS privata risolve il nome host di callout nell'indirizzo IP interno dell'endpoint Private Service Connect.
  5. L'endpoint inoltra il callout al collegamento al servizio della tua istanza Apigee.
  6. Il gruppo di ambienti indirizza il callout in base al nome host al proxy senza target, dove vengono eseguiti i criteri.
  7. Il proxy restituisce un verdetto al gateway. Apigee non inoltra mai il traffico dell'agente. Il proxy non ha una destinazione.
  8. Se il verdetto consente la richiesta, il gateway invia la richiesta originale alla destinazione.

AuthzPolicy e AuthzExtension nella figura 1 sono configurazioni piuttosto che traffico: la policy collega l'estensione al gateway e i nomi delle estensioni il proxy del processore di estensioni in esecuzione. Crea entrambi in Configura l'estensione di autorizzazione.

Per connettere il processore di estensione a un bilanciamento del carico, vedi Guida introduttiva al processore di estensione Apigee.

Le sezioni seguenti ti guidano nei passaggi:

Prima di iniziare

Prima di iniziare, completa le seguenti attività:

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

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

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

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

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

    8.

  8. Installa Google Cloud CLI.

    Dopo aver installato Google Cloud CLI, esegui il comando gcloud components update per ottenere i componenti gcloud più recenti.

  9. Esegui il provisioning di un'istanza Apigee, se non l'hai ancora fatto.

    Nella console Google Cloud , vai alla pagina Istanze Apigee.

    Vai a Istanze Apigee

  10. Esegui il deployment di un Agent Gateway nella stessa regione dell'istanza Apigee, con governedAccessPath impostato su AGENT_TO_ANYWHERE in modo che il gateway gestisca il traffico in uscita dell'agente. Per maggiori informazioni, vedi Configura Agent Gateway.

    Aggiornerai la configurazione di rete di questo gateway in un secondo momento, in Aggiorna il gateway dell'agente, dopo che la zona DNS esiste.

  11. Verifica di avere un VPC e una subnet che possono essere utilizzati sia da Agent Gateway sia dall'endpoint Private Service Connect.

    Vai a Reti VPC

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per connettere il processore di estensioni Apigee a un Agent Gateway, chiedi all'amministratore di concederti i seguenti ruoli IAM:

  • Crea e gestisci risorse Apigee: Apigee Org Admin (roles/apigee.admin) sull'organizzazione
  • Crea e gestisci le estensioni di servizio: Service Extensions Admin (roles/networkservices.serviceExtensionsAdmin) sull'organizzazione
  • Crea e gestisci policy di autorizzazione: Network Security Admin (roles/networksecurity.admin) sull'organizzazione
  • Crea e gestisci risorse di rete, inclusi endpoint Private Service Connect e DNS: Compute Network Admin (roles/compute.networkAdmin) nell'organizzazione

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Imposta le variabili di ambiente

Imposta le seguenti variabili di ambiente per identificare le risorse che hai creato in Prima di iniziare. Ogni sezione successiva di questa pagina definisce le variabili aggiuntive necessarie nel punto in cui crei la risorsa che nomina.

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

Dove:

  • PROJECT_ID è l'ID del progetto che contiene la tua istanza Apigee.
  • REGION è la regione Google Cloud dell'istanza Apigee.
  • INSTANCE è il nome della tua istanza Apigee.
  • VPC_NETWORK_NAME e SUBNET sono la rete VPC e la subnet utilizzate da Agent Gateway e dall'endpoint Private Service Connect.
  • GATEWAY è il nome di Agent Gateway che hai eseguito il deployment.

Per verificare che le variabili di ambiente siano impostate correttamente, esegui questo comando e controlla l'output:

echo $PROJECT_ID $ORG_NAME $REGION $INSTANCE $VPC_NETWORK_NAME $SUBNET $GATEWAY

Scegli il nome host del callout

Il gateway raggiunge Apigee a un nome host privato che scegli. Lo scegli ora, prima di creare qualsiasi cosa, perché la prima risorsa che crei, il gruppo di ambienti Apigee, lo utilizza come nome host, mentre la zona DNS che lo risolve non viene creata fino a quando non viene eseguito il passaggio Crea una zona DNS privata.

export DNS_DOMAIN=DNS_DOMAIN
export EXTPROC_HOST=apigee-extproc.$DNS_DOMAIN

Dove DNS_DOMAIN è un dominio DNS privato che non deve essere risolvibile su internet pubblico, scritto senza un punto finale, ad esempio internal.example.com. In questo modo si ottiene un EXTPROC_HOST di apigee-extproc.internal.example.com. Puoi utilizzare un'etichetta diversa da apigee-extproc, purché il nome host rimanga all'interno di DNS_DOMAIN.

Configura un token di autenticazione

export TOKEN=$(gcloud auth print-access-token)
echo $TOKEN

Configurare il processore di estensioni Apigee

Assegna un nome alle risorse Apigee create da questa sezione:

export EXTPROC_ENV=EXTPROC_ENV
export EXTPROC_ENVGROUP=EXTPROC_ENVGROUP
export PROXY_NAME=PROXY_NAME

Dove:

  • EXTPROC_ENV e EXTPROC_ENVGROUP sono nomi che scegli per un ambiente e un gruppo di ambienti Apigee dedicati al processore di estensioni, ad esempio extproc-env e extproc-envgroup. Ogni nome deve essere composto da 2-32 caratteri di lettere minuscole, numeri o trattini, deve iniziare con una lettera e non può terminare con un trattino. Il nome dell'ambiente deve essere diverso da tutti gli altri nomi di ambiente della tua organizzazione.
  • PROXY_NAME è un nome che scegli per il proxy del processore di estensioni, ad esempio extproc-authz.

La parte Apigee della configurazione è la stessa di un bilanciatore del carico. Segui la Configurazione del processore di estensioni Apigee nella guida rapida per:

  1. Crea un ambiente Apigee con la proprietà apigee-service-extension-enabled impostata su true, collegalo alla tua istanza e crea un gruppo di ambienti il cui nome host è $EXTPROC_HOST.
  2. Crea ed esegui il deployment di un proxy del processore di estensioni senza target in quell'ambiente.

Quindi, elenca i deployment nell'ambiente:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments/$EXTPROC_ENV/deployments"

L'ambiente può avere più di un proxy di cui è stato eseguito il deployment, quindi nella risposta trova la voce il cui apiProxy è $PROXY_NAME e annota il relativo revision.

Puoi esaminare il proxy nella console Google Cloud :

Vai a Proxy API

Imposta la seguente variabile su questa revisione, che ti serve in Verifica la connessione:

export REVISION=REVISION

Connettere l'Agent Gateway ad Apigee

Il gateway raggiunge Apigee tramite un endpoint Private Service Connect nel tuo VPC, che trova risolvendo $EXTPROC_HOST in una zona DNS privata.

Trovare il collegamento al servizio

Trova il service attachment della tua istanza Apigee:

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances"

Imposta la seguente variabile sul valore serviceAttachment dell'istanza nella tua regione:

export SERVICE_ATTACHMENT=SERVICE_ATTACHMENT

Crea un collegamento di rete

L'Agent Gateway esce nel VPC tramite un collegamento di rete. Scegli un nome, ad esempio agent-gateway-attachment, e crea il gruppo:

export NETWORK_ATTACHMENT=NETWORK_ATTACHMENT
gcloud compute network-attachments create $NETWORK_ATTACHMENT \
    --region=$REGION --subnets=$SUBNET --connection-preference=ACCEPT_AUTOMATIC

Crea l'endpoint Private Service Connect

Riserva un indirizzo IP interno e crea l'endpoint Private Service Connect:

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

Nella console Google Cloud , vai alla pagina Private Service Connect .

Vai a Private Service Connect

Verifica che l'endpoint riporti pscConnectionStatus: ACCEPTED e imposta la seguente variabile sul suo indirizzo IP:

gcloud compute forwarding-rules describe apigee-extproc-psc-endpoint \
    --region=$REGION --format="value(pscConnectionStatus,IPAddress)"
export PSC_IP=PSC_IP

Se lo stato è PENDING, il tuo progetto non si trova in consumerAcceptList dell'istanza Apigee e la connessione non può essere accettata.

Crea una zona DNS privata

Crea una zona DNS privata per $DNS_DOMAIN e un record A che risolve $EXTPROC_HOST nell'indirizzo IP dell'endpoint:

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

Aggiorna l'Agent Gateway

Aggiorna Agent Gateway dalla sezione Prima di iniziare in modo che esca tramite il collegamento di rete e possa risolvere la zona che hai creato.

  1. Esporta la configurazione attuale:

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

  2. In agent-gateway.yaml, aggiungi il seguente blocco networkConfig, sostituendo ogni segnaposto con il valore della variabile di ambiente corrispondente. Il file viene modificato direttamente, quindi le variabili della shell non vengono sostituite qui:

    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

    Lascia il resto del file, inclusi googleManaged.governedAccessPath, protocols e registries, così com'è stato esportato.

  3. Importa la configurazione modificata:

    gcloud network-services agent-gateways import $GATEWAY \
    --location=$REGION --source=agent-gateway.yaml

Per l'insieme completo dei campi di Agent Gateway, vedi Configura Agent Gateway.

Configurare l'estensione di autorizzazione

Due risorse collegano il gateway al proxy del processore delle estensioni: un'estensione di autorizzazione che punta ad Apigee e un criterio di autorizzazione che collega l'estensione al gateway.

Crea l'estensione di autorizzazione

Scegli un nome per l'estensione di autorizzazione, ad esempio apigee-authz-extension. I campi metadata selezionano quale proxy Apigee viene eseguito e se i corpi dei messaggi vengono inviati:

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

Dove:

  • apigee-extension-processor seleziona il proxy del processore di estensione che elabora il traffico.
  • apigee-request-body e apigee-response-body rendono disponibili i corpi della richiesta e della risposta nel proxy come request.content e response.content. Senza di loro, i criteri che ispezionano il payload non trovano nulla.

Crea la policy di autorizzazione

Scegli un nome per la policy di autorizzazione, ad esempio apigee-content-authz-policy. Il criterio collega l'estensione al gateway e determina quale traffico viene inviato ad Apigee:

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

Utilizza policyProfile: CONTENT_AUTHZ in modo che i corpi dei messaggi vengano ispezionati. Una policy REQUEST_AUTHZ valuta solo le intestazioni delle richieste.

Verificare la connessione

Per generare traffico, devi avere un agente la cui uscita è regolata da questo gateway. Un agente è associato a un gateway quando viene creato, impostando la configurazione dell'Agent Gateway su $GATEWAY; non puoi esercitare la connessione con una richiesta HTTP diretta al gateway. Per maggiori informazioni, vedi Configura Agent Gateway.

Avvia una sessione di debug di Apigee sul proxy del processore di estensioni, quindi invia una richiesta tramite l'agente:

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*\")"}'

Nelle transazioni acquisite, verifica che:

  • l'URL della richiesta è l'indirizzo chiamato dall'agente, ad esempio l'endpoint del modello o un host di strumenti, anziché un percorso di base Apigee;
  • request.content e response.content sono compilati, il che conferma che i metadati del corpo dell'estensione di autorizzazione funzionano.

Se non vengono visualizzate transazioni, verifica che il nome host del gruppo di ambienti, il record DNS e i campi authority e service dell'estensione siano tutti $EXTPROC_HOST, che l'endpoint Private Service Connect riporti ACCEPTED e che governedAccessPath del gateway sia AGENT_TO_ANYWHERE.

Passaggi successivi