Menghubungkan pemroses ekstensi Apigee ke Agent Gateway

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan cara menghubungkan pemroses ekstensi Apigee ke Agent Gateway, sehingga kebijakan Apigee diterapkan ke panggilan yang dilakukan agen AI ke modelnya, alatnya, dan server Model Context Protocol (MCP) yang digunakannya—tanpa mengubah agen.

Agent Gateway adalah titik masuk dan keluar jaringan untuk traffic agen. Load balancer bukan load balancer, sehingga tidak menggunakan ekstensi traffic. Sebagai gantinya, gateway mendelegasikan otorisasi ke ekstensi otorisasi, dan Anda mengonfigurasi pemroses ekstensi sebagai ekstensi tersebut. Setelah terhubung, gateway mengirimkan setiap permintaan dan respons agen ke Apigee untuk diproses, dan Apigee akan menampilkan hasil.

Gambar berikut menunjukkan resource yang Anda buat di halaman ini, dan jalur yang dilalui satu permintaan agen melalui resource tersebut:

Gambar 1. Komponen dan alur permintaan saat pemroses ekstensi Apigee adalah ekstensi otorisasi untuk Agent Gateway.

Pada gambar 1, permintaan ditangani sebagai berikut:

1. Agen membuat permintaan HTTPS biasa ke model, alat, atau server MCP-nya. Agen terikat ke gateway saat dibuat, dan tidak memerlukan perubahan.
2. Gateway menahan permintaan dan memanggil ekstensi otorisasi untuk mendapatkan keputusan.
3. Panggilan keluar melalui network attachment, sehingga berasal dari dalam Jaringan VPC Anda.
4. Zona DNS pribadi Anda me-resolve nama host panggilan ke alamat IP internal endpoint Private Service Connect.
5. Endpoint meneruskan panggilan ke lampiran layanan instance Apigee Anda.
6. Grup lingkungan merutekan panggilan berdasarkan nama hostnya ke proxy tanpa target, tempat kebijakan Anda dijalankan.
7. Proxy menampilkan putusan ke gateway. Apigee tidak pernah meneruskan traffic agen—proxy tidak memiliki target.
8. Jika putusan mengizinkan permintaan, gateway akan mengirimkan permintaan asli ke tujuannya.

AuthzPolicy dan AuthzExtension pada gambar 1 adalah konfigurasi bukan traffic: kebijakan melampirkan ekstensi ke gateway, dan ekstensi memberi nama proxy pemroses ekstensi yang berjalan. Anda membuat keduanya di Mengonfigurasi ekstensi otorisasi.

Untuk menghubungkan pemroses ekstensi ke load balancer, lihat Mulai menggunakan pemroses ekstensi Apigee.

Bagian berikut akan memandu Anda melalui langkah-langkahnya:

• Konfigurasi pemroses ekstensi Apigee.
• Hubungkan Agent Gateway ke Apigee.
• Konfigurasi ekstensi otorisasi.
• Verifikasi koneksi.

Sebelum memulai

Sebelum memulai, selesaikan tugas berikut:

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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

1. Instal Google Cloud CLI.

   Setelah menginstal Google Cloud CLI, jalankan perintah gcloud components update untuk mendapatkan komponen gcloud terbaru.

2. Sediakan instance Apigee jika Anda belum melakukannya.

   Di konsol Google Cloud , buka halaman Apigee Instances.

   Buka Instance Apigee

3. Deploy Agent Gateway di region yang sama dengan instance Apigee Anda, dengan governedAccessPath ditetapkan ke AGENT_TO_ANYWHERE sehingga gateway mengatur traffic keluar agen. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi Gateway Agen.

   Anda akan memperbarui konfigurasi jaringan gateway ini nanti, di Memperbarui Gateway Agen, setelah zona DNS ada.

4. Pastikan Anda memiliki VPC dan subnet yang dapat digunakan oleh Agent Gateway dan endpoint Private Service Connect.

   Buka Jaringan VPC

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk menghubungkan pemroses ekstensi Apigee ke Agent Gateway, minta administrator untuk memberi Anda peran IAM berikut:

• Membuat dan mengelola resource Apigee: Apigee Org Admin (roles/apigee.admin) di organisasi
• Membuat dan mengelola ekstensi layanan: Service Extensions Admin (roles/networkservices.serviceExtensionsAdmin) di organisasi
• Membuat dan mengelola kebijakan otorisasi: Network Security Admin (roles/networksecurity.admin) di organisasi
• Membuat dan mengelola resource jaringan, termasuk endpoint Private Service Connect dan DNS: Compute Network Admin (roles/compute.networkAdmin) di organisasi

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Menetapkan variabel lingkungan

Tetapkan variabel lingkungan berikut untuk mengidentifikasi resource yang Anda buat di Sebelum memulai. Setiap bagian selanjutnya di halaman ini menentukan variabel tambahan yang diperlukan, pada saat Anda membuat resource yang mereka sebutkan.

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

Dengan:

• PROJECT_ID adalah ID project yang berisi instance Apigee Anda.
• REGION adalah Google Cloud region instance Apigee Anda.
• INSTANCE adalah nama instance Apigee Anda.
• VPC_NETWORK_NAME dan SUBNET adalah jaringan dan subnet VPC yang digunakan oleh Agent Gateway dan endpoint Private Service Connect.
• GATEWAY adalah nama Agent Gateway yang Anda deploy.

Untuk mengonfirmasi bahwa variabel lingkungan telah ditetapkan dengan benar, jalankan perintah berikut dan tinjau outputnya:

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

Pilih nama host info

Gateway menjangkau Apigee di nama host pribadi yang Anda pilih. Anda memilihnya sekarang, sebelum membuat apa pun, karena resource pertama yang Anda buat—grup lingkungan Apigee—menggunakannya sebagai nama host, sementara zona DNS yang menyelesaikannya tidak dibuat hingga Membuat zona DNS pribadi.

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

Dengan DNS_DOMAIN adalah domain DNS pribadi yang tidak harus dapat di-resolve di internet publik, ditulis tanpa titik di akhir, misalnya internal.example.com. Tindakan ini memberikan EXTPROC_HOST dari apigee-extproc.internal.example.com. Anda dapat menggunakan label selain apigee-extproc, asalkan nama host tetap berada di dalam DNS_DOMAIN.

Penting: EXTPROC_HOST digunakan di tiga tempat: nama host grup lingkungan Apigee, data DNS pribadi, dan kolom authority dan service ekstensi otorisasi. Ketiganya harus identik, atau info tidak akan pernah mencapai Apigee. Nama host juga harus berada di dalam DNS_DOMAIN, itulah sebabnya perintah di atas mengambilnya dari variabel tersebut.

Mengonfigurasi token autentikasi

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

Catatan: Jika organisasi Anda menggunakan residensi data, ganti apigee.googleapis.com dalam perintah di halaman ini dengan endpoint regional untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Menggunakan endpoint regional untuk residensi data.

Mengonfigurasi pemroses ekstensi Apigee

Beri nama resource Apigee yang dibuat bagian ini:

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

Dengan:

• EXTPROC_ENV dan EXTPROC_ENVGROUP adalah nama yang Anda pilih untuk grup lingkungan dan lingkungan Apigee yang dikhususkan untuk pemroses ekstensi, misalnya extproc-env dan extproc-envgroup. Setiap nama harus terdiri dari 2 hingga 32 karakter huruf kecil, angka, atau tanda hubung, harus diawali dengan huruf, dan tidak boleh diakhiri dengan tanda hubung. Nama lingkungan harus berbeda dari setiap nama lingkungan lainnya di organisasi Anda.
• PROXY_NAME adalah nama yang Anda pilih untuk proxy pemroses ekstensi, misalnya extproc-authz.

Konfigurasi sisi Apigee sama seperti untuk load balancer. Ikuti Mengonfigurasi pemroses ekstensi Apigee dalam panduan memulai untuk:

1. Buat lingkungan Apigee dengan properti apigee-service-extension-enabled yang ditetapkan ke true, lampirkan ke instance Anda, dan buat grup lingkungan yang nama hostnya adalah $EXTPROC_HOST.
2. Buat dan deploy proxy pemroses ekstensi no-target ke lingkungan tersebut.

Catatan: Panduan memulai ini memberi nama resource ENV_NAME, ENV_GROUP_NAME, dan ENV_GROUP_HOSTNAME. Gunakan $EXTPROC_ENV, $EXTPROC_ENVGROUP, dan $EXTPROC_HOST secara berurutan.

Catatan: Jika ada kebijakan di proxy yang memanggil Google Cloud API, deploy proxy dengan akun layanan dengan menambahkan ?serviceAccount=SERVICE_ACCOUNT_EMAIL ke permintaan deployment. Jika tidak, deployment akan gagal dengan MISSING_SERVICE_ACCOUNT.

Kemudian, cantumkan deployment di lingkungan:

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

Lingkungan dapat memiliki lebih dari satu proxy yang di-deploy, jadi dalam respons, temukan entri yang apiProxy-nya adalah $PROXY_NAME dan catat revision-nya.

Anda dapat meninjau proxy di konsol Google Cloud :

Buka Proxy API

Tetapkan variabel berikut ke revisi tersebut, yang Anda perlukan di Verifikasi koneksi:

export REVISION=REVISION

Menghubungkan Agent Gateway ke Apigee

Gateway menjangkau Apigee melalui endpoint Private Service Connect di VPC Anda, yang ditemukan dengan menyelesaikan $EXTPROC_HOST di zona DNS pribadi.

Menemukan lampiran layanan

Temukan lampiran layanan instance Apigee Anda:

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

Tetapkan variabel berikut ke nilai serviceAttachment instance di region Anda:

export SERVICE_ATTACHMENT=SERVICE_ATTACHMENT

Membuat network attachment

Agent Gateway keluar ke VPC Anda melalui network attachment. Pilih nama untuknya, misalnya agent-gateway-attachment, lalu buat:

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

Buat endpoint Private Service Connect

Cadangkan alamat IP internal dan buat 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

Di konsol Google Cloud , buka halaman Private Service Connect .

Buka Private Service Connect

Konfirmasi bahwa endpoint melaporkan pscConnectionStatus: ACCEPTED, dan tetapkan variabel berikut ke alamat IP-nya:

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

Jika statusnya adalah PENDING, project Anda tidak ada di consumerAcceptList instance Apigee, dan koneksi tidak dapat diterima.

Membuat zona DNS pribadi

Buat zona DNS pribadi untuk $DNS_DOMAIN dan data A yang me-resolve $EXTPROC_HOST ke alamat IP 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

Memperbarui Gateway Agen

Perbarui Agent Gateway dari Sebelum memulai agar keluar melalui lampiran jaringan Anda dan dapat menyelesaikan zona yang Anda buat.

Perhatian: Mengimpor Agent Gateway akan menggantikan seluruh resource. Selalu mulai dari konfigurasi yang diekspor dan edit, bukan menulis file baru, atau kolom yang Anda hapus—seperti protocols dan registries—dihapus dari gateway.

1. Ekspor konfigurasi saat ini:

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

2. Di agent-gateway.yaml, tambahkan blok networkConfig berikut, dengan mengganti setiap placeholder dengan nilai variabel lingkungan yang sesuai. File diedit secara langsung, sehingga variabel shell tidak diganti di sini:

   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

   Biarkan bagian file lainnya, termasuk googleManaged.governedAccessPath, protocols, dan registries, seperti yang diekspor.

3. Impor konfigurasi yang diedit:

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

Untuk mengetahui kumpulan lengkap kolom Agent Gateway, lihat Mengonfigurasi Agent Gateway.

Mengonfigurasi ekstensi otorisasi

Dua resource menghubungkan gateway ke proxy pemroses ekstensi Anda: ekstensi otorisasi yang mengarah ke Apigee, dan kebijakan otorisasi yang melampirkan ekstensi ke gateway.

Buat ekstensi otorisasi

Pilih nama untuk ekstensi otorisasi, misalnya apigee-authz-extension. Kolom metadata memilih proxy Apigee mana yang berjalan dan apakah isi pesan dikirim ke proxy tersebut:

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

Dengan:

• apigee-extension-processor memilih proxy prosesor ekstensi yang memproses traffic.
• apigee-request-body dan apigee-response-body membuat isi permintaan dan respons tersedia di proxy sebagai request.content dan response.content. Tanpa itu, kebijakan yang memeriksa payload tidak akan menemukan apa pun.

Buat kebijakan otorisasi

Pilih nama untuk kebijakan otorisasi, misalnya apigee-content-authz-policy. Kebijakan ini melampirkan ekstensi ke gateway dan menentukan traffic mana yang dikirim ke 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

Gunakan policyProfile: CONTENT_AUTHZ agar isi pesan diperiksa. Kebijakan REQUEST_AUTHZ hanya mengevaluasi header permintaan.

Penting: Contoh di atas mencocokkan setiap permintaan dengan prefix: "/", yang mengirim semua traffic agen ke Apigee—termasuk panggilan sesi, telemetri, dan alatnya. Persempit cakupan dengan to.operations.paths, atau dengan ekspresi Common Expression Language (CEL) di kolom when, sehingga hanya traffic yang ingin Anda atur yang diproses.

Memverifikasi koneksi

Untuk menghasilkan traffic, Anda memerlukan agen yang keluarannya diatur oleh gateway ini. Agen terikat ke gateway saat agen dibuat, dengan menyetel konfigurasi Agent Gateway-nya ke $GATEWAY; Anda tidak dapat menggunakan koneksi dengan permintaan HTTP langsung ke gateway. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi Agent Gateway.

Mulai sesi debug Apigee di proxy pemroses ekstensi, lalu kirim satu permintaan melalui agen:

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

Catatan: Satu giliran agen menghasilkan beberapa transaksi, karena panggilan telemetri dan sesi agen juga melewati gateway. Gunakan kolom filter untuk merekam hanya traffic yang ingin Anda periksa, atau buffer dapat terisi sebelum permintaan yang Anda cari tiba.

Dalam transaksi yang direkam, konfirmasi bahwa:

• URL permintaan adalah alamat yang dipanggil agen, seperti endpoint model atau host alat, bukan jalur dasar Apigee;
• request.content dan response.content diisi, yang mengonfirmasi bahwa metadata isi pada ekstensi otorisasi berfungsi.

Jika tidak ada transaksi yang muncul, periksa apakah nama host grup lingkungan, data DNS, dan kolom authority dan service ekstensi semuanya $EXTPROC_HOST, apakah endpoint Private Service Connect melaporkan ACCEPTED, dan apakah governedAccessPath gateway adalah AGENT_TO_ANYWHERE.

Langkah berikutnya

• Baca ringkasan prosesor ekstensi Apigee.
• Mulai menggunakan pemroses ekstensi Apigee di load balancer.