Mengonfigurasi Model Armor di gateway

Model Armor membantu Anda memastikan bahwa agen AI Anda mengikuti standar keamanan dan tata kelola Anda tanpa mengharuskan Anda menerapkan logika pemfilteran langsung di 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. Fitur ini memungkinkan Anda menerapkan batasan keamanan konten secara konsisten di semua agen yang diatur 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 ditampilkan 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 penyaringan 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 Klien-ke-Agen. Anda dapat menerapkan satu template ke kedua arah atau mengonfigurasi template yang berbeda untuk masing-masing arah.

Model Armor mengikuti template saat menyaring hal berikut:

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

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

Setelah agen AI memproses permintaan dan menghasilkan respons, Agent Gateway akan mengintersepsi streaming keluar sebelum mencapai klien. Model Armor mengevaluasi respons dan memberikan keputusan. Berdasarkan penilaian, Agent Gateway akan mengizinkan atau sepenuhnya memblokir respons.

Agent-to-Anywhere (egress 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 masing-masing arah.

Model Armor mengikuti template saat menyaring komunikasi antara agen AI dan sistem eksternal, termasuk hal 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 menangkap traffic egress dan memanggil Model Armor. Model Armor mengevaluasi payload sesuai dengan template egress yang Anda tetapkan.

Jika data keluar melanggar kebijakan keamanan Anda, Model Armor akan mengeluarkan keputusan BLOCK. Agent Gateway kemudian 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 Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

Mengaktifkan API

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna membuat template Model Armor, minta administrator untuk memberi Anda peran IAM Model Armor Admin (roles/modelarmor.admin) pada project. 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 Armor di 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 konsolGoogle Cloud , lihat detail template dan klik Salin ke papan klip di samping nama template.

    Jika Anda membuat template Model Armor di project yang berbeda dengan project yang berisi agen AI atau Gateway Agen dan Anda menggunakan Kontrol Layanan VPC, kedua project harus berada dalam perimeter layanan Kontrol Layanan VPC yang sama.

  3. Siapkan Agent Gateway di region yang sama dengan tempat template Model Armor disimpan. Untuk Client-to-Agent (ingress) gateway, tentukan template Model Armor yang Anda buat untuk traffic masuk. Untuk Agent-to-Anywhere (egress) gateway, 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:

    • Klien-ke-Agen (ingress): Berikan peran berikut kepada agen layanan AI Platform Reasoning Engine Service Agent:

      • Peran Model Armor Callout User (roles/modelarmor.calloutUser) dalam project yang berisi agen AI.

      • Peran Model Armor User (roles/modelarmor.user) dalam 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.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.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 dari project tempat Anda membuat agen.
      • MODEL_ARMOR_PROJECT_ID: Project ID untuk project yang berisi template Model Armor.

    • Agen-ke-Mana Saja (egress): Berikan peran berikut kepada agen layanan Service Extensions:

      • Peran Model Armor Callout User (roles/modelarmor.calloutUser) dan Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) dalam project yang berisi gateway.
      • Peran Model Armor User (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.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.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.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 untuk 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 menerapkan kebijakan keamanan dengan benar.

Anda dapat memvalidasi template dengan mengkueri metode sanitizeUserPrompt secara langsung menggunakan serangkaian perintah pengujian. Untuk mengetahui informasi selengkapnya tentang cara menjalankan pemeriksaan pra-deployment ini dan daftar perintah pengujian yang diverifikasi, lihat Menguji template Model Armor.

Menyamarkan data sensitif dari permintaan dan respons

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

Jika Anda menggunakan jenis penerapan 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 lanjutan dan template de-identifikasi Anda.

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

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

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

Untuk mengetahui daftar lengkap pendeteksi 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 Klien-ke-Agen (ingress)

Untuk traffic Klien-ke-Agen (ingress) yang menggunakan protokol ADK, Model Armor hanya akan melakukan sanitasi pada permintaan dan respons reasoningEngines.streamQuery untuk agen yang dibangun menggunakan Agent Development Kit (ADK) dan berjalan di Vertex AI Agent Engine.

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

Traffic Agen ke Mana Saja (egress)

Untuk traffic Agen-ke-Mana Saja (egress), 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 pembuat alat MCP berbahaya)

Model Armor mengizinkan payload berikut tanpa sanitasi:

  • 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 (egress), 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 sanitasi.

Penyaringan dokumen

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

Kuota dan batas sistem

Kuota digunakan dalam project tempat template Model Armor berada. Jika gateway berada di project yang berbeda, 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