REST Resource: projects.locations.apps.guardrails

Recurso: Guardrail

La barrera de seguridad contiene una lista de verificaciones y balances para mantener a los agentes seguros.

Representación 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.
}
Campos
name

string

Es el identificador. Es el identificador único de la barandilla de seguridad. Formato: projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}

displayName

string

Obligatorio. Es el nombre visible de la barandilla.

description

string

Es opcional. Descripción de la barrera de seguridad.

enabled

boolean

Es opcional. Indica si la barandilla está habilitada.

action

object (TriggerAction)

Es opcional. Es la acción que se debe realizar cuando se activa la barrera de protección.

createTime

string (Timestamp format)

Solo salida. Es la marca de tiempo de la creación de la barandilla de seguridad.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

updateTime

string (Timestamp format)

Solo salida. Marca de tiempo de la última actualización de la barandilla.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

etag

string

Es la etiqueta de entidad que se usa para garantizar que el objeto no haya cambiado durante una operación de lectura, modificación y escritura. Si la etag está vacía, la actualización reemplazará cualquier cambio simultáneo.

Es el tipo de barrera de seguridad. La siguiente es una lista de campos mutuamente excluyentes. Como máximo, se establecerá uno de los campos en una respuesta:
contentFilter

object (Guardrail.ContentFilter)

Es opcional. Es una barrera que prohíbe que se use cierto contenido en la conversación.

llmPromptSecurity

object (Guardrail.LlmPromptSecurity)

Es opcional. Es una protección que bloquea la conversación si la instrucción se considera no segura según la clasificación del LLM.

llmPolicy

object (Guardrail.LlmPolicy)

Es opcional. Es la barrera que bloquea la conversación si se considera que la respuesta del LLM incumple la política según la clasificación del LLM.

modelSafety

object (Guardrail.ModelSafety)

Es opcional. Es una protección que bloquea la conversación si la respuesta del LLM se considera no segura según la configuración de seguridad del modelo.

codeCallback

object (Guardrail.CodeCallback)

Es opcional. Es una barrera de protección que puede bloquear la conversación según el resultado de la ejecución de la devolución de llamada.

supervisor

object (Guardrail.Supervisor)

Es opcional. Es la protección que ejecuta la intervención del supervisor.

Fin de los campos mutuamente excluyentes.

Guardrail.ContentFilter

Es una barrera que prohíbe que se use cierto contenido en la conversación.

Representación JSON
{
  "bannedContents": [
    string
  ],
  "bannedContentsInUserInput": [
    string
  ],
  "bannedContentsInAgentResponse": [
    string
  ],
  "matchType": enum (Guardrail.ContentFilter.MatchType),
  "disregardDiacritics": boolean,
  "sensitiveWordsExemptions": [
    string
  ]
}
Campos
bannedContents[]

string

Es opcional. Lista de frases prohibidas. Se aplica tanto a las entradas del usuario como a las respuestas del agente.

bannedContentsInUserInput[]

string

Es opcional. Lista de frases prohibidas. Solo se aplica a las entradas de los usuarios.

bannedContentsInAgentResponse[]

string

Es opcional. Lista de frases prohibidas. Solo se aplica a las respuestas del agente.

matchType

enum (Guardrail.ContentFilter.MatchType)

Obligatorio. Es el tipo de concordancia del filtro de contenido.

disregardDiacritics

boolean

Es opcional. Si es verdadero, se ignoran los signos diacríticos durante la coincidencia.

sensitiveWordsExemptions[]

string

Es opcional. Son las entradas de la lista de palabras sensibles que permite esta barandilla de seguridad. Solo es válido cuando matchType es SENSITIVE_WORDS. Cada valor debe ser igual a una entrada de la lista (no distingue mayúsculas de minúsculas, se ignoran los espacios en blanco circundantes); los demás valores no tienen efecto. Se aplica solo a esta barandilla de seguridad. Un máximo de 1,000 entradas de hasta 256 caracteres cada una.

Guardrail.ContentFilter.MatchType

Es el tipo de concordancia del filtro de contenido.

Enums
MATCH_TYPE_UNSPECIFIED No se especificó el tipo de concordancia.
SIMPLE_STRING_MATCH El contenido se compara con las subcadenas carácter por carácter.
WORD_BOUNDARY_STRING_MATCH El contenido solo coincide si el patrón que se encuentra en el texto está rodeado de delimitadores de palabras. Las frases prohibidas también pueden contener delimitadores de palabras.
REGEXP_MATCH El contenido se compara con la sintaxis de expresiones regulares.
SENSITIVE_WORDS El contenido se compara con una lista de palabras y frases sensibles administrada por el sistema. Si adjuntas una barandilla con este tipo de coincidencia a una app o un agente, se reemplazará el filtro predeterminado de palabras sensibles para los agentes afectados. Inhabilita la barandilla para inhabilitar el filtro predeterminado.

Guardrail.LlmPromptSecurity

Es una protección que bloquea la conversación si la entrada se considera insegura según la clasificación del LLM.

Representación 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.
}
Campos
failOpen

boolean

Es opcional. Determina el comportamiento cuando la barrera de seguridad encuentra un error de LLM. - Si es verdadero, se omite la barrera de protección. - Si es falso (predeterminado), la barandilla se activa o bloquea.

Nota: Si se proporciona una política personalizada, este campo se ignora y se prioriza la configuración "failOpen" de la política.

Define el modo de configuración de seguridad. El usuario debe elegir una de las siguientes opciones de configuración. La siguiente es una lista de campos mutuamente excluyentes. Como máximo, se establecerá uno de los campos en una respuesta:
defaultSettings

object (Guardrail.LlmPromptSecurity.DefaultSecuritySettings)

Es opcional. Usa la configuración de seguridad predeterminada del sistema. Para seleccionar este modo, incluye un mensaje "defaultSettings" vacío en la solicitud. El servidor completará el campo "defaultPromptTemplate" en la respuesta.

customPolicy

object (Guardrail.LlmPolicy)

Es opcional. Usa una LlmPolicy definida por el usuario para configurar la barrera de seguridad.

Fin de los campos mutuamente excluyentes.

Guardrail.LlmPromptSecurity.DefaultSecuritySettings

Configuración de los parámetros de seguridad predeterminados del sistema.

Representación JSON
{
  "defaultPromptTemplate": string
}
Campos
defaultPromptTemplate

string

Solo salida. Es la plantilla de instrucciones predeterminada que usa el sistema. Este campo tiene fines de visualización para mostrarle al usuario qué instrucción usa el sistema de forma predeterminada. Es OUTPUT_ONLY.

Guardrail.LlmPolicy

Es la barrera que bloquea la conversación si se considera que la respuesta del LLM incumple la política según la clasificación del LLM.

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

integer

Es opcional. Cuando verifiques esta política, considera los últimos "n" mensajes de la conversación. Si no se establece, se usará un valor predeterminado de 10.

modelSettings

object (ModelSettings)

Es opcional. Configuración del modelo

prompt

string

Obligatorio. Mensaje de política. Admite marcadores de posición de variables de sesión ({var}), así como {agent_system_instruction} para insertar las instrucciones del sistema resueltas del agente.

policyScope

enum (Guardrail.LlmPolicy.PolicyScope)

Obligatorio. Define cuándo aplicar la verificación de la política durante la conversación. Si se establece en POLICY_SCOPE_UNSPECIFIED, la política se aplicará a la entrada del usuario. Cuando se aplique la política a la respuesta del agente, se introducirá una latencia adicional antes de que el agente pueda responder.

failOpen

boolean

Es opcional. Si se produce un error durante la verificación de la política, se produce un error de apertura y no se activa la barandilla.

allowShortUtterance

boolean

Es opcional. De forma predeterminada, la verificación de la política de LLM se omite para las expresiones cortas. Si habilitas este parámetro de configuración, se aplicará la verificación de políticas a todas las expresiones, incluidas las que normalmente se omitirían.

Guardrail.LlmPolicy.PolicyScope

Define cuándo aplicar la verificación de la política durante la conversación.

Enums
POLICY_SCOPE_UNSPECIFIED No se especificó el permiso de la política.
USER_QUERY La verificación de políticas se activa con la entrada del usuario.
AGENT_RESPONSE La verificación de políticas se activa en la respuesta del agente. Aplicar este permiso de política generará latencia adicional antes de que el agente pueda responder.
USER_QUERY_AND_AGENT_RESPONSE La verificación de políticas se activa tanto en la entrada del usuario como en la respuesta del agente. Aplicar este permiso de política generará latencia adicional antes de que el agente pueda responder.

Guardrail.ModelSafety

Anulaciones de la configuración de seguridad del modelo. Cuando se establece, se anula la configuración predeterminada y se activa la barandilla si la respuesta se considera no segura.

Representación JSON
{
  "safetySettings": [
    {
      object (Guardrail.ModelSafety.SafetySetting)
    }
  ]
}
Campos
safetySettings[]

object (Guardrail.ModelSafety.SafetySetting)

Obligatorio. Lista de parámetros de configuración de seguridad.

Guardrail.ModelSafety.SafetySetting

Configuración de seguridad.

Representación JSON
{
  "category": enum (Guardrail.ModelSafety.HarmCategory),
  "threshold": enum (Guardrail.ModelSafety.HarmBlockThreshold)
}
Campos
category

enum (Guardrail.ModelSafety.HarmCategory)

Obligatorio. La categoría de daño.

threshold

enum (Guardrail.ModelSafety.HarmBlockThreshold)

Obligatorio. El umbral de bloqueo de daño.

Guardrail.ModelSafety.HarmCategory

Categoría de daño.

Enums
HARM_CATEGORY_UNSPECIFIED No se especifica la categoría de daño.
HARM_CATEGORY_HATE_SPEECH La categoría de daño es la incitación al odio o a la violencia.
HARM_CATEGORY_DANGEROUS_CONTENT La categoría de daño es el contenido peligroso.
HARM_CATEGORY_HARASSMENT La categoría de daño es el hostigamiento.
HARM_CATEGORY_SEXUALLY_EXPLICIT La categoría de daño es el contenido sexual explícito.
HARM_CATEGORY_PROFANITY La categoría de daño es el lenguaje obsceno.
HARM_CATEGORY_TOXIC La categoría de daño es tóxica.

Guardrail.ModelSafety.HarmBlockThreshold

Niveles de umbral basados en la probabilidad para el bloqueo.

Enums
HARM_BLOCK_THRESHOLD_UNSPECIFIED Umbral de bloqueo de daño no especificado.
BLOCK_LOW_AND_ABOVE Bloquea el umbral bajo y superior (es decir, bloquea más).
BLOCK_MEDIUM_AND_ABOVE Bloquea el umbral medio y superior.
BLOCK_ONLY_HIGH Bloquea solo el umbral alto (es decir, bloquea menos).
BLOCK_NONE No bloquear.
OFF Desactiva el filtro de seguridad.

Guardrail.CodeCallback

Es la barrera que bloquea la conversación según las devoluciones de llamada de código proporcionadas.

Representación JSON
{
  "beforeAgentCallback": {
    object (Callback)
  },
  "afterAgentCallback": {
    object (Callback)
  },
  "beforeModelCallback": {
    object (Callback)
  },
  "afterModelCallback": {
    object (Callback)
  }
}
Campos
beforeAgentCallback

object (Callback)

Es opcional. Es la devolución de llamada que se ejecutará antes de que se llame al agente. Se espera que cada función de devolución de llamada devuelva una estructura (p.ej., un diccionario o un objeto) que contenga, al menos, lo siguiente: - 'decision': 'OK' o 'TRIGGER'. - "reason": Una cadena que explica la decisión. Una decisión de "ACTIVACIÓN" puede detener el procesamiento posterior.

afterAgentCallback

object (Callback)

Es opcional. Es la devolución de llamada que se ejecutará después de que se llame al agente. Se espera que cada función de devolución de llamada devuelva una estructura (p.ej., un diccionario o un objeto) que contenga, al menos, lo siguiente: - 'decision': 'OK' o 'TRIGGER'. - "reason": Una cadena que explica la decisión. Una decisión de "ACTIVACIÓN" puede detener el procesamiento posterior.

beforeModelCallback

object (Callback)

Es opcional. Es la devolución de llamada que se ejecutará antes de que se llame al modelo. Si hay varias llamadas al modelo, la devolución de llamada se ejecutará varias veces. Se espera que cada función de devolución de llamada devuelva una estructura (p.ej., un diccionario o un objeto) que contenga, al menos, lo siguiente: - 'decision': 'OK' o 'TRIGGER'. - "reason": Una cadena que explica la decisión. Una decisión de "ACTIVACIÓN" puede detener el procesamiento posterior.

afterModelCallback

object (Callback)

Es opcional. Es la devolución de llamada que se ejecutará después de que se llame al modelo. Si hay varias llamadas al modelo, la devolución de llamada se ejecutará varias veces. Se espera que cada función de devolución de llamada devuelva una estructura (p.ej., un diccionario o un objeto) que contenga, al menos, lo siguiente: - 'decision': 'OK' o 'TRIGGER'. - "reason": Una cadena que explica la decisión. Una decisión de "ACTIVACIÓN" puede detener el procesamiento posterior.

Guardrail.Supervisor

Es la protección que ejecuta la intervención del supervisor.

Representación JSON
{
  "type": enum (Guardrail.Supervisor.Type),
  "detectionMode": enum (Guardrail.Supervisor.DetectionMode)
}
Campos
type

enum (Guardrail.Supervisor.Type)

Es opcional. Es el tipo de supervisor.

detectionMode

enum (Guardrail.Supervisor.DetectionMode)

Es opcional. Es el modo de detección del supervisor.

Guardrail.Supervisor.Type

Es el tipo de supervisor.

Enums
TYPE_UNSPECIFIED El tipo no está especificado.
INVALID_TEXT Tipo de problema de texto no válido.
LANGUAGE_SHIFT Es el tipo de problema de cambio de idioma.
SPEAKER_SHIFT Es el tipo de problema de cambio de interlocutor.
AUDIO_MISMATCH Tipo de problema de discrepancia de audio.
MISSING_TOOL_CALL Falta el tipo de problema de llamada a la herramienta.
CUSTOM Tipo de problema personalizado.
CHOPPY_AUDIO Tipo de problema de audio entrecortado.
PROFANITY Es el tipo de problema de lenguaje obsceno del agente.

Guardrail.Supervisor.DetectionMode

Es el modo de detección del supervisor.

Enums
DETECTION_MODE_UNSPECIFIED No se especificó el modo de detección. El valor predeterminado es NON_BLOCKING.
NON_BLOCKING Modo de detección sin bloqueo. La respuesta no se bloquea cuando la detección del supervisor está en curso.
BLOCKING Modo de detección de bloqueo. La respuesta se bloquea cuando la detección del supervisor está en curso.

TriggerAction

Es la acción que se realiza cuando se cumple una condición previa determinada.

Representación 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.
}
Campos
La acción por realizar. La siguiente es una lista de campos mutuamente excluyentes. Como máximo, se establecerá uno de los campos en una respuesta:
respondImmediately

object (TriggerAction.RespondImmediately)

Es opcional. Responde de inmediato con una respuesta preconfigurada.

transferAgent

object (TriggerAction.TransferAgent)

Es opcional. Transferir la conversación a otro agente

generativeAnswer

object (TriggerAction.GenerativeAnswer)

Es opcional. Responder con una respuesta generativa

Fin de los campos mutuamente excluyentes.

TriggerAction.RespondImmediately

El agente responderá de inmediato con una respuesta preconfigurada.

Representación JSON
{
  "responses": [
    {
      object (TriggerAction.Response)
    }
  ]
}
Campos
responses[]

object (TriggerAction.Response)

Obligatorio. Son las respuestas estándares entre las que puede elegir el agente. La respuesta se elige de forma aleatoria.

TriggerAction.Response

Representa una respuesta del agente.

Representación JSON
{
  "text": string,
  "disabled": boolean
}
Campos
text

string

Obligatorio. Es el texto con el que debe responder el agente.

disabled

boolean

Es opcional. Indica si la respuesta está inhabilitada. El agente no usa las respuestas inhabilitadas.

TriggerAction.TransferAgent

El agente transferirá la conversación a otro agente.

Representación JSON
{
  "agent": string
}
Campos
agent

string

Obligatorio. Es el nombre del agente al que se transferirá la conversación. El agente debe estar en la misma app que el agente actual. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}

TriggerAction.GenerativeAnswer

El agente responderá de inmediato con una respuesta generativa.

Representación JSON
{
  "prompt": string
}
Campos
prompt

string

Obligatorio. Es la instrucción que se usará para la respuesta generativa.

Métodos

create

Crea una nueva barandilla en la app determinada.

delete

Borra la barandilla especificada.

get

Obtiene los detalles de la protección especificada.

list

Enumera las protecciones de la app determinada.

patch

Actualiza la barandilla especificada.