Kebijakan yang dapat diperluas di Agent Gateway

Seiring agen berkembang dari prototipe awal ke deployment perusahaan, kebutuhan untuk mengintegrasikan kontrol internal, pipeline data eksklusif, dan kebijakan keamanan perusahaan meningkat pesat. Terkadang, keputusan otorisasi yang kompleks tidak dapat dinyatakan dengan mudah hanya menggunakan kebijakan IAM standar.

Untuk memenuhi persyaratan ini, Agent Gateway memperkenalkan framework kebijakan baru yang memungkinkan Anda mendukung penegakan kebijakan dengan layanan Google, mesin otorisasi kustom, atau platform keamanan pihak ketiga, dengan menerapkan kebijakan yang sama secara universal di seluruh gateway Anda. Dokumen ini menguraikan kasus penggunaan risiko agentic utama dan menjelaskan cara mengonfigurasi kebijakan yang dapat diperluas.

Kasus penggunaan ekstensibilitas kebijakan untuk risiko agentic

Kontrol deterministik standar sering kali tidak memadai untuk workload AI probabilistik. Pipeline layanan yang dapat diperluas membantu organisasi memasukkan logika lanjutan yang disesuaikan dengan risiko agentic yang unik:

• Sanitasi Konten & Guardrail Keamanan: Perlindungan terhadap prompt injection, jailbreak, output beracun, dan hilangnya informasi rahasia (misalnya, menggunakan Model Armor).
• Pencegahan Kebocoran Data (DLP): Pemantauan payload dan potongan streaming secara real-time untuk mencegah kebocoran data kode eksklusif atau PII ke sistem eksternal.
• Tata Kelola Identitas Zero-Trust: Memvalidasi kredensial dan menerapkan kontrol akses sebelum agen diizinkan mengakses backend sensitif atau alat eksternal (misalnya, menggunakan IAP).
• Kepatuhan Perusahaan yang Disesuaikan: Menerapkan aturan penghapusan data kustom, penerjemahan token, atau mekanisme kepatuhan khusus untuk arsitektur internal.

Framework untuk ekstensibilitas kebijakan di Agent Gateway

Agent Gateway memungkinkan Anda melampirkan binding ekstensi untuk mendelegasikan keputusan otorisasi ke Policy Engine khusus, seperti penyedia identitas, filter keamanan konten, atau platform keamanan pihak ketiga kustom.

Framework ekstensibilitas kebijakan beroperasi pada pemisahan antara peran dan resource:

• Konsumen: Operator Agent Gateway yang ingin menambahkan ekstensi keamanan dan tata kelola ke gateway mereka dengan upaya konfigurasi minimal.

• Produsen: Tim platform internal, layanan Google pihak pertama (seperti IAP dan Model Armor), serta partner ISV pihak ketiga yang membangun dan memublikasikan ekstensi layanan untuk digunakan oleh orang lain.

• ExtensionBinding: Resource yang dibuat oleh konsumen yang mengikat ProducerExtension ke Agent Gateway target, beserta kondisi pencocokan yang menentukan kapan ekstensi dipanggil. Ini adalah satu-satunya resource yang perlu dibuat konsumen untuk mulai menggunakan ekstensi.

• ProducerExtension: Resource yang dibuat oleh produsen yang mengemas mesin otorisasi yang kompatibel dengan ext_proc ke dalam satu unit terkelola. Layanan ini merangkum semua parameter eksekusi dan setelan konektivitas yang mendasarinya, sehingga konsumen tidak perlu mengonfigurasi mekanisme bidang data tingkat rendah.

Ekstensi Google pihak pertama bawaan

Layanan Google pihak pertama (1P), seperti IAP dan Model Armor, menawarkan kemampuan ekstensi yang telah dipaketkan sebelumnya dengan model operasional yang disederhanakan.

• Konsumen: Developer aplikasi dan operator keamanan bertindak sebagai konsumen. Untuk mengaktifkan autentikasi zero-trust atau perlindungan injeksi perintah, buat resource ExtensionBinding yang menargetkan URI endpoint layanan yang telah ditetapkan Google langsung dari project konsumen Anda.
• Produsen: Google bertindak sebagai produsen. Google membangun, menghosting, dan mengelola Service Infrastructure dan endpoint ekstensi yang mendasarinya secara global (seperti iap.googleapis.com atau modelarmor.us.rep.googleapis.com). Anda tidak perlu membuat atau mengelola resource ProducerExtension.

Ekstensi perusahaan dan partner (2P/3P)

Untuk logika tata kelola kustom, ekstensibilitas kebijakan memungkinkan model integrasi dua sisi yang fleksibel di seluruh tim perusahaan dan partner keamanan.

• Produsen: Tim engineering platform internal (2P) atau vendor keamanan ISV pihak ketiga (3P) bertindak sebagai produsen. Produsen membangun layanan gRPC yang kompatibel dengan protokol ext_proc Envoy, menghostingnya dalam project produsen khusus (seperti layanan Cloud Run di balik Load Balancer Aplikasi), mengeksposnya menggunakan Lampiran Layanan Private Service Connect (PSC), dan memublikasikan resource ProducerExtension.

• Konsumen: Developer aplikasi dan administrator keamanan di seluruh project konsumen bertindak sebagai konsumen. Setelah diberi akses menggunakan PSC oleh produsen, konsumen membuat ExtensionBinding di project mereka yang merujuk ke URI resource ProducerExtension tertentu untuk menerapkan kontrol kustom (seperti Kebijakan Tata Kelola Semantik atau aturan firewall pihak ketiga) pada workload mereka.

Pola deployment

Binding Ekstensi mendukung pola deployment yang fleksibel untuk menerapkan tata kelola yang konsisten di semua jalur traffic guna memastikan bahwa kebijakan tata kelola Anda bertindak secara identik, di mana pun agen Anda di-deploy. ExtensionBinding API berlaku secara seragam di semua model deployment Gateway Agen.

Jalur intersepsi traffic menyeluruh

Anda dapat menerapkan Binding Ekstensi untuk mengintersepsi traffic di seluruh jalur komunikasi berikut dalam ekosistem agen Anda:

• Pengguna → Agen (Ingress): Menghalangi permintaan masuk dari pengguna akhir atau aplikasi klien yang menargetkan Agent Gateway untuk menerapkan autentikasi pengguna, tata kelola identitas, atau pembersihan injeksi perintah.
• Agen → Alat / MCP (Egress): Mengintersepsi panggilan keluar dari agen ke server Model Context Protocol (MCP) atau API eksternal untuk memvalidasi izin dan membersihkan input alat.
• Agen → Model LLM (Egress): Memindai perintah sebelum mencapai model dasar dan memfilter respons model untuk mencegah kebocoran data atau output berbahaya.

• Agen → Agen (Egress A2A): Mengontrol komunikasi antar-agen dan menerapkan batasan kebijakan saat agen otonom berkolaborasi di berbagai project.

Klien ke Agen

Agent-to-Anywhere

Konsumen: Mengikat ekstensi ke Agent Gateway

Konsumen (seperti developer aplikasi atau operator keamanan) melampirkan logika tata kelola dan keamanan ke Agent Gateway mereka dengan membuat ExtensionBinding. Resource ini mengikat workload target ke ekstensi dan mendeklarasikan kondisi kecocokan untuk menentukan dengan tepat kapan ekstensi harus dipanggil (misalnya, mencegat traffic yang terikat ke alat eksternal atau server MCP tertentu). Anda dapat menentukan kondisi pencocokan secara langsung (seperti yang ditunjukkan dalam contoh di bagian ini) atau dalam file YAML terpisah.

Bergantung pada penyedia ekstensi, konsumsi mengikuti salah satu dari dua jalur:

Konfigurasi Konsumen Pihak Pertama

Untuk layanan Google seperti IAP (IAP) atau Model Armor, Google mengelola infrastruktur backend dan pendaftaran secara global. Sebagai konsumen, Anda tidak perlu menargetkan URI resource ProducerExtension tertentu. Anda dapat langsung mengikat layanan ini ke workload Anda dengan meneruskan string endpoint yang telah ditetapkan (misalnya, iap.googleapis.com atau modelarmor.us.rep.googleapis.com) sebagai target di ExtensionBinding Anda.

Mengikat ekstensi IAP ke Agent Gateway

Contoh berikut menunjukkan resource ExtensionBinding yang mengikat layanan Google pihak pertama (IAP) ke Agent Gateway dalam project konsumen. Berdasarkan kolom matchConditions yang ditentukan, ekstensi ini dipanggil saat traffic dikirim ke server MCP.

1. Buat file YAML dengan konfigurasi berikut:

   name: EXTENSION_BINDING_NAME
   target:
     resources:
     - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
   matchConditions:
   - to:
       destination:
         resources:
         - prefix: "urn:mcp"
   producerExtension: "iap.googleapis.com"
   

   Ganti kode berikut:

   • EXTENSION_BINDING_NAME: nama resource binding ekstensi.
   • PROJECT_ID: Project ID Cloud de Confiance by S3NS Anda.
   • LOCATION: lokasi gateway dan binding ekstensi.
   • AGENT_GATEWAY_NAME: nama Agent Gateway target.

2. Impor konfigurasi binding ekstensi:

   gcloud beta service-extensions extension-bindings import EXTENSION_BINDING_NAME \
    --location=LOCATION \
    --source=EXTENSION_BINDING_FILE_PATH

   Ganti EXTENSION_BINDING_FILE_PATH dengan jalur ke file konfigurasi YAML.

Mengikat ekstensi Model Armor ke Agent Gateway

Untuk melindungi agen Anda dari injeksi perintah, konten beracun, dan kebocoran data sensitif, Anda dapat mengikat Model Armor langsung ke workload Anda. Berdasarkan kolom matchConditions yang ditentukan, ekstensi ini dipanggil saat traffic dikirim ke server MCP.

1. Buat file YAML dengan konfigurasi berikut:

   name: EXTENSION_BINDING_NAME
   target:
     resources:
     - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
   matchConditions:
   - to:
       destination:
         resources:
         - prefix: "urn:mcp"
   producerExtension: "modelarmor.us.rep.googleapis.com"
   failOpen: true
   producerMetadata:
     model_armor_settings: '[{
       "request_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
       "response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
     }]'
   

   Ganti kode berikut:

   • EXTENSION_BINDING_NAME: nama resource binding ekstensi.
   • PROJECT_ID: Project ID Cloud de Confiance Anda.
   • LOCATION: lokasi resource.
   • AGENT_GATEWAY_NAME: nama Agent Gateway target.
   • TEMPLATE_PROJECT_ID: project ID tempat template Model Armor Anda berada.
   • REQUEST_TEMPLATE_ID: ID template Model Armor yang digunakan untuk mengevaluasi permintaan.
   • RESPONSE_TEMPLATE_ID: ID template Model Armor yang digunakan untuk mengevaluasi respons.

2. Impor konfigurasi binding ekstensi:

   gcloud beta service-extensions extension-bindings import EXTENSION_BINDING_NAME \
    --location=LOCATION \
    --source=EXTENSION_BINDING_FILE_PATH

   Ganti EXTENSION_BINDING_FILE_PATH dengan jalur ke file konfigurasi YAML.

Konfigurasi Konsumen 2P/3P

Sebagai konsumen ekstensi layanan yang dibuat oleh tim internal lain (2P) atau vendor pihak ketiga eksternal (3P), tanggung jawab Anda adalah memastikan bahwa project konsumen Anda telah diberi akses secara eksplisit untuk menggunakan layanan tersebut. Akses dikontrol oleh produsen menggunakan konfigurasi Lampiran Layanan Private Service Connect mereka. Setelah Anda diberi akses, ikat workload dengan mereferensikan URI resource ProducerExtension tertentu yang disediakan oleh produsen di ExtensionBinding Anda.

Mengikat mesin otorisasi kustom

Contoh berikut menunjukkan resource ExtensionBinding yang mengikat ekstensi kustom dari project produsen 2P/3P ke Agent Gateway di project konsumen. Berdasarkan kolom matchConditions yang ditentukan, ekstensi ini dipanggil saat traffic dikirim ke agen.

1. Buat file YAML dengan konfigurasi berikut:

   name: EXTENSION_BINDING_NAME
   target:
     resources:
     - "projects/CONSUMER_PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
   matchConditions:
   - to:
       destination:
         resources:
         - prefix: "urn:agent"
   producerExtension: "projects/PRODUCER_PROJECT_ID/locations/LOCATION/producerExtensions/PRODUCER_EXTENSION_NAME"
   

   Ganti kode berikut:

   • EXTENSION_BINDING_NAME: nama resource binding ekstensi.
   • CONSUMER_PROJECT_ID: project ID dari project konsumen yang menghosting Gateway Agen.
   • LOCATION: lokasi resource.
   • AGENT_GATEWAY_NAME: nama Agent Gateway target.
   • PRODUCER_PROJECT_ID: project ID dari project produsen yang menghosting ProducerExtension.
   • PRODUCER_EXTENSION_NAME: nama resource ProducerExtension.

2. Impor konfigurasi binding ekstensi:

   gcloud beta service-extensions extension-bindings import EXTENSION_BINDING_NAME \
    --location=LOCATION \
    --source=EXTENSION_BINDING_FILE_PATH

   Ganti EXTENSION_BINDING_FILE_PATH dengan jalur ke file konfigurasi YAML.

Titik lampiran binding ekstensi

Binding ekstensi dapat dikonfigurasi di berbagai tingkat hierarki resource, bergantung pada persyaratan tata kelola Anda:

• Level Agent Gateway: Lampirkan kebijakan langsung ke resource Agent Gateway untuk mengatur semua traffic yang melewati gateway.
• Tingkat project: Buat ExtensionBindings yang berlaku secara global untuk semua resource dari jenis tertentu dalam sebuah project, sehingga menyederhanakan pengelolaan bagi administrator perusahaan yang menerapkan kepatuhan di seluruh project.

Mengikat ekstensi Model Armor ke semua Agent Gateway dalam project

1. Buat file YAML dengan konfigurasi berikut:

   name: EXTENSION_BINDING_NAME
   target:
     scope:
       parent: "projects/PROJECT_NUMBER"
       resourceTypes: "AGENT_GATEWAY"
   matchConditions:
   - to:
       destination:
         resources:
         - prefix: "urn:mcp"
   producerExtension: "modelarmor.us.rep.googleapis.com"
   failOpen: true
   producerMetadata:
     model_armor_settings: '[{
       "request_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
       "response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
     }]'
   

   Ganti kode berikut:

   • EXTENSION_BINDING_NAME: nama resource binding ekstensi.
   • PROJECT_NUMBER: nomor project dari project Cloud de Confiance Anda.
   • TEMPLATE_PROJECT_ID: project ID tempat template Model Armor Anda berada.
   • LOCATION: lokasi resource.
   • REQUEST_TEMPLATE_ID: ID template Model Armor yang digunakan untuk mengevaluasi permintaan.
   • RESPONSE_TEMPLATE_ID: ID template Model Armor yang digunakan untuk mengevaluasi respons.

2. Impor konfigurasi binding ekstensi:

   gcloud beta service-extensions extension-bindings import EXTENSION_BINDING_NAME \
    --location=LOCATION \
    --source=EXTENSION_BINDING_FILE_PATH

   Ganti EXTENSION_BINDING_FILE_PATH dengan jalur ke file konfigurasi YAML.

Untuk permintaan yang cocok dengan workload tertentu, binding ekstensi level project dan level resource akan dijalankan. Jika ekstensi yang sama dikonfigurasi di tingkat resource dan tingkat project, ekstensi tersebut akan dipanggil dua kali.

Kondisi pencocokan untuk memanggil ekstensi

Kondisi pencocokan menentukan kapan ekstensi Anda dipanggil. Anda dapat menentukan kondisi pencocokan secara langsung (seperti yang ditunjukkan dalam contoh sebelumnya di halaman ini) atau dalam file YAML.

Bagian ini memberikan contoh konfigurasi file YAML untuk situasi umum berdasarkan aliran traffic, URN resource target, atau host tujuan:

• Egress ke server alat MCP (Agen → Alat): Memblokir traffic yang dikirim dari agen ke server alat Model Context Protocol (MCP) jarak jauh:

  # Invoke extension for all agent traffic to remote MCP servers
  - to:
      destination:
        resources:
        - prefix: "urn:mcp"
  

• Traffic masuk (Pengguna → Agen): Mengintersepsi permintaan masuk dari pengguna akhir atau aplikasi klien yang menargetkan agen yang diatur oleh Agent Gateway (misalnya, untuk menerapkan autentikasi pengguna akhir atau sanitasi injeksi perintah pada traffic masuk):

  # Invoke extension on incoming user requests targeting agents
  - to:
      destination:
        resources:
        - prefix: "urn:agent"
  

• Egress ke model LLM (Agen → Model LLM): Mengintersepsi permintaan yang dikirim dari agen ke model LLM dasar atau server model dengan mencocokkan host tujuan:

  # Invoke extension on traffic sent to a specific model server
  - to:
      destination:
        hosts:
        - exact: "myexamplemodelserver.com"
  

Produsen: Membangun dan memublikasikan ekstensi

Sebagai produsen kustom (pihak kedua atau ketiga), hosting implementasi ekstensi layanan berbasis ext_proc Anda di balik Lampiran Private Service Connect. Setelah lampiran siap, buat resource ProducerExtension yang menentukan fase pemrosesan permintaan tempat ekstensi Anda beroperasi, otoritas yang akan digunakan, dan URI ke lampiran PSC untuk layanan ext_proc Anda:

gcloud beta service-extensions producer-extensions create PRODUCER_EXTENSION_NAME \
  --phase authz \
  --extension-settings=service=projects/PRODUCER_PROJECT_ID/regions/REGION/serviceAttachments/PSC_ATTACHMENT_NAME,authority="example.provider.net"

Ganti kode berikut:

• PRODUCER_EXTENSION_NAME: nama resource ProducerExtension.
• PRODUCER_PROJECT_ID: project ID dari project produsen.
• REGION: region Lampiran Layanan Private Service Connect.
• PSC_ATTACHMENT_NAME: nama Lampiran Layanan Private Service Connect.

Menghosting ekstensi kustom di Cloud Run

Bagi produsen yang ingin menjalankan layanan gRPC ext_proc kustom tanpa mengelola cluster atau VM khusus, Cloud Run adalah alternatif serverless yang ideal.

Untuk memublikasikan ekstensi serverless sebagai ProducerExtension, ekspos ekstensi tersebut menggunakan Private Service Connect (PSC). Karena resource ProducerExtension memerlukan URI Lampiran Layanan PSC, dan Lampiran Layanan menargetkan aturan penerusan load balancer, bukan layanan Cloud Run secara langsung, tempatkan Load Balancer Aplikasi (menggunakan backend NEG Serverless) di depan layanan Cloud Run Anda.

Berikut adalah alur kerja deployment tingkat tinggi untuk menghosting ekstensi Anda di Cloud Run:

1. Deploy ekstensi Anda di Cloud Run: Hosting ekstensi gRPC ext_proc kustom Anda sebagai layanan dalam container di Cloud Run.

2. Membuat NEG Serverless: Deploy Grup Endpoint Jaringan (NEG) Serverless yang mengarah ke ekstensi yang berjalan di Cloud Run.

3. Siapkan Load Balancer dengan backend NEG Serverless: Siapkan Load Balancer Aplikasi regional di dalam jaringan VPC Anda, dengan NEG Serverless sebagai backend-nya.

4. Publikasikan Layanan Anda dengan PSC: Buat Lampiran Layanan Private Service Connect yang mengarah langsung ke aturan penerusan load balancer. Tindakan ini akan menghasilkan URI Lampiran Layanan yang unik (misalnya, projects/.../regions/.../serviceAttachments/...).

5. Membuat Ekstensi Produsen: Gunakan URI yang dihasilkan ini untuk membuat instance resource ProducerExtension Anda.

6. Mengikat workload konsumen: Konsumen kini dapat mengikat gateway mereka ke ekstensi Anda dengan mereferensikan URI resource ProducerExtension.

Lampiran: Metadata kontekstual untuk ekstensi kustom

Untuk membantu ekstensi kustom Anda membuat keputusan otorisasi dan pemrosesan yang peka konteks,bidang data Cloud de Confiance meneruskan konteks siklus proses dan resource langsung ke server ext_proc.

Informasi ini digabungkan sebagai metadata tanpa jenis dalam kolom metadata_context dari ProcessingRequest gRPC ext_proc. Metadata ini berada di bawah namespace com.google.serviceextensions.invocation_info dan menggunakan format google.protobuf.Struct standar.

Anda dapat mendekode atau mengonversi metadata ini menjadi JSON untuk pemrosesan downstream. Contoh format JSON untuk permintaan yang menargetkan Agent Gateway dengan traffic yang terikat ke server MCP diuraikan sebagai berikut:

{
 "binding_selector" : {
   "target" : "//networkservices.googleapis.com/projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME",
   "project_number" : PROJECT_NUMBER,
   "to_resource": "urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID"
 }
}

Skema JSON adalah sebagai berikut:

message ServiceExtensionsInvocationInfo {
  message ExtensionBindingSelector {
    // The target (gateway ID, etc) in fully qualified name format.
    // For example:
    // "//networkservices.googleapis.com/projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
    string target = 1;
    // Project number associated with the target.
    uint64 project_number = 2;
    // The destination resource within the Agent Registry that traffic is directed to.
    string to_resource = 3;
  }
  ExtensionBindingSelector binding_selector = 1;
}