Model Armor in Agent Gateway einbinden

Die Gemini Enterprise Agent Platform ist eine Plattform zum Erstellen und Verwalten von KI-Agenten für Unternehmen. Agent Gateway dient als Steuerungsebene, die verwaltet, schützt und steuert, wie KI-Agenten eine Verbindung innerhalb der Google Cloud Umgebung und mit externen Agenten, KI-Anwendungen und LLMs herstellen und interagieren. Durch die Integration von Model Armor und Agent Gateway werden die Überprüfungsfunktionen von Model Armor direkt in die Kommunikationswege eingebettet, die von der Gemini Enterprise Agent Platform verwaltet werden. Wenn Inhalte über Agent Gateway weitergeleitet werden, ruft es Model Armor auf, um Ihre vordefinierten Sicherheitsvorlagen zu erzwingen. 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. Dadurch werden Risiken wie Prompt Injection, Jailbreaks, die Offenlegung schädlicher Inhalte und das Durchsickern vertraulicher Daten minimiert.

Wenn Model Armor Richtlinienverstöße in Inhalten erkennt, die über Agent Gateway weitergeleitet 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 ansehen (zu Model Armor). Diese Ergebnisse werden auch in Security Command Center angezeigt. Weitere Informationen finden Sie unter Ergebnisse in der Google Cloud Console prüfen.

Im Echtzeit-Streamingmodus unterstützt Model Armor eine unbegrenzte Anzahl von Tokens im Stream. Daher ist es für lange Interaktionen und Modellantworten geeignet.

Beschränkungen

Beachten Sie bei der Integration von Model Armor in Agent Gateway die folgenden Einschränkungen:

  • Streamingunterstützung für Agenten: Model Armor unterstützt die Streamingbereinigung nur mit der Methode streamQuery für Agenten, die mit dem Agent Development Kit erstellt wurden.
  • Vorlagenverwendung projektübergreifend: 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 in dem Projekt, in dem die Vorlage gehostet wird, als auch in dem Projekt, in dem der aufrufende Dienst gehostet wird, ausreichend sein. Weitere Informationen finden Sie unter Kontingente verwalten.
  • Regionale Ausrichtung: Model Armor und die Dienste, in die 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 der Integration für ausgehenden Traffic: 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 der Integration für eingehenden Traffic: Der Inline-Schutz für eingehenden Traffic mit Model Armor wird nur für Agenten unterstützt, die mit dem ADK erstellt wurden.

Model Armor in einem Gateway konfigurieren

So konfigurieren Sie Model Armor in 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 derselben Region, in der Sie das Gateway hinzufügen möchten. Sie können dieselbe Vorlage für eingehenden und ausgehenden Traffic verwenden.

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

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

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

    • Client zu Agent (eingehend): Weisen Sie dem Dienstkonto des AI Platform Reasoning Engine Service 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.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

      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 zu beliebigem Ziel (ausgehend): Weisen Sie dem Dienstkonto des Agent Gateway 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) im 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.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

      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 Zusammenhang mit der Integration von Agent Gateway und Model Armor werden die Begriffe eingehend und ausgehend 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 zu beliebigem Ziel) : Bezieht sich auf den Kommunikationsfluss zwischen dem Agenten und einem externen System. Model Armor kann sowohl die ausgehenden Anfragen vom Agenten an das externe System als auch die eingehenden Antworten vom externen System an den Agenten schützen.

Schutz für „Client zu Agent (eingehend)“

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

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

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

Für den Traffic „Client zu Agent (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 ReasoningEngineFehlerantworten werden nicht an Model Armor gesendet. Nicht-ADK-Nutzlasten (z. B. Langchain-Nutzlasten) werden ebenfalls nicht an Model Armor gesendet.

Trafficfluss für „Client zu Agent“

  1. Ein Client sendet einen Prompt an den Agenten. 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 eine Fehlermeldung.
  3. Wenn die Anfrage zulässig ist, erreicht sie den KI-Agenten.
  4. Der KI-Agent generiert eine Antwort. 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 je nach Ergebnis zu oder blockiert sie.

Schutz für „Agent zu beliebigem Ziel (ausgehend)“

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

  • 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

Trafficfluss für „Agent zu beliebigem Ziel“

  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 die Anfrage blockiert wird, 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. Agent Gateway fängt diese eingehende Antwort ab.
  5. Model Armor prüft die Antwortnutzlast und Agent Gateway lässt sie entweder zum Agenten durch oder blockiert sie.

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

Streaminganfragen verfolgen und debuggen

Um das Verfolgen und Debuggen 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 in einem verteilten System mehrere Dienste 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 Traces 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 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 mit dem HTTP-Header „traceparent“ in Ihren Anfragen eine eigene angeben.

    Das folgende Codebeispiel zeigt, 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 Google Cloud Projekts in.
    • REASONING_ENGINE_ID: die ID Ihrer Reasoning Engine.

Die Verwendung einer Trace-ID ist die empfohlene Methode, um Logs und Traces vom Aufrufer über Agent Gateway bis zu Model Armor und allen nachgelagerten Agenten durchgängig zu korrelieren. Dies ist für das Debuggen, das Verständnis von Sicherheitsmaßnahmen und die Leistungsüberwachung unerlässlich. Weitere Informationen finden Sie unter Model Armor-Tracespannen ansehen.

Verwenden Sie die folgende Abfrage im Log-Explorer, um Logs für 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 Streamingbereinigungssitzung beziehen, von der ersten Anfrage bis zur endgültigen Antwort. Es ist eine interne ID, 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.