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 Google Cloud lingkungan 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 akan memanggil Model Armor untuk menerapkan template keamanan yang telah ditentukan. Anda dapat mengonfigurasi template untuk memblokir dan mengedit konten yang melanggar kebijakan, atau hanya memeriksa konten dan mencatat pelanggaran yang terdeteksi. Hal ini mengurangi risiko seperti injeksi perintah, jailbreak, paparan 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 Google Cloud konsol (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 sanitasi streaming menggunakan metode streamQuery untuk agen yang dibuat dengan Agent Development Kit.
  • Penggunaan template lintas project: Saat menggunakan template Model Armor dalam 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.
  • Penyesuaian regional: Model Armor dan layanan yang diintegrasikan harus di-deploy dalam region yang sama Google Cloud . 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.

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 tempat Anda berencana menambahkan gateway. Anda dapat menggunakan template yang sama untuk traffic ingress dan egress.

    Perhatikan nama template. Untuk menyalin nama template di Google Cloud konsol, lihat detail template, lalu klik Salin ke papan klip di samping nama template.

  3. Siapkan Agent Gateway di region yang sama 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 kepada agen layanan yang sesuai:

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

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

      • Peran Model Armor User (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 project tempat Anda membuat agen.
      • AGENT_RUNTIME_PROJECT_NUMBER: Nomor project project tempat Anda membuat agen.
      • MODEL_ARMOR_PROJECT_ID: Project ID 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 Model Armor User (roles/modelarmor.user) di 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 project tempat Anda membuat gateway.
      • GATEWAY_PROJECT_NUMBER: Nomor project project tempat Anda membuat gateway.
      • MODEL_ARMOR_PROJECT_ID: Project ID 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 ingress dan egress

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

  • Traffic Ingress (Client-to-Agent): 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 Egress (Agent-to-Anywhere): 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 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 setiap arah.

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

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

Alur traffic untuk Client-to-Agent

  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 mencapai agen AI.
  4. Agen AI membuat respons. Agent Gateway mencegat respons ini sebelum mencapai klien.
  5. Model Armor menyaring respons, dan Agent Gateway mengizinkan atau memblokirnya berdasarkan hasil.

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

Menggunakan ID pelacakan

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

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

ID pelacakan ditangani dengan dua cara:

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

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

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

Penggunaan ID pelacakan adalah metode yang direkomendasikan untuk menghubungkan log dan pelacakan end-to-end dari pemanggil melalui Agent Gateway ke Model Armor dan agen hilir. Hal ini penting untuk proses debug, memahami tindakan keamanan, dan memantau performa. Untuk mengetahui informasi selengkapnya, lihat Melihat rentang pelacakan Model Armor.

Untuk melihat log operasi sanitasi untuk ID pelacakan 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 pelacakan 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 ingress. Untuk mengetahui informasi selengkapnya, lihat Menghubungkan log dan peristiwa terkait.