Guardrails

O que são

Guardrails são uma camada de validação aplicada em dois momentos da Conversa: antes da entrada ir para o modelo de IA (validação de input) e depois do modelo gerar resposta (validação de output). Cada Guardrail é uma política composta por regras que decidem permitir, bloquear, mascarar ou pedir reescrita do conteúdo.

A intenção é simples: a IA é poderosa, mas você precisa de trilhos para manter a Conversa dentro do escopo do produto, proteger dados pessoais do contato e blindar contra entradas adversárias (prompt injection, fuga de tópico, jailbreak).

Quando os Guardrails disparam

A pipeline roda em dois pontos do ciclo de execução do Fluxo Conversacional:

1. Pré-LLM (input). Cada mensagem do contato passa pelas regras de input antes de o modelo recebê-la. Aqui detecta-se PII para mascaramento, prompt injection, conteúdo fora de escopo, mensagens maliciosas em listas negras.
2. Pós-LLM (output). Cada resposta gerada pelo modelo passa pelas regras de output antes de ser entregue ao contato. Aqui valida-se se a resposta está aterrada em fontes (groundedness), se não vaza dados internos (pii_leak), se respeita o limite de tamanho.

Se nenhuma regra reprovar, o conteúdo flui normalmente. Se reprovar, a ação configurada na regra entra em vigor.

Tipos de regra

A biblioteca cobre os casos mais comuns. Todas as regras pertencem a uma das duas pontas (input ou output):

Aplicáveis no input

Regra	O que faz
length_limit	Bloqueia mensagens acima ou abaixo de um tamanho.
blacklist	Bloqueia termos ou padrões proibidos por palavra-chave.
pii_detection	Identifica dados pessoais (CPF, CNPJ, telefone, e-mail) e mascara antes de enviar ao LLM.
prompt_injection	Detecta tentativas de subverter o prompt do sistema (jailbreak, role-play malicioso).
intent_whitelist	Restringe quais intenções a Conversa pode tratar (lista positiva).
scope_check	Verifica se a mensagem pertence ao domínio de assuntos da Operação.

Aplicáveis no output

Regra	O que faz
groundedness	Verifica se a resposta está aterrada em trechos de Conhecimento que o Fluxo recuperou — protege contra alucinação.
pii_leak	Detecta vazamento de PII na resposta (dados internos do tenant aparecendo no que vai para o contato).
length_limit	Reaplica limite de tamanho na saída quando o caso pede.

Ações no disparo

Quando uma regra reprova, ela retorna uma decisão. A engine processa todas as decisões e escolhe a mais restritiva:

Decisão	Comportamento
allow	Permitir; o conteúdo segue inalterado.
allow_warn	Permitir, mas registrar warning na auditoria.
mask	Aplicar mascaramento ao conteúdo (substitui faixa por placeholder, ex.: [CPF]) e seguir.
rewrite	Pedir ao modelo uma reescrita corrigida antes de seguir.
retry	Tentar a geração novamente.
require_citation	Exigir que a resposta cite a fonte do Conhecimento usado.
escalate	Transferir a Conversa para Atendente humano via Fila.
block	Bloquear a mensagem e responder com mensagem padrão.

Mais de uma regra pode disparar na mesma mensagem; a engine combina os mascaramentos e aplica a decisão mais forte (block prevalece sobre mask prevalece sobre allow_warn, etc.).

Tiers e engines

Cada regra usa uma engine — a estratégia técnica para avaliar o conteúdo. As engines disponíveis dependem do tier contratado pela Operação:

Tier	Engines disponíveis	Quando usar
Básico	static, keyword, heuristic, embedding.	Cobertura essencial: blacklists, regex de PII, similaridade vetorial para escopo. Latência baixa, sem custo de LLM extra.
Pro	Tudo do Básico + llm_judge, model.	Adiciona avaliação por LLM (juiz) e modelos dedicados de moderação. Cobertura mais ampla, custo maior por chamada.
Enterprise	Tudo do Pro + integrações externas.	Conexão com soluções terceirizadas de moderação. Para casos com requisitos regulatórios específicos.

Quando a Operação está em Básico, regras com engines Pro/Enterprise são bloqueadas no save da política — você verá um erro de “tier_locked” indicando qual regra exige tier maior.

Como anexar a um Fluxo

No builder do Fluxo Conversacional, abra Configurações globais → Guardrails e selecione as políticas que esse Fluxo deve aplicar. O vínculo é por Fluxo, não por nó: a política roda em todas as mensagens que passam pelo Fluxo.

Você pode anexar várias políticas ao mesmo Fluxo — elas se compõem (todas as regras de todas as políticas são avaliadas). Útil para separar responsabilidades: uma política “Compliance LGPD” cuidando de PII; uma política “Tom de marca” cuidando de blacklist de termos; uma política “Aterramento” cuidando de groundedness.

Auditoria

Todo disparo de Guardrail é registrado para auditoria. O log captura:

• Qual regra disparou e em qual mensagem.
• Decisão final aplicada (block, mask, rewrite, etc.).
• Score, threshold e motivo da regra (quando aplicáveis).
• Identificadores da Conversa e do Fluxo.

O conteúdo armazenado é tratado para conformidade com LGPD — referências à mensagem original são feitas por hash, evitando duplicação do dado sensível na auditoria.

Boas práticas

• Comece pequeno e expanda. Política inicial com pii_detection e blacklist já elimina os erros mais comuns. Adicione scope_check e groundedness depois de medir o que está acontecendo.
• Mascare em vez de bloquear quando o dado é apenas sensível, não proibido. PII detectado no input quase sempre é caso de mascaramento, não bloqueio — bloquear quebraria a Conversa por algo que o contato digitou legitimamente.
• Use groundedness em Fluxos com Conhecimento. Sem ela, a IA pode responder com confiança sobre o que não está nas suas fontes. Combine com require_citation quando quiser ver a referência na resposta.
• Pense em escalate como última saída humana. Em casos onde bloquear é grosseiro mas continuar é arriscado (cliente irritado, pedido fora do escopo claro), escalate transfere a Conversa para Atendente em vez de fechar a porta.
• Revise a auditoria semanalmente nos primeiros meses. Padrões de ataque (prompt injection criativo) e falsos positivos só aparecem na prática.

Erros comuns

• Habilitar tudo de uma vez. Política com 12 regras turn-on simultâneo dispara muito; a operação reage tirando tudo. Comece pelo essencial.
• Esperar groundedness sem Conhecimento. A regra precisa dos trechos recuperados pelo RAG para comparar. Sem Base de Conhecimento anexada ao Fluxo, ela não tem o que aterrar.
• Configurar regra Pro em Operação Básica. O save retorna 403 tier_locked; a UI explica qual regra exige qual tier.
• Confundir mascaramento com remoção. Mascaramento substitui uma faixa por placeholder ([CPF]) — o LLM ainda recebe a estrutura da mensagem, sem o dado bruto.

Ver também

• Fluxos conversacionais
• Base de Conhecimento
• Fluxos: visão geral
• Conversas