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, konten tersebut akan memanggil Model Armor untuk menerapkan template keamanan yang telah Anda tentukan. Anda dapat mengonfigurasi template untuk memblokir dan menyamarkan konten yang melanggar kebijakan, atau hanya memeriksa konten dan mencatat setiap pelanggaran yang terdeteksi. Hal ini memitigasi risiko seperti injeksi perintah, 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 ke dalam log. 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 konsolGoogle Cloud .

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

Batasan

Pertimbangkan batasan berikut saat mengintegrasikan Model Armor dengan Agent Gateway:

  • Dukungan streaming untuk agen: Model Armor hanya mendukung sanitasi streaming menggunakan metode streamQuery untuk agen yang dibuat 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 region Google Cloud yang sama. Panggilan lintas region ke Model Armor tidak didukung.
  • Kompatibilitas integrasi egress: Perlindungan inline Model Armor pada traffic egress 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 dibuat menggunakan ADK.
  • Tidak ada dukungan dokumen: Sanitasi 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.
  • 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 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. \
    --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. \
    --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. \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
    --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.

Traffic masuk dan keluar

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

  • Traffic Masuk (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 Klien ke Agen (ingress)

Anda menentukan template yang digunakan Model Armor untuk mengevaluasi:

  • Permintaan masuk dari klien (pengguna akhir atau aplikasi panggilan) 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 masing-masing arah.

Alur traffic untuk Klien-ke-Agen

  1. Klien mengirimkan perintah ke agen. Agent Gateway mencegat permintaan dan mengirimkan payload ke Model Armor.
  2. Model Armor menyaring permintaan. Jika diblokir, klien akan menerima error.
  3. Jika diizinkan, permintaan akan sampai ke 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 penilaian.

Perlindungan Agen ke Mana Saja (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 Agen-ke-Mana Saja

  1. Agen AI memulai permintaan ke sistem eksternal. Agent Gateway mencegat traffic keluar.
  2. Model Armor menyaring payload 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 mengizinkannya untuk mencapai agen atau memblokirnya.

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 trace.

Menggunakan ID rekaman aktivitas

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

Setiap trace berisi satu atau beberapa span, dengan setiap ID span mewakili operasi atau unit kerja tertentu dalam trace. Log yang dihasilkan selama eksekusi permintaan dikaitkan dengan ID span tertentu dari operasi yang melakukan pekerjaan.

ID rekaman aktivitas ditangani dengan dua cara:

  • Otomatis: Saat Google Cloud Observability diaktifkan, Agent Gateway akan otomatis membuat ID trace dan menyebarkannya melalui sistem.

  • Disediakan pengguna: Anda dapat mengganti ID trace yang dihasilkan sistem dengan memberikan ID trace Anda sendiri menggunakan header HTTP traceparent dalam permintaan Anda.

    Contoh kode berikut menunjukkan cara meneruskan ID trace 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 project Google Cloud Anda.
    • REASONING_ENGINE_ID: ID mesin penalaran Anda.

Menggunakan ID rekaman aktivitas adalah metode yang direkomendasikan untuk menghubungkan log dan rekaman aktivitas secara menyeluruh dari pemanggil melalui Agent Gateway ke Model Armor dan agen downstream mana pun. Hal ini penting untuk men-debug, memahami tindakan keamanan, dan memantau performa. Untuk mengetahui informasi selengkapnya, lihat Melihat span trace Model Armor.

Untuk melihat log operasi sanitasi untuk ID trace 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 trace permintaan Anda.

Menggunakan ID korelasi

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

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 (masuk) yang menggunakan protokol ADK, Model Armor hanya akan melakukan sanitasi reasoningEngines.streamQuery permintaan dan respons untuk agen yang dibuat menggunakan Agent Development Kit (ADK) dan berjalan di Agent Runtime.

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.