Model Armor in Agent Gateway einbinden

Die Gemini Enterprise Agent Platform ist eine Plattform zum Erstellen und Verwalten von KI-Agenten auf Unternehmensniveau. Agent Gateway dient als Steuerungsebene, die verwaltet, sichert und steuert, wie KI-Agenten innerhalb der Google Cloud -Umgebung und mit externen Agenten, KI-Anwendungen und LLMs verbunden sind und interagieren. Durch die Integration von Model Armor und Agent Gateway werden die Prüffunktionen von Model Armor direkt in die Kommunikationspfade eingebettet, die von der Gemini Enterprise Agent Platform verwaltet werden. Wenn Inhalte das Agent Gateway passieren, wird Model Armor aufgerufen, um Ihre vordefinierten Sicherheitsvorlagen anzuwenden. Sie können Ihre Vorlage so konfigurieren, dass Inhalte, die gegen Richtlinien verstoßen, entweder blockiert und unkenntlich gemacht werden oder dass Inhalte nur geprüft und alle erkannten Verstöße protokolliert werden. So werden Risiken wie Prompt Injection, Jailbreaking, die Offenlegung schädlicher Inhalte und der Verlust sensibler Daten minimiert.

Wenn Model Armor Richtlinienverstöße in Inhalten erkennt, die über Agent Gateway übertragen werden, kann es so konfiguriert werden, dass diese Ereignisse protokolliert werden. Sie können diese Ergebnisse in der Google Cloud Console auf der Seite Model Armor aufrufen (Zu Model Armor). Diese Ergebnisse werden auch im Security Command Center angezeigt. Weitere Informationen finden Sie unter Ergebnisse in derGoogle Cloud Console prüfen.

Im Echtzeit-Streamingmodus unterstützt Model Armor eine unbegrenzte Anzahl von Tokens im Stream. Dadurch eignet es sich für lang andauernde Interaktionen und Modellantworten.

Beschränkungen

Beachten Sie die folgenden Einschränkungen, wenn Sie Model Armor in Agent Gateway einbinden:

  • Streaming-Unterstützung für Agenten: Model Armor unterstützt nur die Streaming-Bereinigung mit der Methode streamQuery für Agenten, die mit dem Agent Development Kit erstellt wurden.
  • Projektübergreifende Vorlagennutzung: Wenn Sie eine Model Armor-Vorlage in einem Projekt verwenden, um Anfragen für einen Dienst wie Agent Gateway in einem anderen Projekt zu bereinigen, muss das API-Kontingent für Model Armor sowohl im Projekt, in dem die Vorlage gehostet wird, als auch im Projekt, in dem der aufrufende Dienst gehostet wird, ausreichend sein. Weitere Informationen finden Sie unter Kontingente verwalten.
  • Regionale Ausrichtung: Model Armor und die Dienste, mit denen es integriert ist, müssen in derselben Google Cloud -Region bereitgestellt werden. Regionenübergreifende Aufrufe von Model Armor werden nicht unterstützt.
  • Kompatibilität mit ausgehender Integration: Der Inline-Schutz von Model Armor für ausgehenden Traffic ist auf Integrationen mit MCP-Servern, Diensten im OpenAI-Format und A2A über Agent Gateway beschränkt.
  • Kompatibilität mit Ingress-Integration: Der Inline-Ingress-Schutz mit Model Armor wird nur für Agenten unterstützt, die mit dem ADK erstellt wurden.
  • Keine Dokumentunterstützung: Das Bereinigen von Prompts und Antworten, die Dokumente oder Dateiuploads (z. B. PDFs) enthalten, wird in dieser Integration nicht unterstützt. Wenn Sie Dokumente prüfen möchten, rufen Sie die Model Armor REST API direkt auf.
  • Unterstützte Nutzlasten: Eine Liste der unterstützten Nutzlasten finden Sie in diesem Dokument unter Unterstützte und nicht unterstützte Nutzlasten.

Model Armor auf einem Gateway konfigurieren

So konfigurieren Sie Model Armor auf einem Gateway:

  1. Aktivieren Sie die Model Armor API in dem Projekt, in dem Sie die Model Armor-Vorlagen erstellen möchten.

  2. Erstellen Sie eine oder mehrere Model Armor-Vorlagen in der Region, in der Sie das Gateway hinzufügen möchten. Sie können dieselbe Vorlage sowohl für eingehenden als auch für ausgehenden Traffic verwenden.

    Notieren Sie sich die Vorlagennamen. Wenn Sie den Namen einer Vorlage in derGoogle Cloud Console kopieren möchten, rufen Sie die Details der Vorlage auf und klicken Sie neben dem Vorlagennamen auf In die Zwischenablage kopieren.

    Wenn Sie die Model Armor-Vorlagen in einem anderen Projekt als dem Projekt erstellen, das den KI-Agenten oder das Agent Gateway enthält, und Sie VPC Service Controls verwenden, müssen sich beide Projekte im selben VPC Service Controls-Dienstperimeter befinden.

  3. Richten Sie das Agent Gateway in derselben Region ein, in der die Model Armor-Vorlagen gespeichert sind. Geben Sie für das Client-zu-Agent-Gateway (eingehend) die Model Armor-Vorlagen an, die Sie für eingehenden Traffic erstellt haben. Geben Sie für das Agent-to-Anywhere-Gateway (ausgehend) die Model Armor-Vorlagen an, die Sie für ausgehenden Traffic erstellt haben. Sie können für beide Trafficflüsse dieselbe Vorlage verwenden.

  4. Weisen Sie den entsprechenden Dienst-Agents die erforderlichen IAM-Rollen zu:

    • Client zu Agent (eingehend): Weisen Sie dem KI-Plattform Reasoning Engine-Dienst-Agent die folgenden Rollen zu:

      • Die Rolle „Model Armor Callout User“ (roles/modelarmor.calloutUser) im Projekt, das den KI-Agenten enthält.

      • Die Rolle „Model Armor User“ (roles/modelarmor.user) im Projekt, das die Model Armor-Vorlage enthält.

      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

      Ersetzen Sie Folgendes:

      • AGENT_RUNTIME_PROJECT_ID: Die Projekt-ID des Projekts, in dem Sie den Agenten erstellt haben.
      • AGENT_RUNTIME_PROJECT_NUMBER: Die Projektnummer des Projekts, in dem Sie den Agenten erstellt haben.
      • MODEL_ARMOR_PROJECT_ID: Die Projekt-ID des Projekts, das die Model Armor-Vorlage enthält.

    • Agent-to-Anywhere (ausgehend): Weisen Sie dem Service Extensions-Dienst-Agenten die folgenden Rollen zu:

      • Die Rollen „Model Armor Callout User“ (roles/modelarmor.calloutUser) und „Service Usage Consumer“ (roles/serviceusage.serviceUsageConsumer) im Projekt, das das Gateway enthält.
      • Die Rolle „Model Armor User“ (roles/modelarmor.user) in dem Projekt, das die Model Armor-Vorlage enthält.
      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

      Ersetzen Sie Folgendes:

      • GATEWAY_PROJECT_ID: Die Projekt-ID des Projekts, in dem Sie das Gateway erstellt haben.
      • GATEWAY_PROJECT_NUMBER: Die Projektnummer des Projekts, in dem Sie das Gateway erstellt haben.
      • MODEL_ARMOR_PROJECT_ID: Die Projekt-ID des Projekts, das die Model Armor-Vorlage enthält.

      Eine Anleitung finden Sie unter Autorisierung an Model Armor delegieren.

    Allgemeine Informationen zum Zuweisen einer Rolle finden Sie unter Einzelne IAM-Rolle zuweisen.

Ein- und ausgehender Traffic

Im Kontext der Integration von Agent Gateway und Model Armor werden die Begriffe Ingress und Egress aus der Perspektive der Interaktionen des KI-Agenten verwendet:

  • Eingehender Traffic (Client-zu-Agent): Bezieht sich auf den Kommunikationsfluss zwischen einem Client und dem Agenten. Model Armor kann sowohl die eingehenden Anfragen vom Client an den Agenten als auch die ausgehenden Antworten vom Agenten an den Client schützen.
  • Ausgehender Traffic (Agent-to-Anywhere): Bezieht sich auf den Kommunikationsfluss zwischen dem Agenten und einem externen System. Model Armor kann sowohl die ausgehenden Anfragen des KI-Agenten an das externe System als auch die eingehenden Antworten des externen Systems an den KI-Agenten schützen.

Schutz für Client-zu-Agent-Traffic (eingehend)

Sie definieren Vorlagen, die Model Armor für die Bewertung verwendet:

  • Eingehende Anfragen vom Client (Endnutzer oder aufrufende Anwendungen) an Ihren KI-Agenten.
  • Ausgehende Antworten des KI-Agenten an den Client.

Sie können eine einzelne Vorlage auf beide Richtungen anwenden oder für jede Richtung unterschiedliche Vorlagen konfigurieren.

Traffic-Fluss für Client-zu-Agent

  1. Ein Client sendet einen Prompt an den Agenten. Das Agent Gateway fängt die Anfrage ab und sendet die Nutzlast an Model Armor.
  2. Model Armor prüft die Anfrage. Wenn die Anfrage blockiert wird, erhält der Client einen Fehler.
  3. Wenn die Anfrage zulässig ist, erreicht sie den KI-Agenten.
  4. Der KI-Agent generiert eine Antwort. Das Agent Gateway fängt diese Antwort ab, bevor sie den Client erreicht.
  5. Model Armor prüft die Antwort und Agent Gateway lässt sie basierend auf dem Ergebnis entweder zu oder blockiert sie.

Schutz für Agent zu beliebigem Ziel (ausgehend)

Sie definieren Vorlagen, die Model Armor für die Bewertung verwendet:

  • Ausgehende Anfragen von Ihrem KI-Agenten an externe Systeme.
  • Eingehende Antworten von externen Systemen an Ihren KI-Agenten.

Dieser Schutz gilt für die Kommunikation mit Systemen wie:

  • Externe LLMs und KI-Agenten von Drittanbietern
  • MCP-Server (Model Context Protocol)
  • Andere KI-Agenten

Traffic-Fluss für Agent-to-Anywhere

  1. Der KI-Agent initiiert eine Anfrage an ein externes System. Agent Gateway fängt den ausgehenden Traffic ab.
  2. Model Armor prüft die ausgehende Nutzlast. Wenn sie blockiert ist, wird die Verbindung beendet.
  3. Wenn die Anfrage zulässig ist, wird sie an das externe System gesendet.
  4. Das externe System sendet eine Antwort zurück. Das Agent Gateway fängt diese eingehende Antwort ab.
  5. Model Armor prüft die Antwortnutzlast und Agent Gateway lässt sie entweder zum Agent durch oder blockiert sie.

Weitere Informationen finden Sie unter Model Armor auf einem Gateway konfigurieren.

Streaminganfragen verfolgen und Fehler beheben

Um das Tracking und Debugging von Streaminganfragen zu erleichtern, verwendet Model Armor eine Korrelations-ID und eine Trace-ID.

Trace-ID verwenden

Eine Trace-ID verbindet alle Ereignisse für eine einzelne Anfrage, während sie mehrere Dienste in einem verteilten System durchläuft. Dazu gehören die Sicherheitsmaßnahmen, die Model Armor im Anfragepfad der Agent Gateway-Ressource anwendet.

Jeder Trace enthält einen oder mehrere Spans, wobei jede Span-ID einen bestimmten Vorgang oder eine bestimmte Arbeitseinheit innerhalb des Trace darstellt. Logs, die während der Ausführung einer Anfrage generiert werden, sind mit der spezifischen Span-ID des Vorgangs verknüpft, der die Arbeit ausführt.

Eine Trace-ID wird auf zwei Arten verarbeitet:

  • Automatisch: Wenn Google Cloud Observability aktiviert ist, generiert das Agent Gateway automatisch eine Trace-ID und gibt sie im System weiter.

  • Vom Nutzer bereitgestellt: Sie können die vom System generierte Trace-ID überschreiben, indem Sie in Ihren Anfragen den HTTP-Header „traceparent“ verwenden.

    Im folgenden Codebeispiel wird gezeigt, wie Sie eine benutzerdefinierte Trace-ID in einer Anfrage an die Methode streamQuery übergeben:

    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"

    Ersetzen Sie Folgendes:

    • LOCATION: die Region, in der sich die Reasoning Engine befindet.
    • PROJECT_ID: die ID Ihres Projekts in Google Cloud .
    • REASONING_ENGINE_ID: die ID Ihrer Reasoning Engine.

Die Verwendung einer Trace-ID ist die empfohlene Methode, um Logs und Traces durchgängig vom Aufrufer über das Agent Gateway bis hin zu Model Armor und allen nachgelagerten Agenten zu korrelieren. Dies ist für das Debugging, das Verständnis von Sicherheitsaktionen und das Monitoring der Leistung unerlässlich. Weitere Informationen finden Sie unter Model Armor-Trace-Spans ansehen.

Verwenden Sie die folgende Abfrage im Log-Explorer, um die Logs für die Bereinigungsvorgänge für eine bestimmte Trace-ID aufzurufen:

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

Ersetzen Sie TRACE_ID durch die Trace-ID Ihrer Anfrage.

Korrelations-ID verwenden

Eine Korrelations-ID verknüpft alle Logeinträge in Cloud Logging, die sich auf eine einzelne Streaming-Sanitization-Sitzung beziehen, von der ersten Anfrage bis zur endgültigen Antwort. Es handelt sich um eine interne Kennung, die hauptsächlich in Model Armor-Logs verwendet wird, insbesondere für eingehende Streamingsitzungen. Weitere Informationen finden Sie unter Logs und zugehörige Ereignisse korrelieren.

Unterstützte und nicht unterstützte Nutzlasten

In diesem Abschnitt werden die Arten von Nutzlasten aufgeführt, die von Model Armor bereinigt werden.

Client-zu-Agent-Traffic (eingehend)

Bei Client-zu-Agent-Traffic (eingehend) mit dem ADK-Protokoll bereinigt Model Armor nur reasoningEngines.streamQuery-Anfragen und ‑Antworten für Agenten, die mit dem Agent Development Kit (ADK) erstellt wurden und in der Agent Runtime ausgeführt werden.

Alle anderen ReasoningEngine-Nutzlasten und ReasoningEngine-Fehlerantworten werden nicht an Model Armor gesendet. Nicht-ADK-Nutzlasten (z. B. Langchain-Nutzlasten) werden ebenfalls nicht an Model Armor gesendet.

Traffic von KI-Agent zu beliebigem Ziel (ausgehend)

Für den Traffic vom Agent zu einem beliebigen Ziel (ausgehend) werden die folgenden Nutzlasten unterstützt.

A2A-Nutzlasten

Model Armor bereinigt nur die folgenden Nutzlasten des A2A v1-Protokolls:

Model Armor lässt die folgenden A2A-Nutzlasten ohne Bereinigung zu:

MCP-Nutzlasten

Model Armor bereinigt nur die folgenden MCP-Nutzlasten:

  • tools/call-Anfrage und -Antwort
  • prompts/get-Anfrage und -Antwort
  • MCP-Tool-Ausführungsfehler (Ziel für Prompt Injection durch böswillige MCP-Tool-Autoren)

Model Armor lässt die folgenden Nutzlasten ohne Bereinigung zu:

  • tools/list
  • resources/*
  • notifications/*
  • Streamable HTTP/SSE for MCP
  • MCP-Protokollfehler (z. B. alle Fehler außer Fehlern bei der Toolausführung)

Externe LLM-Nutzlasten

Model Armor bereinigt nur die folgenden Payloads des OpenAI API-Protokolls (ausgehend), einschließlich GPT-Modellen auf openai.com sowie aller anderen Modelle über OpenAI API-kompatible LLM-Server (z. B. vLLM). Nutzlasten, die hier nicht aufgeführt sind, sind ohne Bereinigung zulässig.