Mengintegrasikan Model Armor dengan Agent Gateway

Gemini Enterprise Agent Platform adalah platform untuk membangun dan mengelola agen AI tingkat perusahaan. Agent Gateway berfungsi sebagai bidang kontrol yang mengelola, mengamankan, dan mengatur cara agen AI terhubung dan berinteraksi dalam lingkungan Google Cloud dan dengan agen eksternal, aplikasi AI, dan LLM. Integrasi Model Armor dan Agent Gateway menyematkan kemampuan penyaringan Model Armor langsung ke jalur komunikasi yang dikelola Gemini Enterprise Agent Platform. Saat konten melewati Agent Gateway, Model Armor akan dipanggil untuk menerapkan template keamanan yang telah ditentukan sebelumnya. Anda dapat mengonfigurasi template untuk memblokir dan menyamarkan konten yang melanggar kebijakan, atau hanya memeriksa konten dan mencatat setiap pelanggaran yang terdeteksi. Tindakan ini memitigasi risiko seperti injeksi prompt, jailbreak, eksposur ke konten berbahaya, dan kebocoran data sensitif.

Saat Model Armor mendeteksi pelanggaran kebijakan dalam konten yang melewati Agent Gateway, Model Armor dapat dikonfigurasi untuk mencatat peristiwa ini. Anda dapat melihat temuan ini di halaman Model Armor di konsol Google Cloud (Buka Model Armor). Temuan ini juga ditampilkan di Security Command Center. Untuk mengetahui informasi selengkapnya, lihat Meninjau temuan di Google Cloud konsol.

Saat menggunakan mode streaming real-time, Model Armor mendukung token tanpa batas dalam streaming, sehingga cocok untuk interaksi dan respons model yang berjalan lama.

Batasan

Pertimbangkan batasan berikut saat mengintegrasikan Model Armor dengan Agent Gateway:

  • Dukungan streaming untuk agen: Model Armor hanya mendukung pembersihan streaming menggunakan metode streamQuery untuk agen yang dibangun dengan Agent Development Kit.
  • Penggunaan template lintas project: Saat menggunakan template Model Armor di satu project untuk membersihkan permintaan layanan, seperti Agent Gateway, di project lain, kuota API untuk Model Armor harus mencukupi di project yang menghosting template dan project yang menghosting layanan panggilan. Untuk mengetahui informasi selengkapnya, lihat Mengelola kuota.
  • Penyelarasan regional: Model Armor dan layanan yang terintegrasi dengannya harus di-deploy dalam Google Cloud region yang sama. Panggilan lintas-region ke Model Armor tidak didukung.
  • Kompatibilitas integrasi keluar: Perlindungan inline Model Armor pada traffic keluar terbatas pada integrasi dengan server MCP, layanan yang mengikuti format OpenAI, dan A2A melalui Agent Gateway.
  • Kompatibilitas integrasi Ingress: Perlindungan ingress inline dengan Model Armor hanya didukung untuk agen yang dibangun menggunakan ADK.
  • Tidak ada dukungan dokumen: Pembersihan 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.
  • Payload yang didukung: Untuk mengetahui daftar payload yang didukung, 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 konsolGoogle Cloud , 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 ingress. 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.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 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.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 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.

Traffic masuk dan keluar

Dalam konteks integrasi Agent Gateway dan Model Armor, istilah ingress dan egress digunakan dari perspektif interaksi agen AI:

  • Traffic Ingress (Klien ke Agen): Mengacu pada alur komunikasi antara klien dan agen. Model Armor dapat melindungi permintaan masuk dari klien ke agen dan respons keluar dari agen kembali ke klien.
  • Traffic Keluar (Agen ke Mana Saja): Mengacu pada alur komunikasi antara agen dan sistem eksternal. Model Armor dapat melindungi permintaan keluar dari agen ke sistem eksternal dan respons masuk dari sistem eksternal kembali ke agen.

Perlindungan Client-to-Agent (ingress)

Anda menentukan template yang digunakan Model Armor untuk mengevaluasi:

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

Anda dapat menerapkan satu template ke kedua arah atau mengonfigurasi template yang berbeda untuk setiap arah.

Alur traffic untuk Client-to-Agent

  1. Klien mengirimkan perintah ke agen. Agent Gateway mencegat permintaan dan mengirim payload ke Model Armor.
  2. Model Armor menyaring permintaan. Jika diblokir, klien akan menerima error.
  3. Jika diizinkan, permintaan akan mencapai agen AI.
  4. Agen AI menghasilkan respons. Agent Gateway mencegat respons ini sebelum mencapai klien.
  5. Model Armor menyaring respons, dan Agent Gateway mengizinkan atau memblokirnya berdasarkan hasil pemeriksaan.

Perlindungan Agent-to-Anywhere (egress)

Anda menentukan template yang digunakan Model Armor untuk mengevaluasi:

  • Permintaan keluar dari agen AI Anda ke sistem eksternal.
  • Respons masuk dari sistem eksternal kembali ke agen AI Anda.

Perlindungan ini berlaku untuk komunikasi dengan sistem, termasuk:

  • LLM eksternal dan agen AI pihak ketiga
  • Server Model Context Protocol (MCP)
  • Agen AI lainnya

Alur traffic untuk Agent-to-Anywhere

  1. Agen AI memulai permintaan ke sistem eksternal. Agent Gateway mencegat traffic keluar.
  2. Model Armor menyaring payload yang keluar. Jika diblokir, koneksi akan dihentikan.
  3. Jika diizinkan, permintaan akan dikirim ke sistem eksternal.
  4. Sistem eksternal mengirimkan respons kembali. Agent Gateway mencegat respons masuk ini.
  5. Model Armor menyaring payload respons, dan Agent Gateway mengizinkan atau memblokirnya untuk mencapai agen.

Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi Model Armor di gateway.

Melacak dan men-debug permintaan streaming

Untuk memfasilitasi pelacakan dan proses debug permintaan streaming, Model Armor menggunakan ID korelasi dan ID aktivitas.

Menggunakan ID rekaman aktivitas

ID rekaman aktivitas menghubungkan semua peristiwa untuk satu permintaan saat permintaan tersebut berjalan di beberapa layanan dalam sistem terdistribusi. Hal ini mencakup penerapan keamanan yang diterapkan Model Armor dalam jalur permintaan resource Agent Gateway.

Setiap rekaman aktivitas berisi satu atau beberapa rentang, dengan setiap ID rentang merepresentasikan operasi atau unit kerja tertentu dalam rekaman aktivitas. Log yang dibuat selama eksekusi permintaan dikaitkan dengan ID rentang tertentu dari operasi yang melakukan tugas.

ID rekaman aktivitas ditangani dengan dua cara:

  • Otomatis: Jika Google Cloud Observability diaktifkan, Agent Gateway akan otomatis membuat ID aktivitas dan menyebarkannya ke seluruh sistem.

  • Disediakan pengguna: Anda dapat mengganti ID aktivitas yang dibuat sistem dengan menyediakan ID Anda sendiri menggunakan header HTTP traceparent dalam permintaan Anda.

    Contoh kode berikut menunjukkan cara meneruskan ID rekaman aktivitas kustom dalam permintaan ke metode streamQuery:

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "traceparent: 00-98adffecc8dd095968a06c44216190f6-5b565a8342378cd7-01" \
  "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID:streamQuery?alt=sse"

    Ganti kode berikut:

    • LOCATION: region tempat mesin penalaran berada.
    • PROJECT_ID: ID Google Cloud project Anda.
    • REASONING_ENGINE_ID: ID mesin penalaran Anda.

Penggunaan ID aktivitas adalah metode yang direkomendasikan untuk mengorelasikan log dan aktivitas secara menyeluruh dari pemanggil melalui Agent Gateway ke Model Armor dan agen hilir lainnya. Hal ini penting untuk men-debug, memahami tindakan keamanan, dan memantau performa. Untuk mengetahui informasi selengkapnya, lihat Melihat rentang rekaman aktivitas Model Armor.

Untuk melihat log operasi sanitasi untuk ID aktivitas tertentu, gunakan kueri berikut di Logs Explorer:

jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
trace:TRACE_ID

Ganti TRACE_ID dengan ID aktivitas permintaan Anda.

Menggunakan ID korelasi

ID korelasi menautkan semua entri log di Cloud Logging yang berkaitan dengan satu sesi pembersihan streaming, dari permintaan awal hingga respons akhir. ID ini adalah ID internal yang terutama digunakan dalam log Model Armor, khususnya untuk sesi streaming ingress. Untuk mengetahui informasi selengkapnya, lihat Mengorelasikan log dan peristiwa terkait.

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

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 sanitasi:

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 lain melalui server LLM yang kompatibel dengan OpenAI API (seperti vLLM). Payload yang tidak tercantum di sini diizinkan tanpa pembersihan.