Saltar para o conteúdo principal
Toda regra de guardrail responde a três perguntas — o que procurar (um tipo), onde procurar (um estágio) e o que fazer a respeito (uma ação). Esta página é sobre essa terceira escolha. A ação de uma regra é o campo mais consequente dela: decide se um match para a requisição, a reescreve silenciosamente, ou apenas deixa uma migalha. O construtor de regras expõe cinco ações ao todo — block, mask, flag, annotate e spotlight. Esta página cobre as três escolhas de enforcement que você usa primeiro: block, mask e flag. Escolha uma por regra (ou, para uma regra PII, roteie entidades diferentes para ações diferentes; veja §5). As outras duas são ações de modelagem de prompt, não bloqueantes: annotate injeta uma nota de segurança upstream (veja code security), e spotlight envolve o input não confiável correspondente em delimitadores para que o modelo o trate como dados, não instruções. O elenco completo vive na Visão geral dos guardrails. Para o motor mais amplo — tipos de regra, estágios, vincular uma política a uma chave — comece na Visão geral dos guardrails ou na referência completa de Guardrails.

​
1. A decisão block mask flag de guardrail em uma linha

block

Rejeita a chamada com HTTP 400 guardrail_blocked. O modelo nunca roda (estágio de input) ou sua resposta nunca retorna (estágio de output).

mask

Redige cada correspondência — ex.: jane@acme.com → [EMAIL] — e deixa o texto sanitizado passar. A requisição continua.

flag

Não muda nada no tráfego. Registra um match no feed e segue em frente. Apenas observa.
Estas são as três ações de enforcement. Qualquer que você defina é honrada em todo lugar onde a regra roda — o construtor de regras do console, o sandbox de Test e o caminho de relay /v1/* ao vivo leem todos o mesmo valor block / mask / flag.

​
2. Um exemplo concreto — três regras, três ações

Aqui está um único guardrail cujas três regras escolhem cada uma uma ação diferente. Você escreve isto no console (/console/guardrails) na sua sessão — a chave de relay sk-orca-... é apenas para chamadas /v1/*, nunca para editar política. Criar ou editar um guardrail exige o papel Developer+. 
{
  "rules": [
    { "type": "keyword", "stage": "input",  "action": "block",
      "keywords": ["internal-only", "do-not-share"] },
    { "type": "pii",     "stage": "input",  "action": "mask",
      "entities": ["email", "phone"] },
    { "type": "regex",   "stage": "output", "action": "flag",
      "pattern": "(?i)acme\\s+confidential" }
  ]
}
O que cada regra faz em uma requisição:
  • A regra block rejeita qualquer prompt contendo um desses termos literais — HTTP 400, o modelo nunca roda.
  • A regra mask reescreve emails e números de telefone para [EMAIL] / [PHONE] no prompt antes de o modelo vê-lo.
  • A regra flag observa o output do modelo em busca de um marcador confidencial e registra um match sem alterar a resposta — para que você possa medir com que frequência ele aparece antes de decidir aplicar.
O motor roda todas as regras aplicáveis e consolida os resultados em um veredito. Se qualquer regra bloqueia, a requisição é bloqueada.

​
3. block — rejeita com HTTP 400

Uma ação block rejeita a chamada inteira. O chamador recebe HTTP 400 com o código de erro guardrail_blocked e uma mensagem nomeando o guardrail e a regra que disparou.
Um block no estágio de input dispara antes da medição, então nada é consumido. Um block no estágio de output reembolsa a cota pré-consumida depois de rejeitar a resposta. De qualquer forma, o chamador não paga nada por uma chamada bloqueada.
Um resultado guardrail_blocked é skip-retry — reexecutar o mesmo prompt contra outro canal apenas bloquearia de novo, então o gateway não desperdiça uma retry. Veja o erro guardrail_blocked.
Em uma resposta não-streaming a resposta é filtrada antes de retornar. Em uma resposta streaming um scanner corta o stream em pleno voo e emite uma mensagem de substituição antes que qualquer conteúdo bloqueado chegue ao cliente. Veja cobertura de streaming.
Use block quando um match significa que a requisição não deve prosseguir — segredos em um prompt, uma tentativa de jailbreak, uma linha rígida de compliance.

​
4. mask — redige e continua

Uma ação mask redige cada correspondência e deixa a requisição passar com o texto sanitizado. O modelo upstream nunca vê o original. Em uma regra PII, cada correspondência é substituída por uma tag tipada derivada da entidade — um email vira [EMAIL], um SSN vira [SSN], um cartão de crédito [CREDIT_CARD], e assim por diante. (Você pode sobrescrever a string de substituição por entidade personalizada; veja formatos de mascaramento.)
O mascaramento no estágio de input está ativo em todo stream. Ele reescreve a requisição antes de o modelo rodar, streaming ou não. O mascaramento no estágio de output se aplica apenas a respostas não-streaming — o texto mascarado é encaminhado depois que a resposta completa é filtrada. Em uma resposta streaming o gateway calcula a máscara mas ainda não encaminha o texto redigido, então uma regra de mask não redige uma resposta streaming hoje; o mascaramento in-stream do output está no roadmap. (Um block de output ainda corta um stream em pleno voo — veja §3.) Prove sua combinação exata de estágio/stream no sandbox primeiro. Veja cobertura de streaming.
Use mask quando o conteúdo está bem mas uma substring não deveria chegar ao modelo — a redação de PII é o caso canônico. O ponto de partida pronto é o preset PII Shield; veja PII Shield.

​
5. flag — apenas registra, não muda nada

Uma ação flag é apenas observação: a requisição é byte-idêntica a uma sem regra nenhuma, exceto que um match é registrado no Feed de matches. Nada é bloqueado, nada é redigido.
flag é como você mede uma regra antes de aplicá-la. Coloque um novo keyword ou regex como flag, observe o feed de Matches por alguns dias para ver sua taxa de verdadeiro-vs-falso-positivo no tráfego real, depois promova-o para mask ou block quando você confiar nele. Ajustar um padrão barulhento com flag ligado vence descobrir os falsos positivos em produção com block ligado. Veja ajustar falsos positivos.
Um match sinalizado registra o tipo de regra, ação, estágio e uma string de detalhe — e a substring correspondente apenas se Log raw content estiver ligado para aquele guardrail (desligado por padrão, a postura conservadora de privacidade). Veja logging e privacidade.

​
6. Overrides de ação por entidade

Uma única regra PII pode rotear entidades diferentes para ações diferentes via entity_actions, em vez de empilhar regras sobrepostas. Cada valor de override deve ser um entre block / mask / flag / annotate, e deve referenciar uma entidade que a regra já declara — o validador rejeita qualquer outra coisa. 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ip", "credit_card", "ssn"],
  "entity_actions": {
    "credit_card": "block",
    "ssn": "block"
  }
}
Esta regra única mascara emails, phones e IPs mas bloqueia a requisição totalmente em um número de cartão ou SSN. Veja entidades de PII personalizadas para empilhar seus próprios detectores sob o mesmo modelo de override.

​
7. Escolhendo a ação certa

Se você quer…UseEfeito
Parar a requisição inteiramenteblockHTTP 400, sem cota, skip-retry
Remover uma substring, manter a chamadamaskTexto redigido encaminhado
Observar sem tocar o tráfegoflagApenas match registrado
As ações se compõem com estágios. A mesma ação se comporta de forma ligeiramente diferente em input vs output — um block de input economiza cota de antemão; um block de output a reembolsa; o mascaramento de output se aplica apenas a respostas não-streaming, enquanto um block de output corta respostas streaming e não-streaming igualmente. Leia estágio de input e estágio de output junto com esta página.

​
8. Para onde ir a seguir

O erro guardrail_blocked

Como é um 400, por que não custa cota e como funciona o skip-retry.

Formatos de mascaramento

Tags tipadas, strings de substituição personalizadas e como um prompt mascarado se lê para o modelo.

Cobertura de streaming

Exatamente quais combinações de ação × estágio × stream são aplicadas hoje.

Modos de enforcement

Como block / mask / flag se mapeiam no modelo de enforcement mais amplo do gateway, incluindo o veredito de audit do firewall.
O firewall tem seu próprio vocabulário de veredito (allow, audit, deny, sanitize e mais) para política de ferramenta — distinto dessas ações de conteúdo. Veja guardrails vs. firewall.