Mengonfigurasi Model Armor di gateway

Model Armor membantu Anda memastikan bahwa agen AI Anda mematuhi standar keamanan dan tata kelola Anda tanpa mengharuskan Anda menerapkan logika pemfilteran secara langsung dalam agen. Saat Anda mengonfigurasi Model Armor dengan Agent Gateway, Model Armor menerapkan batasan pengamanan keamanan konten organisasi Anda dengan memeriksa semua perintah dan respons yang melewati gateway. Dengan fitur ini, Anda dapat menerapkan batasan keamanan konten secara konsisten di semua agen yang dikelola oleh gateway. Model Armor membantu Anda memitigasi risiko seperti injeksi perintah, upaya jailbreak, kebocoran informasi sensitif, dan pembuatan konten berbahaya. Untuk mengetahui informasi selengkapnya, lihat Filter Model Armor.

Template Model Armor

Untuk mengonfigurasi Model Armor di gateway, buat template yang menentukan cara menyaring perintah dan respons yang diterima dan dikembalikan oleh agen AI Anda. Template menyediakan filter dan batasan yang disesuaikan untuk berbagai kategori keselamatan dan keamanan. Untuk mengetahui informasi selengkapnya, lihat Template Model Armor.

Model Armor menyematkan kemampuan penapisan langsung ke jalur komunikasi yang diatur oleh Agent Gateway. Dengan meneruskan konten melalui Model Armor, gateway akan menerapkan template keamanan konten Anda. Dalam template, Anda dapat mengonfigurasi Model Armor untuk menyamarkan atau memblokir konten yang melanggar template Anda.

Traffic masuk dan keluar

Melalui Agent Gateway, Model Armor dapat membantu melindungi alur traffic berikut.

Klien ke Agen (ingress agen)

Anda menentukan template yang digunakan Model Armor untuk mengevaluasi permintaan dan respons dalam traffic Client-to-Agent. Anda dapat menerapkan satu template ke kedua arah atau mengonfigurasi template yang berbeda untuk setiap arah.

Model Armor mengikuti template saat menyaring hal berikut:

  • Permintaan masuk dari klien (pengguna akhir atau aplikasi yang memanggil) ke agen AI Anda
  • Respons keluar dari agen AI kembali ke klien

Saat klien mengirimkan perintah ke agen, Agent Gateway akan mencegat traffic dan mengirimkan payload ke Model Armor untuk pembersihan. Jika Model Armor mengeluarkan putusan ALLOW, Agent Gateway akan mengirimkan perintah ke agen AI. Jika Model Armor mengeluarkan putusan BLOCK, klien akan menerima error, dan alur akan berakhir sebelum mencapai agen AI.

Setelah agen AI memproses permintaan dan menghasilkan respons, Agent Gateway akan mencegat aliran keluar sebelum mencapai klien. Model Armor mengevaluasi respons dan mengeluarkan putusan. Berdasarkan putusan, Agent Gateway mengizinkan atau memblokir sepenuhnya respons.

Agent-to-Anywhere (keluar dari agen)

Anda menentukan template yang digunakan Model Armor untuk mengevaluasi permintaan dan respons dalam traffic Agent-to-Anywhere. Anda dapat menerapkan satu template ke kedua arah atau mengonfigurasi template yang berbeda untuk setiap arah.

Model Armor mengikuti template saat menyaring komunikasi antara agen AI dan sistem eksternal Anda, termasuk yang berikut:

  • Model bahasa besar (LLM) eksternal
  • Agen AI pihak ketiga
  • Server Model Context Protocol (MCP)

Saat agen AI berkomunikasi dengan sistem eksternal, Agent Gateway akan mencegat traffic keluar dan memanggil Model Armor. Model Armor mengevaluasi payload sesuai dengan template keluar yang Anda tetapkan.

Jika data keluar melanggar kebijakan keamanan Anda, Model Armor akan mengeluarkan putusan BLOCK. Kemudian, Agent Gateway menghentikan koneksi untuk mencegah data berbahaya atau sensitif mencapai LLM, alat, atau agen AI eksternal.

Sebelum memulai

Aktifkan Model Armor API, jika belum diaktifkan.

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

Mengaktifkan API

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna membuat template Model Armor, minta administrator Anda untuk memberi Anda peran IAM Model Armor Admin (roles/modelarmor.admin) di project tersebut. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

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

Untuk mengetahui peran yang diperlukan untuk menggunakan Agent Gateway, lihat Peran yang diperlukan dalam dokumentasi Agent Gateway.

Untuk mengetahui informasi tentang payload yang didukung dan tidak didukung yang melewati gateway, lihat Payload yang didukung dan tidak didukung dalam dokumen ini.

Mengonfigurasi Model Armor di gateway

Untuk mengonfigurasi Model Armor di gateway, ikuti langkah-langkah berikut:

  1. Aktifkan Model Armor API di project tempat Anda ingin membuat template Model Armor.

  2. Buat satu atau beberapa template Model Armordi region yang sama dengan tempat Anda berencana menambahkan gateway. Anda dapat menggunakan template yang sama untuk traffic masuk dan keluar.

    Catat nama template. Untuk menyalin nama template di konsolCloud de Confiance , lihat detail template dan klik Salin ke papan klip di samping nama template.

  3. Siapkan Agent Gateway di region yang sama dengan tempat template Model Armor disimpan. Untuk gateway Client-to-Agent (ingress), tentukan template Model Armor yang Anda buat untuk traffic masuk. Untuk gateway Agent-to-Anywhere (egress), tentukan template Model Armor yang Anda buat untuk traffic egress. Anda dapat menggunakan template yang sama untuk kedua alur traffic.

  4. Berikan peran IAM yang diperlukan ke agen layanan yang sesuai:

    • Client-to-Agent (ingress): Berikan peran berikut kepada agen layanan AI Platform Reasoning Engine Service Agent:

      • Peran Pengguna Pemberitahuan Model Armor (roles/modelarmor.calloutUser) di project yang berisi agen AI.

      • Peran Pengguna Model Armor (roles/modelarmor.user) di project yang berisi template Model Armor.

      gcloud projects add-iam-policy-binding AGENT_RUNTIME_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

      Ganti kode berikut:

      • AGENT_RUNTIME_PROJECT_ID: Project ID dari project tempat Anda membuat agen.
      • AGENT_RUNTIME_PROJECT_NUMBER: Nomor project tempat Anda membuat agen.
      • MODEL_ARMOR_PROJECT_ID: Project ID dari project yang berisi template Model Armor.

    • Agent-to-Anywhere (egress): Berikan peran berikut kepada agen layanan Service Extensions:

      • Peran Model Armor Callout User (roles/modelarmor.calloutUser) dan Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) di project yang berisi gateway.
      • Peran Pengguna Model Armor (roles/modelarmor.user) dalam project yang berisi template Model Armor.
      gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.s3ns-system.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.s3ns-system.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.s3ns-system.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

      Ganti kode berikut:

      • GATEWAY_PROJECT_ID: Project ID dari project tempat Anda membuat gateway.
      • GATEWAY_PROJECT_NUMBER: Nomor project dari project tempat Anda membuat gateway.
      • MODEL_ARMOR_PROJECT_ID: Project ID dari project yang berisi template Model Armor.

      Untuk mengetahui petunjuknya, lihat Mendelegasikan otorisasi ke Model Armor.

    Untuk mengetahui informasi umum tentang cara memberikan peran, lihat Memberikan satu peran IAM.

Opsional: Pemeriksaan validasi template pra-deployment

Sebelum men-deploy template ke gateway, Anda dapat menjalankan pemeriksaan pra-deployment untuk memverifikasi bahwa konfigurasi template Anda menerapkan kebijakan keamanan dengan benar.

Anda dapat memvalidasi template dengan membuat kueri metode sanitizeUserPrompt secara langsung menggunakan serangkaian perintah pengujian. Untuk mengetahui informasi selengkapnya tentang cara menjalankan pemeriksaan pra-deployment ini dan daftar perintah pengujian yang terverifikasi, lihat Memvalidasi konfigurasi template Anda.

Menyamarkan data sensitif dari permintaan dan respons

Anda dapat menginstruksikan Model Armor untuk menyamarkan data sensitif—seperti nomor ID nasional dan nomor telepon—dari payload. Untuk menggunakan fitur ini, ikuti langkah-langkah berikut:

Jika Anda menggunakan jenis penegakan INSPECT_AND_BLOCK, salah satu hal berikut akan terjadi:

  • Jika payload hanya melanggar detektor Sensitive Data Protection, Model Armor akan menyamarkan payload sesuai dengan setelan Sensitive Data Protection tingkat lanjut dan template de-identifikasi Anda.

  • Jika payload melanggar beberapa detektor, Model Armor tidak akan melakukan penyensoran; Model Armor akan memblokir seluruh payload.

Jika Anda menggunakan jenis penegakan INSPECT_ONLY, bukan INSPECT_AND_BLOCK, Model Armor tidak menyamarkan payload.

Terlepas dari jenis penegakan Anda (INSPECT_ONLY atau INSPECT_AND_BLOCK), log Model Armor disamarkan sesuai dengan setelan Sensitive Data Protection lanjutan dan template de-identifikasi Anda.

Untuk mengetahui daftar lengkap detektor Model Armor (juga disebut filter), lihat Filter Model Armor.

Payload yang didukung dan tidak didukung

Bagian ini mencantumkan jenis payload yang dibersihkan oleh Model Armor.

Traffic Client-to-Agent (ingress)

Untuk traffic Client-to-Agent (ingress) menggunakan protokol ADK, Model Armor hanya membersihkan reasoningEngines.streamQuery permintaan dan respons untuk agen yang dibangun menggunakan Agent Development Kit (ADK) dan berjalan di Vertex AI Agent Engine.

Semua payload ReasoningEngine lainnya dan respons error ReasoningEngine tidak dikirim ke Model Armor. Payload non-ADK (seperti payload Langchain) juga tidak dikirim ke Model Armor.

Traffic Agent-to-Anywhere (keluar)

Untuk traffic Agent-to-Anywhere (keluar), payload berikut didukung.

Payload A2A

Model Armor hanya membersihkan payload berikut dari protokol A2A v1:

Model Armor mengizinkan payload A2A berikut tanpa pembersihan:

Payload MCP

Model Armor hanya membersihkan payload MCP berikut:

  • Permintaan dan respons tools/call
  • Permintaan dan respons prompts/get
  • Error eksekusi alat MCP (target untuk injeksi perintah oleh penulis alat MCP berbahaya)

Model Armor mengizinkan payload berikut tanpa pembersihan:

  • tools/list
  • resources/*
  • notifications/*
  • HTTP/SSE yang dapat di-stream untuk MCP
  • Error protokol MCP (misalnya, semua error selain error eksekusi alat)

Payload LLM eksternal

Model Armor hanya membersihkan payload berikut dari protokol OpenAI API (keluar), yang mencakup model GPT di openai.com serta model lainnya melalui server LLM yang kompatibel dengan OpenAI API (seperti vLLM). Payload yang tidak tercantum di sini diizinkan tanpa pembersihan.

Pemeriksaan dokumen

Pembersihan perintah dan respons yang berisi dokumen atau upload file (seperti PDF) tidak didukung dalam integrasi ini. Untuk menyaring dokumen, panggil Model Armor REST API secara langsung. Untuk mengetahui informasi selengkapnya, lihat Penyaringan dokumen di dokumentasi Model Armor.

Kuota dan batas sistem

Kuota digunakan dalam project tempat template Model Armor berada. Jika gateway berada di project lain, kuota ExternalProcessor juga akan digunakan di project gateway.

Untuk mengetahui informasi selengkapnya tentang kuota yang berlaku saat Anda menggunakan Model Armor dengan layanan lain, lihat Mengelola kuota.

Untuk mengetahui informasi umum tentang kuota dan batas sistem Model Armor—termasuk ukuran input dan batas token—lihat Kuota dan batas sistem dalam dokumentasi Model Armor.

Langkah berikutnya