Guardrails

O bloco Guardrails checa conteúdo contra um tipo de validação e reporta se passou. Use para pegar JSON malformado, texto fora do padrão, respostas sem grounding ou PII antes do conteúdo seguir. Cada bloco roda uma checagem; encadeie vários para aplicar mais de uma.

Tipos de validação

Valid JSON

Checa se o conteúdo parseia como JSON válido. Use antes de um Function ou bloco downstream ler a saída estruturada de um modelo.

• <guardrails.passed> — true se o conteúdo é JSON válido
• <guardrails.error> — o erro de parse quando não é, como Invalid JSON: Unexpected token

Regex Match

Checa o conteúdo contra uma expressão regular — um e-mail, um telefone, uma URL ou qualquer padrão que você definir.

• Regex Pattern — a expressão a bater, como ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ para um e-mail
• <guardrails.passed> — true se o conteúdo bate; <guardrails.error> caso contrário

Hallucination Check

Pontua quão bem a saída de IA está grounded numa base de conhecimento. O bloco recupera contexto relevante, envia ao modelo com a saída, e o modelo retorna um score de confiança de 0 (completamente sem grounding) a 10 (totalmente suportado). A validação passa quando o score atinge o limiar.

• Knowledge Base — a base de conhecimento contra a qual checar
• Model — o modelo que pontua o grounding. Use um modelo de raciocínio forte; o padrão é claude-sonnet-4-6. A API key é fornecida para você no Zoen hospedado
• Confidence — o score mínimo para passar, de 0 a 10 (padrão 3)
• Top K (advanced) — quantos chunks da base de conhecimento recuperar (padrão 5)

Produz <guardrails.score> (0–10) e <guardrails.reasoning> (por que o modelo pontuou assim) junto com passed.

PII Detection

Detecta informações pessoalmente identificáveis com Microsoft Presidio — mais de 30 tipos de entidade em vários países e idiomas.

• PII Types to Detect — escolha os tipos de entidade no modal, agrupados por região:
  • Common — nome de pessoa, e-mail, telefone, cartão de crédito, endereço IP e mais
  • USA — SSN, carteira de motorista, passaporte, conta bancária, ITIN
  • UK — número NHS, national insurance number
  • Spain — NIF, NIE · Italy — código fiscal, carteira de motorista, identidade, passaporte · Poland — PESEL · Singapore — NRIC/FIN
  • Australia — ABN, ACN, TFN, Medicare · India — Aadhaar, PAN, registro de veículo, número de eleitor, passaporte
• Action — Block falha a validação quando qualquer tipo selecionado é encontrado (padrão); Mask também substitui o PII por valores mascarados
• Language — o idioma de detecção (padrão English)

Produz <guardrails.detectedEntities> (cada uma com tipo, localização e confiança) e, no modo Mask, <guardrails.maskedText>. passed é false quando qualquer PII selecionado é encontrado.

Configuração

Content to Validate

A entrada a checar. Geralmente uma saída anterior como <agent.content>, <function.result> ou uma resposta de API.

Validation Type

Qual das quatro checagens rodar: Valid JSON, Regex Match, Hallucination Check ou PII Detection.

Saídas

Todo tipo de validação retorna:

Hallucination adiciona <guardrails.score> e <guardrails.reasoning>; PII adiciona <guardrails.detectedEntities> e <guardrails.maskedText>.

Exemplos

Validar JSON antes de parsear

Cheque se a saída do Agent é JSON válido e depois ramifique em <guardrails.passed> antes de um Function parseá-la.

Prevenir alucinações

Pontue a resposta contra uma base de conhecimento e faça gate em <guardrails.score> para enviar uma resposta grounded ou marcar uma fraca.

Bloquear PII na entrada do usuário

Detecte PII na entrada e ramifique em <guardrails.passed> para processar entrada limpa ou rejeitá-la.

Boas práticas

• Ramifique no resultado. Leia <guardrails.passed> num Condition para rotear conteúdo válido e inválido por caminhos diferentes.
• Valide JSON antes de parsear. Uma checagem upstream é mais barata que um erro de parse num bloco Function.
• Escolha só os tipos de PII de que precisa. Selecionar menos tipos de entidade mantém a detecção rápida e focada.
• Ajuste o limiar de alucinação. Suba o piso de confiança para grounding mais estrito, baixe para permitir mais latitude.
• Mascare quando logar. Use o modo Mask para conteúdo que você armazena ou loga, para PII nunca cair em texto puro.
• Encadeie checagens. Um bloco roda um tipo, então coloque vários em sequência para validar formato e depois varrer PII.