REST Resource: projects.locations.apps.guardrails

Ressource: Guardrail

Guardrail enthält eine Liste von Prüfungen und Kontrollen, um die Agenten zu schützen.

JSON-Darstellung
{
  "name": string,
  "displayName": string,
  "description": string,
  "enabled": boolean,
  "action": {
    object (TriggerAction)
  },
  "createTime": string,
  "updateTime": string,
  "etag": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "contentFilter": {
    object (Guardrail.ContentFilter)
  },
  "llmPromptSecurity": {
    object (Guardrail.LlmPromptSecurity)
  },
  "llmPolicy": {
    object (Guardrail.LlmPolicy)
  },
  "modelSafety": {
    object (Guardrail.ModelSafety)
  },
  "codeCallback": {
    object (Guardrail.CodeCallback)
  },
  "supervisor": {
    object (Guardrail.Supervisor)
  }
  // End of mutually exclusive fields.
}
Felder
name

string

ID. Die eindeutige Kennung der Guardrail. Format: projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}

displayName

string

Erforderlich. Anzeigename der Guardrail.

description

string

Optional. Beschreibung der Schutzmaßnahme.

enabled

boolean

Optional. Gibt an, ob die Schutzmaßnahme aktiviert ist.

action

object (TriggerAction)

Optional. Aktion, die ausgeführt werden soll, wenn die Schutzmaßnahme ausgelöst wird.

createTime

string (Timestamp format)

Nur Ausgabe. Zeitstempel für die Erstellung der Guardrail.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30"

updateTime

string (Timestamp format)

Nur Ausgabe. Zeitstempel der letzten Aktualisierung der Guardrail.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".

etag

string

Etag, mit dem sichergestellt wird, dass sich das Objekt während eines Lesevorgangs mit anschließender Änderung und Schreibvorgang nicht geändert hat. Wenn das ETag leer ist, werden durch das Update alle gleichzeitigen Änderungen überschrieben.

Typ der Schutzmaßnahme. Im Folgenden finden Sie eine Liste von Feldern, die sich gegenseitig ausschließen. In einer Antwort wird höchstens eines der Felder festgelegt:
contentFilter

object (Guardrail.ContentFilter)

Optional. Guardrail, die verhindert, dass bestimmte Inhalte in der Unterhaltung verwendet werden.

llmPromptSecurity

object (Guardrail.LlmPromptSecurity)

Optional. Guardrail, die die Unterhaltung blockiert, wenn der Prompt basierend auf der LLM-Klassifizierung als unsicher eingestuft wird.

llmPolicy

object (Guardrail.LlmPolicy)

Optional. Guardrail, die die Unterhaltung blockiert, wenn die LLM-Antwort gemäß der LLM-Klassifizierung als Verstoß gegen die Richtlinie gilt.

modelSafety

object (Guardrail.ModelSafety)

Optional. Guardrail, die die Unterhaltung blockiert, wenn die LLM-Antwort basierend auf den Modellsicherheitseinstellungen als unsicher eingestuft wird.

codeCallback

object (Guardrail.CodeCallback)

Optional. Guardrail, die die Unterhaltung basierend auf dem Ergebnis der Callback-Ausführung möglicherweise blockiert.

supervisor

object (Guardrail.Supervisor)

Optional. Schutzmaßnahme, die eine Supervisor-Intervention ausführt.

Ende der sich gegenseitig ausschließenden Felder.

Guardrail.ContentFilter

Guardrail, die verhindert, dass bestimmte Inhalte in der Unterhaltung verwendet werden.

JSON-Darstellung
{
  "bannedContents": [
    string
  ],
  "bannedContentsInUserInput": [
    string
  ],
  "bannedContentsInAgentResponse": [
    string
  ],
  "matchType": enum (Guardrail.ContentFilter.MatchType),
  "disregardDiacritics": boolean,
  "sensitiveWordsExemptions": [
    string
  ]
}
Felder
bannedContents[]

string

Optional. Liste verbotener Ausdrücke. Gilt sowohl für Nutzereingaben als auch für Antworten des KI-Agenten.

bannedContentsInUserInput[]

string

Optional. Liste verbotener Ausdrücke. Gilt nur für Nutzereingaben.

bannedContentsInAgentResponse[]

string

Optional. Liste verbotener Ausdrücke. Gilt nur für Antworten von KI-Agenten.

matchType

enum (Guardrail.ContentFilter.MatchType)

Erforderlich. Keyword-Option für den Inhaltsfilter.

disregardDiacritics

boolean

Optional. Wenn der Wert „true“ ist, werden diakritische Zeichen beim Abgleich ignoriert.

sensitiveWordsExemptions[]

string

Optional. Einträge in der Liste sensibler Wörter, die diese Schutzmaßnahme zulässt. Nur gültig, wenn „matchType“ auf „SENSITIVE_WORDS“ festgelegt ist. Jeder Wert muss einem Listeneintrag entsprechen (Groß-/Kleinschreibung wird nicht berücksichtigt, Leerzeichen am Anfang und Ende werden ignoriert). Andere Werte haben keine Auswirkungen. Gilt nur für diese Schutzmaßnahme. Maximal 1.000 Einträge mit jeweils bis zu 256 Zeichen.

Guardrail.ContentFilter.MatchType

Keyword-Option für den Inhaltsfilter.

Enums
MATCH_TYPE_UNSPECIFIED Die Keyword-Option ist nicht angegeben.
SIMPLE_STRING_MATCH Inhalte werden Zeichen für Zeichen auf Teilstrings abgeglichen.
WORD_BOUNDARY_STRING_MATCH Inhalte werden nur dann erkannt, wenn das im Text gefundene Muster von Worttrennzeichen umgeben ist. Verbotene Ausdrücke können auch Worttrennzeichen enthalten.
REGEXP_MATCH Inhalte werden mithilfe der Syntax für reguläre Ausdrücke abgeglichen.
SENSITIVE_WORDS Inhalte werden mit einer vom System verwalteten Liste sensibler Wörter und Wortgruppen abgeglichen. Wenn Sie eine Schutzmaßnahme mit diesem Abgleichtyp an eine Anwendung oder einen Agenten anhängen, wird der standardmäßige Filter für sensible Wörter für die betroffenen Agenten ersetzt. Deaktivieren Sie die Schutzmaßnahme, um den Standardfilter nicht zu verwenden.

Guardrail.LlmPromptSecurity

Guardrail, die die Unterhaltung blockiert, wenn die Eingabe basierend auf der LLM-Klassifizierung als unsicher eingestuft wird.

JSON-Darstellung
{
  "failOpen": boolean,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "defaultSettings": {
    object (Guardrail.LlmPromptSecurity.DefaultSecuritySettings)
  },
  "customPolicy": {
    object (Guardrail.LlmPolicy)
  }
  // End of mutually exclusive fields.
}
Felder
failOpen

boolean

Optional. Bestimmt das Verhalten, wenn die Schutzmaßnahme auf einen LLM-Fehler stößt. – Wenn „true“: Die Schutzmaßnahme wird umgangen. – Wenn „false“ (Standard): Die Guardrail wird ausgelöst/blockiert.

Hinweis: Wenn eine benutzerdefinierte Richtlinie angegeben wird, wird dieses Feld zugunsten der „failOpen“-Konfiguration der Richtlinie ignoriert.

Definiert den Sicherheitskonfigurationsmodus. Der Nutzer muss eine der folgenden Konfigurationen auswählen. Im Folgenden finden Sie eine Liste von Feldern, die sich gegenseitig ausschließen. In einer Antwort wird höchstens eines der Felder festgelegt:
defaultSettings

object (Guardrail.LlmPromptSecurity.DefaultSecuritySettings)

Optional. Verwenden Sie die vordefinierten Standardsicherheitseinstellungen des Systems. Wenn Sie diesen Modus auswählen möchten, fügen Sie der Anfrage eine leere „defaultSettings“-Nachricht hinzu. Das Feld „defaultPromptTemplate“ wird vom Server in der Antwort ausgefüllt.

customPolicy

object (Guardrail.LlmPolicy)

Optional. Verwenden Sie eine benutzerdefinierte LlmPolicy, um die Sicherheitsvorkehrung zu konfigurieren.

Ende der sich gegenseitig ausschließenden Felder.

Guardrail.LlmPromptSecurity.DefaultSecuritySettings

Konfiguration für die Standardsicherheitseinstellungen des Systems.

JSON-Darstellung
{
  "defaultPromptTemplate": string
}
Felder
defaultPromptTemplate

string

Nur Ausgabe. Die vom System verwendete Standard-Prompt-Vorlage. Dieses Feld dient nur zur Anzeige, damit der Nutzer sieht, welchen Prompt das System standardmäßig verwendet. Es ist OUTPUT_ONLY.

Guardrail.LlmPolicy

Guardrail, die die Unterhaltung blockiert, wenn die LLM-Antwort gemäß der LLM-Klassifizierung als Verstoß gegen die Richtlinie gilt.

JSON-Darstellung
{
  "maxConversationMessages": integer,
  "modelSettings": {
    object (ModelSettings)
  },
  "prompt": string,
  "policyScope": enum (Guardrail.LlmPolicy.PolicyScope),
  "failOpen": boolean,
  "allowShortUtterance": boolean
}
Felder
maxConversationMessages

integer

Optional. Beim Prüfen dieser Richtlinie werden die letzten „n“ Nachrichten in der Unterhaltung berücksichtigt. Wenn nicht festgelegt, wird der Standardwert 10 verwendet.

modelSettings

object (ModelSettings)

Optional. Modelleinstellungen

prompt

string

Erforderlich. Richtlinien-Prompt. Unterstützt Platzhalter für Sitzungsvariablen ({var}) sowie {agent_system_instruction}, um die aufgelösten Systemanweisungen des KI-Agenten einzufügen.

policyScope

enum (Guardrail.LlmPolicy.PolicyScope)

Erforderlich. Definiert, wann die Richtlinienprüfung während der Unterhaltung angewendet werden soll. Wenn die Richtlinie auf POLICY_SCOPE_UNSPECIFIED festgelegt ist, wird sie auf die Nutzereingabe angewendet. Wenn die Richtlinie auf die Antwort des KI-Agenten angewendet wird, kommt es zu einer zusätzlichen Latenz, bevor der KI-Agent antworten kann.

failOpen

boolean

Optional. Wenn während der Richtlinienprüfung ein Fehler auftritt, wird die Anfrage zugelassen und die Guardrail nicht ausgelöst.

allowShortUtterance

boolean

Optional. Standardmäßig wird die LLM-Richtlinienprüfung für kurze Äußerungen umgangen. Wenn Sie diese Einstellung aktivieren, wird die Richtlinienprüfung auf alle Äußerungen angewendet, auch auf solche, die normalerweise übersprungen werden.

Guardrail.LlmPolicy.PolicyScope

Definiert, wann die Richtlinienprüfung während der Unterhaltung angewendet werden soll.

Enums
POLICY_SCOPE_UNSPECIFIED Der Richtlinienbereich ist nicht angegeben.
USER_QUERY Die Richtlinienprüfung wird durch Nutzereingaben ausgelöst.
AGENT_RESPONSE Die Richtlinienprüfung wird bei der Antwort des KI-Agenten ausgelöst. Wenn Sie diesen Richtlinienbereich anwenden, kommt es zu zusätzlicher Latenz, bevor der Agent antworten kann.
USER_QUERY_AND_AGENT_RESPONSE Die Richtlinienprüfung wird sowohl bei Nutzereingaben als auch bei Antworten des KI-Agenten ausgelöst. Wenn Sie diesen Richtlinienbereich anwenden, kommt es zu zusätzlicher Latenz, bevor der Agent antworten kann.

Guardrail.ModelSafety

Überschreibungen der Modellsicherheitseinstellungen. Wenn diese Option festgelegt ist, werden die Standardeinstellungen überschrieben und die Schutzmaßnahme wird ausgelöst, wenn die Antwort als unsicher eingestuft wird.

JSON-Darstellung
{
  "safetySettings": [
    {
      object (Guardrail.ModelSafety.SafetySetting)
    }
  ]
}
Felder
safetySettings[]

object (Guardrail.ModelSafety.SafetySetting)

Erforderlich. Liste der Sicherheitseinstellungen.

Guardrail.ModelSafety.SafetySetting

Sicherheitseinstellung.

JSON-Darstellung
{
  "category": enum (Guardrail.ModelSafety.HarmCategory),
  "threshold": enum (Guardrail.ModelSafety.HarmBlockThreshold)
}
Felder
category

enum (Guardrail.ModelSafety.HarmCategory)

Erforderlich. Die Schadenskategorie.

threshold

enum (Guardrail.ModelSafety.HarmBlockThreshold)

Erforderlich. Der Schwellenwert für die Schadensblockierung

Guardrail.ModelSafety.HarmCategory

Schadenskategorie

Enums
HARM_CATEGORY_UNSPECIFIED Die Schadenskategorie ist nicht angegeben.
HARM_CATEGORY_HATE_SPEECH Die Schadenskategorie ist Hassrede.
HARM_CATEGORY_DANGEROUS_CONTENT Die Schadenskategorie ist gefährlicher Inhalt.
HARM_CATEGORY_HARASSMENT Die Schadenskategorie ist Belästigung.
HARM_CATEGORY_SEXUALLY_EXPLICIT Die Schadenskategorie umfasst sexuell anstößige Inhalte.
HARM_CATEGORY_PROFANITY Die Schadenskategorie ist vulgäre Sprache.
HARM_CATEGORY_TOXIC Die Schadenskategorie ist „toxisch“.

Guardrail.ModelSafety.HarmBlockThreshold

Wahrscheinlichkeitsbasierte Schwellenwertebenen für die Blockierung

Enums
HARM_BLOCK_THRESHOLD_UNSPECIFIED Unbekannter Schwellenwert für die Schadensblockierung
BLOCK_LOW_AND_ABOVE Niedrigen Schwellenwert und höher blockieren (d. h. mehr blockieren)
BLOCK_MEDIUM_AND_ABOVE Mittleren Schwellenwert und höher blockieren
BLOCK_ONLY_HIGH Nur einen hohen Schwellenwert blockieren (d. h. weniger blockieren)
BLOCK_NONE Nichts blockieren
OFF Sicherheitsfilter deaktivieren

Guardrail.CodeCallback

Guardrail, die die Unterhaltung basierend auf den bereitgestellten Code-Callbacks blockiert.

JSON-Darstellung
{
  "beforeAgentCallback": {
    object (Callback)
  },
  "afterAgentCallback": {
    object (Callback)
  },
  "beforeModelCallback": {
    object (Callback)
  },
  "afterModelCallback": {
    object (Callback)
  }
}
Felder
beforeAgentCallback

object (Callback)

Optional. Der Callback, der vor dem Aufruf des KI-Agenten ausgeführt werden soll. Jede Callback-Funktion muss eine Struktur (z.B. ein Wörterbuch oder ein Objekt) zurückgeben, die mindestens Folgendes enthält: - „decision“: Entweder „OK“ oder „TRIGGER“. - 'reason': Ein String, der die Entscheidung erklärt. Eine „TRIGGER“-Entscheidung kann die weitere Verarbeitung stoppen.

afterAgentCallback

object (Callback)

Optional. Der Callback, der nach dem Aufruf des KI-Agenten ausgeführt werden soll. Jede Callback-Funktion muss eine Struktur (z.B. ein Wörterbuch oder ein Objekt) zurückgeben, die mindestens Folgendes enthält: - „decision“: Entweder „OK“ oder „TRIGGER“. - 'reason': Ein String, der die Entscheidung erklärt. Eine „TRIGGER“-Entscheidung kann die weitere Verarbeitung stoppen.

beforeModelCallback

object (Callback)

Optional. Der Callback, der vor dem Aufruf des Modells ausgeführt werden soll. Wenn das Modell mehrmals aufgerufen wird, wird der Callback mehrmals ausgeführt. Jede Callback-Funktion muss eine Struktur (z.B. ein Wörterbuch oder ein Objekt) zurückgeben, die mindestens Folgendes enthält: - „decision“: Entweder „OK“ oder „TRIGGER“. - 'reason': Ein String, der die Entscheidung erklärt. Eine „TRIGGER“-Entscheidung kann die weitere Verarbeitung stoppen.

afterModelCallback

object (Callback)

Optional. Der Callback, der nach dem Aufruf des Modells ausgeführt werden soll. Wenn das Modell mehrmals aufgerufen wird, wird der Callback mehrmals ausgeführt. Jede Callback-Funktion muss eine Struktur (z.B. ein Wörterbuch oder ein Objekt) zurückgeben, die mindestens Folgendes enthält: - „decision“: Entweder „OK“ oder „TRIGGER“. - 'reason': Ein String, der die Entscheidung erklärt. Eine „TRIGGER“-Entscheidung kann die weitere Verarbeitung stoppen.

Guardrail.Supervisor

Schutzmaßnahme, die eine Supervisor-Intervention ausführt.

JSON-Darstellung
{
  "type": enum (Guardrail.Supervisor.Type),
  "detectionMode": enum (Guardrail.Supervisor.DetectionMode)
}
Felder
type

enum (Guardrail.Supervisor.Type)

Optional. Der Typ des Supervisors.

detectionMode

enum (Guardrail.Supervisor.DetectionMode)

Optional. Der Erkennungsmodus des Supervisors.

Guardrail.Supervisor.Type

Typ des Supervisors.

Enums
TYPE_UNSPECIFIED Typ ist nicht angegeben.
INVALID_TEXT Ungültiger Problemtyp für Text.
LANGUAGE_SHIFT Problemtyp „Sprachwechsel“
SPEAKER_SHIFT Problemtyp „Sprecherwechsel“.
AUDIO_MISMATCH Problemtyp „Audio stimmt nicht überein“.
MISSING_TOOL_CALL Fehlender Problemtyp für Toolaufruf.
CUSTOM Benutzerdefinierter Problemtyp.
CHOPPY_AUDIO Problemtyp „Abgehackte Übertragung“.
PROFANITY Art des Problems mit vulgärer Sprache des KI-Agenten.

Guardrail.Supervisor.DetectionMode

Erkennungsmodus des Supervisors.

Enums
DETECTION_MODE_UNSPECIFIED Der Erkennungsmodus ist nicht angegeben. Die Standardeinstellung ist NON_BLOCKING.
NON_BLOCKING Nicht blockierender Erkennungsmodus. Die Antwort wird nicht blockiert, während die Supervisor-Erkennung läuft.
BLOCKING Blockierender Erkennungsmodus. Die Antwort wird blockiert, wenn die Supervisor-Erkennung läuft.

TriggerAction

Aktion, die ausgeführt wird, wenn eine bestimmte Vorbedingung erfüllt ist.

JSON-Darstellung
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "respondImmediately": {
    object (TriggerAction.RespondImmediately)
  },
  "transferAgent": {
    object (TriggerAction.TransferAgent)
  },
  "generativeAnswer": {
    object (TriggerAction.GenerativeAnswer)
  }
  // End of mutually exclusive fields.
}
Felder
Die erforderliche Aktion. Im Folgenden finden Sie eine Liste von Feldern, die sich gegenseitig ausschließen. In einer Antwort wird höchstens eines der Felder festgelegt:
respondImmediately

object (TriggerAction.RespondImmediately)

Optional. Sofort mit einer vorkonfigurierten Antwort reagieren.

transferAgent

object (TriggerAction.TransferAgent)

Optional. Leiten Sie die Unterhaltung an einen anderen Kundenservicemitarbeiter weiter.

generativeAnswer

object (TriggerAction.GenerativeAnswer)

Optional. Mit einer generativen Antwort antworten.

Ende der sich gegenseitig ausschließenden Felder.

TriggerAction.RespondImmediately

Der KI-Agent antwortet sofort mit einer vorkonfigurierten Antwort.

JSON-Darstellung
{
  "responses": [
    {
      object (TriggerAction.Response)
    }
  ]
}
Felder
responses[]

object (TriggerAction.Response)

Erforderlich. Die Antwortvorlagen, aus denen der Agent auswählen kann. Die Antwort wird zufällig ausgewählt.

TriggerAction.Response

Stellt eine Antwort des KI-Agenten dar.

JSON-Darstellung
{
  "text": string,
  "disabled": boolean
}
Felder
text

string

Erforderlich. Text, mit dem der Agent antworten soll.

disabled

boolean

Optional. Gibt an, ob die Antwort deaktiviert ist. Deaktivierte Antworten werden vom Agenten nicht verwendet.

TriggerAction.TransferAgent

Der Kundenservicemitarbeiter leitet die Unterhaltung an einen anderen Kundenservicemitarbeiter weiter.

JSON-Darstellung
{
  "agent": string
}
Felder
agent

string

Erforderlich. Der Name des KI-Agenten, an den die Unterhaltung übertragen werden soll. Der Agent muss sich in derselben Anwendung wie der aktuelle Agent befinden. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}

TriggerAction.GenerativeAnswer

Der KI-Agent antwortet sofort mit einer generativen Antwort.

JSON-Darstellung
{
  "prompt": string
}
Felder
prompt

string

Erforderlich. Der Prompt, der für die generative Antwort verwendet werden soll.

Methoden

create

Erstellt eine neue Schutzmaßnahme in der angegebenen Anwendung.

delete

Löscht die angegebene Schutzmaßnahme.

get

Ruft Details zur angegebenen Schutzmaßnahme ab.

list

Listet Schutzmaßnahmen in der angegebenen Anwendung auf.

patch

Aktualisiert die angegebene Schutzmaßnahme.