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, schützt 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 Kommunikationswege eingebettet, die von der Gemini Enterprise Agent Platform verwaltet werden. Wenn Inhalte das KI-Agenten-Gateway durchlaufen, wird Model Armor aufgerufen, 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 oder 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 verringert.

Wenn Model Armor Richtlinienverstöße in Inhalten erkennt, die das KI-Agenten-Gateway durchlaufen, 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 derGoogle Cloud -Konsole ansehen.

Im Echtzeit-Streamingmodus unterstützt Model Armor eine unbegrenzte Anzahl von Tokens im Stream. Daher eignet sich dieser Modus für lange Interaktionen und Modellantworten.

Beschränkungen

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

  • Streamingunterstützung für KI-Agenten: Model Armor unterstützt die Streamingbereinigung nur mit der streamQuery-Methode für KI-Agenten, die mit dem Agent Development Kit erstellt wurden.
  • Vorlagenverwendung über mehrere Projekte hinweg: 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 der Egress-Integration: Der Inline-Schutz von Model Armor für Egress-Traffic ist auf Integrationen mit MCP-Servern, Diensten im OpenAI-Format und A2A über Agent Gateway beschränkt.
  • Kompatibilität mit der Ingress-Integration: Der Inline-Ingress-Schutz mit Model Armor wird nur für Agents unterstützt, die mit dem ADK erstellt wurden.

Model Armor auf einem Gateway konfigurieren

So konfigurieren Sie Model Armor für ein 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 sowohl für eingehenden als auch für ausgehenden Traffic verwenden.

    Notieren Sie sich die Namen der Vorlagen. 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 Namen der Vorlage auf  In die Zwischenablage kopieren.

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

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

    • Client zu Agent (eingehender Traffic): Weisen Sie dem Dienst-Agent 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 Agent erstellt haben.
      • AGENT_RUNTIME_PROJECT_NUMBER: Die Projektnummer des Projekts, in dem Sie den Agent erstellt haben.
      • MODEL_ARMOR_PROJECT_ID: Die Projekt-ID des Projekts, das die Model Armor-Vorlage enthält.

    • Agent-to-Anywhere (Egress): Gewähren Sie dem Dienst-Agenten für Dienst-Erweiterungen die folgenden Rollen:

      • 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 Kontext der Integration von Agent Gateway und Model Armor werden die Begriffe eingehender Traffic und ausgehender Traffic aus der Perspektive der Interaktionen des KI-Agents verwendet:

  • Eingehender Traffic (Client zu Agent): Bezieht sich auf den Kommunikationsfluss zwischen einem Client und dem Agent. Model Armor kann sowohl die eingehenden Anfragen vom Client an den Agent als auch die ausgehenden Antworten vom Agent an den Client schützen.
  • Ausgehender Traffic (KI-Agent – beliebig): Bezieht sich auf den Kommunikationsfluss zwischen dem KI-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 von Client zu Agent (eingehend)

Sie definieren Vorlagen, die von Model Armor zur Bewertung verwendet werden:

  • Eingehende Anfragen vom Client (Endnutzer oder Anrufanwendungen) an Ihren KI-Agenten.
  • Ausgehende Antworten des KI-Agents an den Kunden.

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

Bei Client-zu-Agent-Traffic (Ingress) 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.

Datenverkehr für Client-zu-Agent

  1. Ein Client sendet einen Prompt an den Agent. Agent Gateway fängt die Anfrage ab und sendet die Nutzlast an Model Armor.
  2. Model Armor prüft die Anfrage. Wenn der Zugriff blockiert wird, erhält der Client eine Fehlermeldung.
  3. Wenn die Anfrage zulässig ist, wird sie an den KI-Agenten weitergeleitet.
  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 je nach Ergebnis zu oder blockiert sie.

Schutz für Agent zu beliebigem Ziel (ausgehend)

Sie definieren Vorlagen, die von Model Armor zur 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, einschließlich:

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

Traffic-Fluss 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 Verbindung blockiert wird, wird sie 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 das KI-Agenten-Gateway lässt sie entweder zum KI-Agenten durch oder blockiert sie.

Weitere Informationen finden Sie unter Model Armor für ein Gateway konfigurieren.

Streaminganfragen nachverfolgen 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, wenn sie in einem verteilten System über mehrere Dienste hinweg übertragen wird. 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 der spezifischen Spannen-ID des Vorgangs zugeordnet, 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 in Ihren Anfragen den HTTP-Header „traceparent“ verwenden.

    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 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 vom Aufrufer über das Agenten-Gateway bis hin zu Model Armor und allen nachgelagerten Agenten durchgängig zu korrelieren. Dies ist für die Fehlerbehebung, das Nachvollziehen von Sicherheitsmaßnahmen und das Monitoring der Leistung unerlässlich. Weitere Informationen finden Sie unter Model Armor-Trace-Spans ansehen.

Wenn Sie die Logs für den Bereinigungsvorgang für eine bestimmte Trace-ID aufrufen möchten, verwenden Sie die folgende Abfrage im Log-Explorer:

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-Bereinigungssitzung beziehen, von der ursprünglichen Anfrage bis zur endgültigen Antwort. Es handelt sich um eine interne Kennung, die hauptsächlich in Model Armor-Protokollen verwendet wird, insbesondere für Ingress-Streaming-Sitzungen. Weitere Informationen finden Sie unter Logs und zugehörige Ereignisse korrelieren.