REST Resource: projects.locations.apps.guardrails

Risorsa: Guardrail

La barriera di protezione contiene un elenco di controlli e bilanciamenti per mantenere gli agenti al sicuro.

Rappresentazione JSON
{
  "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.
}
Campi
name

string

Identificatore. L'identificatore univoco della regola di sicurezza. Formato: projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}

displayName

string

Obbligatorio. Nome visualizzato del guardrail.

description

string

Facoltativo. Descrizione della guardrail.

enabled

boolean

Facoltativo. Indica se il guardrail è abilitato.

action

object (TriggerAction)

Facoltativo. Azione da intraprendere quando viene attivato il guardrail.

createTime

string (Timestamp format)

Solo output. Timestamp della creazione della regola di protezione.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

updateTime

string (Timestamp format)

Solo output. Timestamp dell'ultimo aggiornamento della regola di protezione.

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

etag

string

Etag utilizzato per garantire che l'oggetto non sia cambiato durante un'operazione di lettura, modifica e scrittura. Se l'etag è vuoto, l'aggiornamento sovrascriverà eventuali modifiche simultanee.

Tipo di guardrail. Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
contentFilter

object (Guardrail.ContentFilter)

Facoltativo. Guardrail che vieta l'utilizzo di determinati contenuti nella conversazione.

llmPromptSecurity

object (Guardrail.LlmPromptSecurity)

Facoltativo. Guardrail che blocca la conversazione se il prompt è considerato non sicuro in base alla classificazione dell'LLM.

llmPolicy

object (Guardrail.LlmPolicy)

Facoltativo. Guardrail che blocca la conversazione se la risposta dell'LLM è considerata in violazione della policy in base alla classificazione dell'LLM.

modelSafety

object (Guardrail.ModelSafety)

Facoltativo. Guardrail che blocca la conversazione se la risposta dell'LLM è considerata non sicura in base alle impostazioni di sicurezza del modello.

codeCallback

object (Guardrail.CodeCallback)

Facoltativo. Guardrail che blocca potenzialmente la conversazione in base al risultato dell'esecuzione del callback.

supervisor

object (Guardrail.Supervisor)

Facoltativo. Guardrail che esegue l'intervento del supervisore.

Fine dei campi che si escludono a vicenda.

Guardrail.ContentFilter

Guardrail che vieta l'utilizzo di determinati contenuti nella conversazione.

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

string

Facoltativo. Elenco di frasi vietate. Si applica sia agli input degli utenti sia alle risposte degli agenti.

bannedContentsInUserInput[]

string

Facoltativo. Elenco di frasi vietate. Si applica solo agli input degli utenti.

bannedContentsInAgentResponse[]

string

Facoltativo. Elenco di frasi vietate. Si applica solo alle risposte degli agenti.

matchType

enum (Guardrail.ContentFilter.MatchType)

Obbligatorio. Tipo di corrispondenza per il filtro dei contenuti.

disregardDiacritics

boolean

Facoltativo. Se impostato su true, i segni diacritici vengono ignorati durante la ricerca di corrispondenze.

sensitiveWordsExemptions[]

string

Facoltativo. Voci dell'elenco di parole sensibili consentite da questo guardrail. Valido solo quando matchType è SENSITIVE_WORDS. Ogni valore deve corrispondere a una voce dell'elenco (senza distinzione tra maiuscole e minuscole, gli spazi vuoti circostanti vengono ignorati); altri valori non hanno alcun effetto. Si applica solo a questa regola di sicurezza. Massimo 1000 voci di massimo 256 caratteri ciascuna.

Guardrail.ContentFilter.MatchType

Tipo di corrispondenza per il filtro dei contenuti.

Enum
MATCH_TYPE_UNSPECIFIED Il tipo di corrispondenza non è specificato.
SIMPLE_STRING_MATCH I contenuti vengono confrontati con le sottostringhe carattere per carattere.
WORD_BOUNDARY_STRING_MATCH I contenuti corrispondono solo se il pattern trovato nel testo è circondato da delimitatori di parole. Le frasi vietate possono contenere anche delimitatori di parole.
REGEXP_MATCH I contenuti vengono abbinati utilizzando la sintassi delle espressioni regolari.
SENSITIVE_WORDS I contenuti vengono confrontati con un elenco di parole e frasi sensibili gestito dal sistema. Se colleghi un guardrail con questo tipo di corrispondenza a un'app o a un agente, il filtro predefinito per le parole sensibili viene sostituito per gli agenti interessati. Disattiva il guardrail per disattivare il filtro predefinito.

Guardrail.LlmPromptSecurity

Guardrail che blocca la conversazione se l'input è considerato non sicuro in base alla classificazione dell'LLM.

Rappresentazione JSON
{
  "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.
}
Campi
failOpen

boolean

Facoltativo. Determina il comportamento quando la barriera di protezione rileva un errore LLM. - Se true: il guardrail viene ignorato. - Se il valore è false (predefinito): il guardrail si attiva/blocca.

Nota: se viene fornita una policy personalizzata, questo campo viene ignorato a favore della configurazione "failOpen" della policy.

Definisce la modalità di configurazione della sicurezza. L'utente deve scegliere una delle seguenti configurazioni. Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
defaultSettings

object (Guardrail.LlmPromptSecurity.DefaultSecuritySettings)

Facoltativo. Utilizza le impostazioni di sicurezza predefinite del sistema. Per selezionare questa modalità, includi un messaggio "defaultSettings" vuoto nella richiesta. Il campo "defaultPromptTemplate" all'interno verrà compilato dal server nella risposta.

customPolicy

object (Guardrail.LlmPolicy)

Facoltativo. Utilizza un LlmPolicy definito dall'utente per configurare il guardrail di sicurezza.

Fine dei campi che si escludono a vicenda.

Guardrail.LlmPromptSecurity.DefaultSecuritySettings

Configurazione delle impostazioni di sicurezza predefinite del sistema.

Rappresentazione JSON
{
  "defaultPromptTemplate": string
}
Campi
defaultPromptTemplate

string

Solo output. Il template di prompt predefinito utilizzato dal sistema. Questo campo serve per mostrare all'utente il prompt utilizzato dal sistema per impostazione predefinita. È OUTPUT_ONLY.

Guardrail.LlmPolicy

Guardrail che blocca la conversazione se la risposta dell'LLM è considerata in violazione della policy in base alla classificazione dell'LLM.

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

integer

Facoltativo. Quando controlli questa policy, considera gli ultimi "n" messaggi della conversazione. Se non viene impostato, verrà utilizzato il valore predefinito 10.

modelSettings

object (ModelSettings)

Facoltativo. Impostazioni del modello.

prompt

string

Obbligatorio. Prompt delle norme. Supporta i segnaposto delle variabili di sessione ({var}) e {agent_system_instruction} per inserire le istruzioni di sistema risolte dell'agente.

policyScope

enum (Guardrail.LlmPolicy.PolicyScope)

Obbligatorio. Definisce quando applicare il controllo delle policy durante la conversazione. Se impostata su POLICY_SCOPE_UNSPECIFIED, la policy verrà applicata all'input utente. Quando applichi la policy alla risposta dell'agente, verrà introdotta una latenza aggiuntiva prima che l'agente possa rispondere.

failOpen

boolean

Facoltativo. Se si verifica un errore durante il controllo della policy, l'operazione non va a buon fine e il guardrail non viene attivato.

allowShortUtterance

boolean

Facoltativo. Per impostazione predefinita, il controllo delle policy LLM viene ignorato per gli enunciati brevi. Se attivi questa impostazione, il controllo delle policy viene applicato a tutti gli enunciati, inclusi quelli che normalmente verrebbero ignorati.

Guardrail.LlmPolicy.PolicyScope

Definisce quando applicare il controllo delle policy durante la conversazione.

Enum
POLICY_SCOPE_UNSPECIFIED L'ambito della policy non è specificato.
USER_QUERY Il controllo delle norme viene attivato in base all'input utente.
AGENT_RESPONSE Il controllo delle policy viene attivato in base alla risposta dell'agente. L'applicazione di questo ambito della policy introdurrà una latenza aggiuntiva prima che l'agente possa rispondere.
USER_QUERY_AND_AGENT_RESPONSE Il controllo delle policy viene attivato sia sull'input utente dell'utente che sulla risposta dell'agente. L'applicazione di questo ambito della policy introdurrà una latenza aggiuntiva prima che l'agente possa rispondere.

Guardrail.ModelSafety

Override delle impostazioni di sicurezza del modello. Se impostata, questa opzione sostituisce le impostazioni predefinite e attiva il guardrail se la risposta è considerata non sicura.

Rappresentazione JSON
{
  "safetySettings": [
    {
      object (Guardrail.ModelSafety.SafetySetting)
    }
  ]
}
Campi
safetySettings[]

object (Guardrail.ModelSafety.SafetySetting)

Obbligatorio. Elenco delle impostazioni di sicurezza.

Guardrail.ModelSafety.SafetySetting

Impostazione di sicurezza.

Rappresentazione JSON
{
  "category": enum (Guardrail.ModelSafety.HarmCategory),
  "threshold": enum (Guardrail.ModelSafety.HarmBlockThreshold)
}
Campi
category

enum (Guardrail.ModelSafety.HarmCategory)

Obbligatorio. La categoria di danno.

threshold

enum (Guardrail.ModelSafety.HarmBlockThreshold)

Obbligatorio. La soglia di blocco dei contenuti dannosi.

Guardrail.ModelSafety.HarmCategory

Categoria di danno.

Enum
HARM_CATEGORY_UNSPECIFIED La categoria di danno non è specificata.
HARM_CATEGORY_HATE_SPEECH La categoria di danno è l'incitamento all'odio.
HARM_CATEGORY_DANGEROUS_CONTENT La categoria di danno è Contenuti pericolosi.
HARM_CATEGORY_HARASSMENT La categoria di danno è molestie.
HARM_CATEGORY_SEXUALLY_EXPLICIT La categoria di danno è contenuti sessualmente espliciti.
HARM_CATEGORY_PROFANITY La categoria di danno è il linguaggio volgare.
HARM_CATEGORY_TOXIC La categoria di danno è tossica.

Guardrail.ModelSafety.HarmBlockThreshold

Livelli di soglia basati sulla probabilità per il blocco.

Enum
HARM_BLOCK_THRESHOLD_UNSPECIFIED Soglia di blocco dei contenuti dannosi non specificata.
BLOCK_LOW_AND_ABOVE Blocca soglia bassa e superiore (ovvero blocca più contenuti).
BLOCK_MEDIUM_AND_ABOVE Blocca soglia media e superiore.
BLOCK_ONLY_HIGH Blocco solo soglia alta (ovvero blocco ridotto).
BLOCK_NONE Nessun blocco.
OFF Disattiva il filtro di sicurezza.

Guardrail.CodeCallback

Guardrail che blocca la conversazione in base ai callback di codice forniti.

Rappresentazione JSON
{
  "beforeAgentCallback": {
    object (Callback)
  },
  "afterAgentCallback": {
    object (Callback)
  },
  "beforeModelCallback": {
    object (Callback)
  },
  "afterModelCallback": {
    object (Callback)
  }
}
Campi
beforeAgentCallback

object (Callback)

Facoltativo. Il callback da eseguire prima della chiamata dell'agente. Ogni funzione di callback deve restituire una struttura (ad es. un dizionario o un oggetto) contenente almeno: - "decision": "OK" o "TRIGGER". - "reason": una stringa che spiega la decisione. Una decisione "TRIGGER" potrebbe interrompere l'ulteriore elaborazione.

afterAgentCallback

object (Callback)

Facoltativo. Il callback da eseguire dopo la chiamata dell'agente. Ogni funzione di callback deve restituire una struttura (ad es. un dizionario o un oggetto) contenente almeno: - "decision": "OK" o "TRIGGER". - "reason": una stringa che spiega la decisione. Una decisione "TRIGGER" potrebbe interrompere l'ulteriore elaborazione.

beforeModelCallback

object (Callback)

Facoltativo. Il callback da eseguire prima della chiamata del modello. Se il modello viene chiamato più volte, il callback verrà eseguito più volte. Ogni funzione di callback deve restituire una struttura (ad es. un dict o un oggetto) contenente almeno: - "decision": "OK" o "TRIGGER". - "reason": una stringa che spiega la decisione. Una decisione "TRIGGER" potrebbe interrompere l'ulteriore elaborazione.

afterModelCallback

object (Callback)

Facoltativo. Il callback da eseguire dopo la chiamata del modello. Se il modello viene chiamato più volte, il callback verrà eseguito più volte. Ogni funzione di callback deve restituire una struttura (ad es. un dizionario o un oggetto) contenente almeno: - "decision": "OK" o "TRIGGER". - "reason": una stringa che spiega la decisione. Una decisione "TRIGGER" potrebbe interrompere l'ulteriore elaborazione.

Guardrail.Supervisor

Guardrail che esegue l'intervento del supervisore.

Rappresentazione JSON
{
  "type": enum (Guardrail.Supervisor.Type),
  "detectionMode": enum (Guardrail.Supervisor.DetectionMode)
}
Campi
type

enum (Guardrail.Supervisor.Type)

Facoltativo. Il tipo di supervisore.

detectionMode

enum (Guardrail.Supervisor.DetectionMode)

Facoltativo. La modalità di rilevamento del supervisore.

Guardrail.Supervisor.Type

Tipo di supervisore.

Enum
TYPE_UNSPECIFIED Il tipo non è specificato.
INVALID_TEXT Tipo di problema di testo non valido.
LANGUAGE_SHIFT Tipo di problema relativo al cambio di lingua.
SPEAKER_SHIFT Tipo di problema di spostamento dello speaker.
AUDIO_MISMATCH Tipo di problema di mancata corrispondenza audio.
MISSING_TOOL_CALL Tipo di problema di chiamata allo strumento mancante.
CUSTOM Tipo di problema personalizzato.
CHOPPY_AUDIO Tipo di problema: audio frammentato.
PROFANITY Tipo di problema relativo al linguaggio volgare dell'agente.

Guardrail.Supervisor.DetectionMode

Modalità di rilevamento del supervisore.

Enum
DETECTION_MODE_UNSPECIFIED La modalità di rilevamento non è specificata. Il valore predefinito è NON_BLOCKING.
NON_BLOCKING Modalità di rilevamento non bloccante. La risposta non viene bloccata quando è in corso il rilevamento del supervisore.
BLOCKING Modalità di rilevamento del blocco. La risposta viene bloccata quando è in corso il rilevamento del supervisore.

TriggerAction

Azione eseguita quando viene soddisfatta una determinata precondizione.

Rappresentazione JSON
{

  // 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.
}
Campi
L'azione da eseguire. Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
respondImmediately

object (TriggerAction.RespondImmediately)

Facoltativo. Rispondi immediatamente con una risposta preconfigurata.

transferAgent

object (TriggerAction.TransferAgent)

Facoltativo. Trasferire la conversazione a un altro agente.

generativeAnswer

object (TriggerAction.GenerativeAnswer)

Facoltativo. Rispondi con una risposta generativa.

Fine dei campi che si escludono a vicenda.

TriggerAction.RespondImmediately

L'agente risponderà immediatamente con una risposta preconfigurata.

Rappresentazione JSON
{
  "responses": [
    {
      object (TriggerAction.Response)
    }
  ]
}
Campi
responses[]

object (TriggerAction.Response)

Obbligatorio. Le risposte predefinite tra cui l'agente può scegliere. La risposta viene scelta in modo casuale.

TriggerAction.Response

Rappresenta una risposta dell'agente.

Rappresentazione JSON
{
  "text": string,
  "disabled": boolean
}
Campi
text

string

Obbligatorio. Testo con cui l'agente deve rispondere.

disabled

boolean

Facoltativo. Indica se la risposta è disattivata. Le risposte disattivate non vengono utilizzate dall'agente.

TriggerAction.TransferAgent

L'agente trasferirà la conversazione a un altro agente.

Rappresentazione JSON
{
  "agent": string
}
Campi
agent

string

Obbligatorio. Il nome dell'agente a cui trasferire la conversazione. L'agente deve trovarsi nella stessa app dell'agente corrente. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}

TriggerAction.GenerativeAnswer

L'agente risponderà immediatamente con una risposta generativa.

Rappresentazione JSON
{
  "prompt": string
}
Campi
prompt

string

Obbligatorio. Il prompt da utilizzare per la risposta generativa.

Metodi

create

Crea un nuovo guardrail nell'app specificata.

delete

Elimina la barriera di sicurezza specificata.

get

Recupera i dettagli della risorsa guardrail specificata.

list

Elenca i guardrail nell'app specificata.

patch

Aggiorna la protezione specificata.