REST Resource: projects.locations.apps.guardrails

资源：Guardrail

保护措施包含一系列制衡机制，旨在确保智能体的安全。

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.
}
字段
name

string

标识符。安全屏障的唯一标识符。格式：projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}
displayName

string

必需。安全屏障的显示名称。
description

string

可选。安全护栏的说明。
enabled

boolean

可选。安全护栏是否已启用。
action

object (TriggerAction)

可选。触发保护措施时要采取的操作。
createTime

string (Timestamp format)

仅限输出。安全措施的创建时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime

string (Timestamp format)

仅限输出。上次更新安全措施时的时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
etag

string

用于确保对象在读取-修改-写入操作期间未发生更改的 ETag。如果 etag 为空，则更新会覆盖任何并发更改。
保护措施类型。以下是互斥字段的列表。在响应中，最多只能设置以下字段之一：
contentFilter

object (Guardrail.ContentFilter)

可选。禁止在对话中使用某些内容的护栏。
llmPromptSecurity

object (Guardrail.LlmPromptSecurity)

可选。如果根据 LLM 分类，提示被认为不安全，则阻止对话的防护措施。
llmPolicy

object (Guardrail.LlmPolicy)

可选。如果 LLM 回答根据 LLM 分类被视为违反政策，则阻止对话的安全屏障。
modelSafety

object (Guardrail.ModelSafety)

可选。如果 LLM 回答根据模型安全设置被视为不安全，则会阻止对话的防护栏。
codeCallback

object (Guardrail.CodeCallback)

可选。根据回调执行结果，可能会阻止对话的防护栏。
supervisor

object (Guardrail.Supervisor)

可选。运行监督员干预的保护措施。
互斥字段的结束。

Guardrail.ContentFilter

禁止在对话中使用某些内容的护栏。

JSON 表示法 
{
  "bannedContents": [
    string
  ],
  "bannedContentsInUserInput": [
    string
  ],
  "bannedContentsInAgentResponse": [
    string
  ],
  "matchType": enum (Guardrail.ContentFilter.MatchType),
  "disregardDiacritics": boolean
}
字段
bannedContents[]

string

可选。禁用短语的列表。适用于用户输入和智能体回答。
bannedContentsInUserInput[]

string

可选。禁用短语的列表。仅适用于用户输入。
bannedContentsInAgentResponse[]

string

可选。禁用短语的列表。仅适用于智能体回答。
matchType

enum (Guardrail.ContentFilter.MatchType)

必需。内容过滤条件的匹配类型。
disregardDiacritics

boolean

可选。如果为 true，则在匹配时忽略变音符号。

Guardrail.ContentFilter.MatchType

内容过滤条件的匹配类型。

枚举
MATCH_TYPE_UNSPECIFIED 未指定匹配类型。
SIMPLE_STRING_MATCH 系统会逐个字符地匹配子字符串。
WORD_BOUNDARY_STRING_MATCH 只有当文本中找到的模式被字词定界符包围时，内容才会匹配。禁用短语也可以包含字词定界符。
REGEXP_MATCH 系统会使用正则表达式语法来匹配内容。

Guardrail.LlmPromptSecurity

如果输入内容根据 LLM 分类被视为不安全，则阻止对话的防护措施。

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.
}
字段
failOpen

boolean

可选。确定保护措施遇到 LLM 错误时的行为。- 如果为 true：则绕过安全屏障。- 如果为 false（默认值）：安全措施会触发/阻止。

注意：如果提供了自定义政策，系统会忽略此字段，而采用政策的“failOpen”配置。
定义安全配置模式。用户必须选择以下配置之一。以下是互斥字段的列表。在响应中，最多只能设置以下字段之一：
defaultSettings

object (Guardrail.LlmPromptSecurity.DefaultSecuritySettings)

可选。使用系统预定义的默认安全设置。如需选择此模式，请在请求中添加空的“defaultSettings”消息。其中的“defaultPromptTemplate”字段将由服务器在响应中填充。
customPolicy

object (Guardrail.LlmPolicy)

可选。使用用户定义的 LlmPolicy 配置安全防护措施。
互斥字段的结束。

Guardrail.LlmPromptSecurity.DefaultSecuritySettings

默认系统安全设置的配置。

JSON 表示法 
{
  "defaultPromptTemplate": string
}
字段
defaultPromptTemplate

string

仅限输出。系统使用的默认提示模板。此字段用于显示目的，以向用户展示系统默认使用的提示。此字段为 OUTPUT_ONLY。

Guardrail.LlmPolicy

如果 LLM 回答根据 LLM 分类被视为违反政策，则阻止对话的安全屏障。

JSON 表示法 
{
  "maxConversationMessages": integer,
  "modelSettings": {
    object (ModelSettings)
  },
  "prompt": string,
  "policyScope": enum (Guardrail.LlmPolicy.PolicyScope),
  "failOpen": boolean,
  "allowShortUtterance": boolean
}
字段
maxConversationMessages

integer

可选。检查此政策时，请考虑对话中的最后“n”条消息。如果未设置，则使用默认值 10。
modelSettings

object (ModelSettings)

可选。模型设置。
prompt

string

必需。政策提示。
policyScope

enum (Guardrail.LlmPolicy.PolicyScope)

必需。定义在对话期间何时应用政策检查。如果设置为 POLICY_SCOPE_UNSPECIFIED，该政策将应用于用户输入。将政策应用于代理回答时，代理在做出回答之前会产生额外的延迟。
failOpen

boolean

可选。如果在政策检查期间发生错误，则以失败开放模式运行，并且不触发安全防护措施。
allowShortUtterance

boolean

可选。默认情况下，系统会跳过对简短话语的 LLM 政策检查。启用此设置后，系统会对所有话语（包括通常会跳过的话语）执行政策检查。

Guardrail.LlmPolicy.PolicyScope

定义在对话期间何时应用政策检查。

枚举
POLICY_SCOPE_UNSPECIFIED 未指定政策范围。
USER_QUERY 在用户输入时触发政策检查。
AGENT_RESPONSE 在代理回答时触发政策检查。应用此政策范围会在代理能够响应之前引入额外的延迟。
USER_QUERY_AND_AGENT_RESPONSE 系统会在用户输入和智能体回答时触发政策检查。应用此政策范围会在代理能够响应之前引入额外的延迟。

Guardrail.ModelSafety

模型安全设置替换项。如果设置了此值，它将覆盖默认设置，并在回答被认为不安全时触发安全护栏。

JSON 表示法 
{
  "safetySettings": [
    {
      object (Guardrail.ModelSafety.SafetySetting)
    }
  ]
}
字段
safetySettings[]

object (Guardrail.ModelSafety.SafetySetting)

必需。安全设置列表。

Guardrail.ModelSafety.SafetySetting

安全设置。

JSON 表示法 
{
  "category": enum (Guardrail.ModelSafety.HarmCategory),
  "threshold": enum (Guardrail.ModelSafety.HarmBlockThreshold)
}
字段
category

enum (Guardrail.ModelSafety.HarmCategory)

必需。有害类别。
threshold

enum (Guardrail.ModelSafety.HarmBlockThreshold)

必需。有害内容屏蔽阈值。

Guardrail.ModelSafety.HarmCategory

危害类别。

枚举
HARM_CATEGORY_UNSPECIFIED 未指定有害类别。
HARM_CATEGORY_HATE_SPEECH 有害类别为仇恨言论。
HARM_CATEGORY_DANGEROUS_CONTENT 有害类别为危险内容。
HARM_CATEGORY_HARASSMENT 有害类别为骚扰。
HARM_CATEGORY_SEXUALLY_EXPLICIT 有害类别为露骨色情内容。
HARM_CATEGORY_PROFANITY 有害类别为脏话。
HARM_CATEGORY_TOXIC 有害类别为恶意。

Guardrail.ModelSafety.HarmBlockThreshold

用于屏蔽的基于概率的阈值级别。

枚举
HARM_BLOCK_THRESHOLD_UNSPECIFIED 未指定的有害屏蔽阈值。
BLOCK_LOW_AND_ABOVE 屏蔽低阈值及以上的内容（即屏蔽较多的内容）。
BLOCK_MEDIUM_AND_ABOVE 屏蔽中等阈值及以上。
BLOCK_ONLY_HIGH 仅屏蔽高阈值内容（即屏蔽较少的内容）。
BLOCK_NONE 全部不屏蔽。
OFF 关闭安全过滤条件。

Guardrail.CodeCallback

根据提供的代码回调阻止对话的防护栏。

JSON 表示法 
{
  "beforeAgentCallback": {
    object (Callback)
  },
  "afterAgentCallback": {
    object (Callback)
  },
  "beforeModelCallback": {
    object (Callback)
  },
  "afterModelCallback": {
    object (Callback)
  }
}
字段
beforeAgentCallback

object (Callback)

可选。在调用代理之前要执行的回调。每个回调函数都应返回一个包含至少以下内容的结构（例如字典或对象）：-“decision”：可以是“OK”或“TRIGGER”。-“reason”：说明决策的字符串。“触发”决定可能会停止进一步处理。
afterAgentCallback

object (Callback)

可选。在调用代理后执行的回调。每个回调函数都应返回一个包含至少以下内容的结构（例如字典或对象）：-“decision”：可以是“OK”或“TRIGGER”。-“reason”：说明决策的字符串。“触发”决定可能会停止进一步处理。
beforeModelCallback

object (Callback)

可选。在调用模型之前要执行的回调。如果多次调用模型，则回调将执行多次。每个回调函数都应返回一个包含至少以下内容的结构（例如字典或对象）：-“decision”：可以是“OK”或“TRIGGER”。-“reason”：说明决策的字符串。“触发”决定可能会停止进一步处理。
afterModelCallback

object (Callback)

可选。在调用模型后执行的回调。如果多次调用模型，则回调将执行多次。每个回调函数都应返回一个包含至少以下内容的结构（例如字典或对象）：-“decision”：可以是“OK”或“TRIGGER”。-“reason”：说明决策的字符串。“触发”决定可能会停止进一步处理。

Guardrail.Supervisor

运行监督员干预的保护措施。

JSON 表示法 
{
  "type": enum (Guardrail.Supervisor.Type),
  "detectionMode": enum (Guardrail.Supervisor.DetectionMode)
}
字段
type

enum (Guardrail.Supervisor.Type)

可选。监督者的类型。
detectionMode

enum (Guardrail.Supervisor.DetectionMode)

可选。监督者的检测模式。

Guardrail.Supervisor.Type

监督者的类型。

枚举
TYPE_UNSPECIFIED 类型未指定。
INVALID_TEXT 文字问题类型无效。
LANGUAGE_SHIFT 语言转换问题类型。
SPEAKER_SHIFT 发言人轮换问题类型。
AUDIO_MISMATCH 音频不匹配问题类型。
MISSING_TOOL_CALL 缺少工具调用问题类型。
CUSTOM 自定义问题类型。
CHOPPY_AUDIO 声音断断续续问题类型。
PROFANITY 代理脏话问题类型。

Guardrail.Supervisor.DetectionMode

监督者的检测模式。

枚举
DETECTION_MODE_UNSPECIFIED 未指定检测模式。默认为 NON_BLOCKING。
NON_BLOCKING 非阻塞检测模式。在主管检测正在进行时，系统不会阻止响应。
BLOCKING 阻塞检测模式。当主管检测正在进行时，系统会屏蔽回答。

TriggerAction

在满足特定前提条件时执行的操作。

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.
}
字段
要采取的行动。以下是互斥字段的列表。在响应中，最多只能设置以下字段之一：
respondImmediately

object (TriggerAction.RespondImmediately)

可选。立即使用预配置的回答进行回复。
transferAgent

object (TriggerAction.TransferAgent)

可选。将对话转接给其他客服人员。
generativeAnswer

object (TriggerAction.GenerativeAnswer)

可选。使用生成式回答进行回复。
互斥字段的结束。

TriggerAction.RespondImmediately

智能体将立即回复预配置的回答。

JSON 表示法 
{
  "responses": [
    {
      object (TriggerAction.Response)
    }
  ]
}
字段
responses[]

object (TriggerAction.Response)

必需。供代理选择的预设回答。回答是随机选择的。

TriggerAction.Response

表示智能体的回答。

JSON 表示法 
{
  "text": string,
  "disabled": boolean
}
字段
text

string

必需。智能体要回复的文本。
disabled

boolean

可选。响应是否已停用。代理不会使用已停用的回答。

TriggerAction.TransferAgent

客服人员会将对话转接给其他客服人员。

JSON 表示法 
{
  "agent": string
}
字段
agent

string

必需。要将对话转接到的客服人员的名称。代理必须与当前代理位于同一应用中。格式：projects/{project}/locations/{location}/apps/{app}/agents/{agent}

TriggerAction.GenerativeAnswer

智能体将立即回复生成式答案。

JSON 表示法 
{
  "prompt": string
}
字段
prompt

string

必需。用于生成式回答的提示。

方法

create

 在指定应用中创建新的安全护栏。

delete

 删除指定的安全防护措施。

get

 获取指定安全屏障的详细信息。

list

 列出指定应用中的安全防护措施。

patch

 更新指定的安全措施。