Guardrails

O bloco Guardrails verifica o conteúdo contra um único tipo de validação e informa se ele passou. Use-o para pegar JSON malformado, texto fora do padrão, respostas sem fundamento ou PII antes de o conteúdo seguir adiante. Cada block executa uma verificação; encadeie vários para aplicar mais de uma.

Tipos de validação

Valid JSON

Verifica se o conteúdo é um JSON válido. Use antes de um block Function ou de outro block seguinte ler a saída estruturada de um modelo.

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

Regex Match

Verifica 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 casar, como ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ para um e-mail
• <guardrails.passed> — true se o conteúdo casar; <guardrails.error> caso contrário

Hallucination Check

Pontua o quanto a saída da IA está fundamentada em uma base de conhecimento. O block recupera o contexto relevante, envia-o a um modelo junto com a saída, e o modelo retorna uma pontuação de confiança de 0 (totalmente sem fundamento) a 10 (totalmente sustentado). A validação passa quando a pontuação alcança o limite.

• Knowledge Base — a base de conhecimento usada como referência
• Model — o modelo que pontua a fundamentação. Use um modelo forte de raciocínio; o padrão é claude-sonnet-4-6. No Studio hospedado, a chave de API é fornecida para você
• Confidence — a pontuação mínima para passar, de 0 a 10 (padrão 3)
• Top K (avançado) — quantos trechos da base de conhecimento recuperar (padrão 5)

Retorna <guardrails.score> (0–10) e <guardrails.reasoning> (por que o modelo pontuou daquela forma), além de passed.

PII Detection

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

• PII Types to Detect — escolha os tipos de entidade na janela, 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 do NHS, número do national insurance
  • Spain — NIF, NIE · Italy — código fiscal, carteira de motorista, carteira de 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 a PII por valores mascarados
• Language — o idioma da detecção (padrão English)

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

Configuração

Content to Validate

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

Validation Type

Qual das quatro verificações executar: Valid JSON, Regex Match, Hallucination Check ou PII Detection.

Saídas

Todos os tipos de validação retornam:

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

Exemplos

Validar JSON antes do parsing

Verifique se a saída do Agent é um JSON válido e depois ramifique com base em <guardrails.passed>, antes de uma Function fazer o parsing.

Evitar alucinações

Pontue a resposta contra uma base de conhecimento e use <guardrails.score> como porteiro para enviar uma resposta fundamentada ou sinalizar uma resposta fraca.

Bloquear PII na entrada do usuário

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

Boas práticas

• Ramifique com base no resultado. Leia <guardrails.passed> em um Condition para rotear conteúdo válido e inválido por caminhos diferentes.
• Valide o JSON antes de fazer o parsing. Uma verificação antes é mais barata que um erro de parsing dentro de um block Function.
• Escolha só os tipos de PII que você precisa. Selecionar menos tipos de entidade mantém a detecção rápida e focada.
• Ajuste o limite de alucinação. Aumente o piso de confiança para exigir mais fundamentação; reduza-o para permitir mais folga.
• Mascare quando você gerar logs. Use o modo Mask para conteúdo que você armazena ou registra, para que a PII nunca fique em texto puro.
• Encadeie verificações. Um block executa um tipo, então coloque vários em sequência para validar o formato e depois procurar PII.