Mengakses Apigee secara pribadi dari Gemini Enterprise Agent Platform

Halaman ini berlaku untuk Apigee, tetapi tidak untuk Apigee Hybrid.

Lihat dokumentasi Apigee Edge.

Dokumen ini menjelaskan cara mengonfigurasi konektivitas pribadi dari agen yang di-deploy di Platform Agen Gemini Enterprise Agent Runtime ke API dan alat Model Context Protocol (MCP) yang dipublikasikan di Apigee, menggunakan Private Service Connect. Dengan pola ini, traffic dari agen ke Apigee tetap sepenuhnya bersifat pribadi dan tidak melintasi internet publik.

Informasi harga: Untuk mengetahui informasi tentang cara Private Service Connect diukur dan ditagih, lihat Private Service Connect di halaman harga Virtual Private Cloud. Untuk mengetahui harga Agent Platform, lihat Harga Agent Platform.

Ringkasan

Agent Runtime men-deploy agen Anda di jaringan yang aman dan dikelola Google tanpa akses ke jaringan Virtual Private Cloud (VPC) Anda. Demikian pula, Apigee berjalan di jaringan yang aman dan dikelola Google. Jika Anda ingin panggilan agen ke Model Bahasa Besar (LLM) atau ke alat MCP yang diekspos melalui Apigee berjalan secara pribadi, Anda memerlukan cara untuk menghubungkan kedua jaringan yang dikelola Google ini melalui jaringan VPC yang Anda kontrol.

Dokumen ini menjelaskan pola berikut untuk jembatan tersebut:

• Agent Runtime menyediakan antarmuka Private Service Connect (antarmuka PSC) yang terhubung ke lampiran jaringan di subnet VPC konsumen Anda. Traffic keluar dari agen Anda keluar ke VPC tersebut.
• Di VPC konsumen yang sama, Anda membuat endpoint Private Service Connect yang menargetkan lampiran layanan yang diekspos oleh instance Apigee Anda.
• Anda membuat zona pribadi Cloud DNS di VPC konsumen yang menyelesaikan nama host grup lingkungan Apigee ke alamat IP endpoint Private Service Connect.
• Agent Runtime menggunakan peering DNS untuk me-resolve nama host tersebut dari dalam lingkungan Agent Runtime dengan menggunakan zona pribadi di VPC konsumen Anda.

Dengan konfigurasi ini, saat agen Anda memanggil https://APIGEE_HOSTNAME/..., permintaan akan diselesaikan ke IP endpoint Private Service Connect di VPC Anda, diteruskan melalui lampiran layanan ke instance Apigee Anda, dan diproses oleh proxy API yang cocok dengan jalur permintaan.

Catatan: Pola yang dijelaskan dalam dokumen ini menggunakan endpoint Private Service Connect secara langsung. TLS dihentikan di ingress instance Apigee, yang menampilkan sertifikat yang ditandatangani sendiri kepada klien yang terhubung melalui endpoint Private Service Connect. Jika klien Anda memerlukan sertifikat yang dipercaya secara publik di jalur pribadi, gunakan Load Balancer Aplikasi internal dengan grup endpoint jaringan (NEG) Private Service Connect di depan lampiran layanan; lihat Jaringan northbound dengan Private Service Connect untuk pola tersebut.

Sebelum memulai

Dokumen ini menggunakan placeholder berikut dalam perintah. Ganti dengan nilai dari lingkungan Anda.

• APIGEE_PROJECT_ID: Google Cloud project ID yang berisi organisasi Apigee Anda.
• SERVICE_PROJECT_ID: Google Cloud project ID tempat Anda men-deploy agen di Agent Runtime. Project ini dapat sama dengan APIGEE_PROJECT_ID atau project yang berbeda, bergantung pada cara Anda mengatur resource Google Cloud.
• SERVICE_PROJECT_NUMBER: nomor project numerik untuk SERVICE_PROJECT_ID. Anda dapat mengambilnya dengan gcloud projects describe SERVICE_PROJECT_ID --format="value(projectNumber)".
• HOST_PROJECT_ID: project ID Google Cloud yang berisi jaringan VPC konsumen, subnet, dan zona pribadi Cloud DNS. Ini sama dengan SERVICE_PROJECT_ID kecuali jika Anda menggunakan VPC Bersama, dalam hal ini, project host yang dilampirkan project layanan.
• REGION: region instance Apigee Anda (misalnya, us-west1).
• VPC_NAME: nama jaringan VPC konsumen di HOST_PROJECT_ID.
• SUBNET_NAME: nama subnet di VPC_NAME yang berada di REGION.
• APIGEE_HOSTNAME: nama host yang telah Anda konfigurasi di grup lingkungan Apigee (misalnya, api.internal.example.com).
• BASE_PATH: jalur dasar proxy API yang di-deploy di Apigee (misalnya, /mcp atau /orders).
• PARENT_DNS_NAME: domain DNS induk dari APIGEE_HOSTNAME yang ingin Anda sajikan dari zona pribadi (misalnya, internal.example.com.). Nilai harus diakhiri dengan titik.
• APIGEE_INSTANCE_NAME: nama instance Apigee Anda di REGION.

Catatan tentang topologi project: APIGEE_PROJECT_ID, SERVICE_PROJECT_ID, dan HOST_PROJECT_ID bersifat independen. Semuanya dapat berupa project yang sama, semuanya berbeda, atau kombinasi apa pun yang sesuai dengan cara Anda mengatur resource Google Cloud.

• Jika Anda menggunakan VPC Bersama untuk jaringan konsumen, HOST_PROJECT_ID adalah project host dan SERVICE_PROJECT_ID adalah project layanan yang terlampir padanya. Jika tidak, HOST_PROJECT_ID sama dengan SERVICE_PROJECT_ID.
• Untuk mengetahui detail tentang project mana yang memiliki network attachment dan peran IAM yang sesuai dalam deployment VPC Bersama, lihat Menggunakan antarmuka Private Service Connect dengan VPC Bersama dalam dokumentasi Agent Platform.

Anda memerlukan hal berikut:

• Satu atau beberapa project Google Cloud (seperti yang dijelaskan dalam catatan sebelumnya) dengan penagihan diaktifkan.
• Organisasi Apigee yang sudah ada di APIGEE_PROJECT_ID dengan setidaknya satu instance. Dokumen ini membuat semua resource jaringan konsumen (lampiran jaringan, endpoint Private Service Connect, deployment Agent Runtime) di region yang sama dengan instance Apigee Anda, yang merupakan konfigurasi paling sederhana.
• Grup lingkungan yang lingkungannya di-deploy ke instance Apigee tersebut, dan yang menyertakan nama host yang ingin dipanggil oleh agen Anda. Dokumen ini merujuk pada nama host tersebut sebagai APIGEE_HOSTNAME.
• Setidaknya satu proxy API di-deploy ke lingkungan dalam grup lingkungan tersebut. Setiap proxy yang Anda inginkan untuk dipanggil oleh agen harus dapat dijangkau di https://APIGEE_HOSTNAME/BASE_PATH.
• Jaringan dan subnet VPC di HOST_PROJECT_ID, di region yang sama dengan instance Apigee. Dokumen ini merujuk pada sebagai VPC_NAME dan SUBNET_NAME. Agent Runtime memerlukan subnet /28 minimum, dan memberlakukan batasan rentang tambahan. Untuk mengetahui detailnya, lihat Persyaratan rentang IP subnetwork dalam dokumentasi Agent Platform.
• API berikut diaktifkan dalam project yang sesuai:
  • Apigee (apigee.googleapis.com) di APIGEE_PROJECT_ID.
  • Compute Engine (compute.googleapis.com) dan Cloud DNS (dns.googleapis.com) di HOST_PROJECT_ID.
  • Agent Platform (aiplatform.googleapis.com) di SERVICE_PROJECT_ID.
• Izin IAM yang memadai untuk membuat zona dan data Cloud DNS, alamat Compute Engine, lampiran jaringan, dan aturan penerusan Private Service Connect di HOST_PROJECT_ID, serta untuk memperbarui konfigurasi grup lingkungan dan instance Apigee di APIGEE_PROJECT_ID. Untuk mengetahui detail tentang peran yang diperlukan, lihat Peran Apigee, Kontrol akses Cloud DNS, dan Peran IAM Compute Engine.

Arsitektur

Langkah-langkah berikut menjelaskan alur traffic antara agen yang di-deploy di Agent Runtime dan proxy API yang dihosting di Apigee, menggunakan endpoint Private Service Connect di VPC konsumen sebagai jembatan.

1. Agen, yang berjalan di Agent Runtime, membuat permintaan HTTPS ke APIGEE_HOSTNAME.
2. Peering DNS yang dikonfigurasi di antarmuka PSC Agent Runtime meneruskan pencarian ke zona pribadi Cloud DNS di VPC konsumen Anda, yang menampilkan alamat IP endpoint Private Service Connect.
3. Permintaan agen keluar melalui antarmuka PSC ke VPC konsumen Anda dan mencapai endpoint Private Service Connect di alamat IP tersebut.
4. Endpoint Private Service Connect meneruskan permintaan melalui koneksi layanan ke lampiran layanan instance Apigee.
5. Instance Apigee menghentikan TLS, mencocokkan nama host permintaan dengan grup lingkungan, dan merutekan ke proxy API yang benar.

Langkah 1: Konfigurasi jaringan di VPC konsumen

Bagian ini mengonfigurasi resource di dua project. Setiap perintah mencakup flag --project eksplisit sehingga Anda dapat menjalankan perintah dari konfigurasi gcloud aktif mana pun:

• Resource Cloud DNS (zona dan data pribadi) dibuat di HOST_PROJECT_ID, karena zona pribadi terlampir ke jaringan VPC konsumen.
• Resource endpoint Private Service Connect (alamat IP internal statis dan aturan penerusan) serta network attachment dibuat di SERVICE_PROJECT_ID. Setiap perintah ini menggunakan referensi lintas project ke subnet atau jaringan VPC bersama di HOST_PROJECT_ID. Dalam deployment satu project, SERVICE_PROJECT_ID dan HOST_PROJECT_ID sama, sehingga tidak ada perubahan kepemilikan di seluruh langkah. Untuk mengetahui informasi selengkapnya tentang model VPC Bersama untuk endpoint Private Service Connect, lihat Membuat endpoint di project layanan VPC Bersama.

Membuat zona pribadi Cloud DNS

Buat zona pribadi Cloud DNS yang hanya dapat dilihat oleh VPC konsumen Anda. Agen menggunakan zona ini (melalui peering DNS) untuk menyelesaikan APIGEE_HOSTNAME ke alamat IP pribadi.

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

Untuk mengetahui informasi selengkapnya tentang zona pribadi Cloud DNS, lihat Zona pribadi.

Membuat network attachment

Buat lampiran jaringan di region dan subnet yang sama tempat Anda ingin antarmuka PSC Agent Runtime muncul. Agent Runtime mengikat antarmuka PSC-nya ke lampiran ini saat agen di-deploy.

Dalam deployment project tunggal, buat network attachment di SERVICE_PROJECT_ID (yang juga HOST_PROJECT_ID). Dalam deployment VPC Bersama, Anda dapat membuat network attachment di project layanan atau project host; Agent Platform merekomendasikan project layanan untuk menyederhanakan izin. Untuk panduan dalam memilih dan peran IAM yang sesuai, lihat Menggunakan antarmuka Private Service Connect dengan VPC Bersama.

Perintah berikut akan membuat network attachment di SERVICE_PROJECT_ID. Dalam deployment VPC Bersama, referensi subnet harus menyertakan project ID host.

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

Mencadangkan alamat IP internal statis

Cadangkan alamat IP internal untuk digunakan sebagai IP endpoint Private Service Connect yang terhubung ke agen. Buat resource alamat di SERVICE_PROJECT_ID, dan referensikan subnet bersama di HOST_PROJECT_ID sehingga nilai alamat dialokasikan dari rentang subnet tersebut. Hal ini sesuai dengan panduan VPC Bersama di Menggunakan alamat IP internal statis dengan VPC Bersama.

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

Ambil alamat yang dipesan, yang akan Anda gunakan di langkah-langkah berikutnya:

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

Dokumen ini merujuk ke alamat ini sebagai PSC_ENDPOINT_IP.

Mendapatkan lampiran layanan untuk instance Apigee

Ambil URI lampiran layanan untuk instance Apigee Anda menggunakan metode organizations.instances.get Apigee API. Anda menggunakan URI ini sebagai target untuk endpoint Private Service Connect.

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

Respons mencakup kolom serviceAttachment. Dokumen ini merujuk pada nilai tersebut sebagai APIGEE_SERVICE_ATTACHMENT. Untuk mengetahui informasi selengkapnya tentang cara Apigee mengekspos lampiran layanan di setiap instance, lihat Mengelola instance.

Buat endpoint Private Service Connect

Buat aturan penerusan yang bertindak sebagai endpoint Private Service Connect. Tindakan ini menargetkan lampiran layanan Apigee dan menggunakan IP statis yang Anda cadangkan. Buat aturan penerusan di SERVICE_PROJECT_ID dan rujuk jaringan VPC Bersama di HOST_PROJECT_ID dan alamat di 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

Pastikan layanan Apigee menerima koneksi:

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

Status harus ACCEPTED sebelum endpoint dapat meneruskan traffic. Untuk mengetahui informasi selengkapnya tentang endpoint Private Service Connect, lihat Tentang mengakses layanan yang dipublikasikan melalui endpoint.

Menambahkan data DNS untuk nama host

Di zona pribadi, buat data A yang me-resolve APIGEE_HOSTNAME ke PSC_ENDPOINT_IP. Data ini hanya dapat dilihat di dalam VPC_NAME, sehingga klien eksternal akan terus me-resolve nama host melalui DNS publik.

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

Langkah 2: Konfigurasi Apigee

Menambahkan project layanan ke daftar penerimaan konsumen instance

Instance Apigee hanya menerima koneksi Private Service Connect dari project konsumen yang tercantum dalam consumerAcceptList-nya. Sisi konsumen koneksi dikaitkan dengan SERVICE_PROJECT_ID, karena project tersebut adalah tempat agen di-deploy.

Secara default, project yang terkait dengan organisasi Apigee (APIGEE_PROJECT_ID) sudah ada dalam daftar. Jika SERVICE_PROJECT_ID sama dengan APIGEE_PROJECT_ID, tidak ada perubahan yang diperlukan dan Anda dapat melewati bagian ini. Jika tidak, tambahkan SERVICE_PROJECT_ID ke daftar.

Pertama, periksa nilai consumerAcceptList saat ini menggunakan metode 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"

Cari kolom consumerAcceptList dalam respons.

Kemudian, perbarui daftar dengan memanggil metode organizations.instances.patch dengan mask update pada consumerAcceptList. Karena kolom menggantikan daftar yang ada, sertakan setiap project ID yang harus mempertahankan akses, termasuk APIGEE_PROJECT_ID dan project layanan tambahan yang men-deploy agen:

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"

Konfirmasi update dengan menjalankan kembali perintah get dan memverifikasi bahwa SERVICE_PROJECT_ID kini disertakan dalam consumerAcceptList.

Alternatif: Anda juga dapat menambahkan atau menghapus project yang diterima menggunakan konsol Google Cloud . Lihat Mengedit daftar project yang diterima di Mengelola instance.

Memverifikasi nama host grup lingkungan

Pastikan APIGEE_HOSTNAME tercantum di grup lingkungan yang menghosting proxy API Anda. Jika tidak ada, tambahkan.

Untuk mengetahui petunjuknya, lihat Bekerja dengan grup lingkungan.

Langkah 3: Deploy agen Anda dengan peering DNS dan antarmuka PSC

Saat men-deploy agen ke Agent Runtime, konfigurasikan dengan antarmuka PSC yang mereferensikan lampiran jaringan yang Anda buat, dan konfigurasikan peering DNS ke zona pribadi Anda. Untuk prosedur penyebaran lengkap dan framework yang didukung, lihat Menggunakan antarmuka Private Service Connect dengan Agent Runtime dan Men-deploy agen dalam dokumentasi Agent Platform.

Konfigurasi dua kolom berikut pada konfigurasi antarmuka PSC agen (lihat referensi PscInterfaceConfig):

• networkAttachment: tetapkan ini ke nama resource lengkap network attachment yang Anda buat di Langkah 1, dalam bentuk projects/SERVICE_PROJECT_ID/regions/REGION/networkAttachments/agent-network-attachment. Jika Anda membuat lampiran jaringan di project host, gunakan HOST_PROJECT_ID di jalur ini.
• dnsPeeringConfigs: tambahkan satu entri dengan kolom berikut, sehingga Agent Runtime menyelesaikan APIGEE_HOSTNAME melalui zona pribadi Anda:
  • domain: PARENT_DNS_NAME. Nilai harus diakhiri dengan titik.
  • targetProject: HOST_PROJECT_ID. Project ini adalah project yang berisi VPC konsumen dan zona pribadi.
  • targetNetwork: VPC_NAME.

Agen Layanan Agent Platform untuk SERVICE_PROJECT_ID ([e-mail]) harus memiliki izin untuk mengonfigurasi peering DNS dan memperbarui lampiran jaringan. Berikan peran yang diperlukan seperti yang dijelaskan dalam Peran yang diperlukan untuk agen layanan Agent Platform. Dalam deployment VPC Bersama, peran tambahan berlaku di project host; lihat Menggunakan antarmuka Private Service Connect dengan VPC Bersama.

Dari kode agen, panggil proxy API di https://APIGEE_HOSTNAME/BASE_PATH. Di dalam lingkungan Agent Runtime, nama host ini di-resolve melalui peering DNS ke PSC_ENDPOINT_IP, dan permintaan melintasi endpoint Private Service Connect ke VPC Anda dan ke Apigee.

Catatan: Karena instance Apigee menampilkan sertifikat yang ditandatangani sendiri di jalur pribadi, klien HTTP agen Anda harus menerima sertifikat yang ditandatangani sendiri atau menggunakan konfigurasi yang menempatkan Load Balancer Aplikasi internal dengan sertifikat TLS terkelola di depan lampiran layanan. Lihat Jaringan ke utara dengan Private Service Connect untuk varian yang di-load balance.

Memverifikasi jalur pribadi

Setelah men-deploy agen, verifikasi bahwa permintaan mencapai Apigee melalui jalur pribadi:

• Pastikan status aturan penerusan adalah ACCEPTED, menggunakan perintah di Buat endpoint Private Service Connect.
• Dari VM Compute Engine yang terhubung ke VPC_NAME di REGION (dalam deployment VPC Bersama, VM ini dapat berada di project host atau project layanan yang terhubung ke VPC Bersama), jalankan dig +short APIGEE_HOSTNAME. Hasilnya harus PSC_ENDPOINT_IP. Hal ini mengonfirmasi bahwa zona pribadi menyelesaikan nama host dengan benar di dalam VPC.
• Dari VM yang sama, kirim permintaan ke proxy API yang di-deploy di https://APIGEE_HOSTNAME/BASE_PATH dan konfirmasi bahwa Anda menerima respons yang diharapkan.
• Panggil agen yang di-deploy dan konfirmasi bahwa permintaan telah ditayangkan. Kemudian gunakan Apigee Analytics atau Debug untuk mengonfirmasi bahwa permintaan tiba di proxy API yang diharapkan di nama host grup lingkungan.

Langkah berikutnya

• Pelajari lebih lanjut Penggunaan antarmuka Private Service Connect dengan Agent Runtime.
• Pelajari cara Men-deploy agen di Agent Runtime.
• Baca tentang Jaringan ke utara dengan Private Service Connect, varian berbasis load balancer yang menggunakan sertifikat TLS terkelola.
• Baca Pola jaringan ke hilir, yang menjelaskan cara Apigee terhubung secara pribadi ke target backend Anda.
• Pelajari MCP di Apigee untuk mengekspos API Anda sebagai alat MCP ke aplikasi berbasis agen.