Guardrails

O bloco Guardrails valida e protege seus workflows de IA verificando o conteúdo contra múltiplos tipos de validação. Garanta qualidade de dados, previna alucinações, detecte PII e imponha requisitos de formato antes que o conteúdo avance no seu workflow.

Tipos de Validação

Validação de JSON

Valida se o conteúdo está formatado corretamente como JSON. Perfeito para garantir que outputs estruturados de LLM possam ser parseados com segurança.

Casos de Uso:

• Validar respostas JSON de blocos Agent antes do parsing
• Garantir que payloads de API estejam formatados corretamente
• Verificar integridade de dados estruturados

Output:

• passed: true se for JSON válido, false caso contrário
• error: Mensagem de erro se a validação falhar (ex: "Invalid JSON: Unexpected token...")

Validação com Regex

Verifica se o conteúdo corresponde a um padrão de expressão regular especificado.

Casos de Uso:

• Validar endereços de email
• Verificar formatos de números de telefone
• Verificar URLs ou identificadores personalizados
• Impor padrões específicos de texto

Configuração:

• Regex Pattern: A expressão regular para fazer match (ex: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ para emails)

Output:

• passed: true se o conteúdo corresponder ao padrão, false caso contrário
• error: Mensagem de erro se a validação falhar

Detecção de Alucinação

Usa Retrieval-Augmented Generation (RAG) com pontuação de LLM para detectar quando o conteúdo gerado por IA contradiz ou não está fundamentado na sua base de conhecimento.

Como Funciona:

1. Consulta sua base de conhecimento para obter contexto relevante
2. Envia tanto o output da IA quanto o contexto recuperado para um LLM
3. O LLM atribui uma pontuação de confiança (escala 0-10)
   • 0 = Alucinação total (completamente sem fundamento)
   • 10 = Totalmente fundamentado (completamente suportado pela base de conhecimento)
4. A validação passa se a pontuação ≥ limite (padrão: 3)

Configuração:

• Knowledge Base: Selecione das suas bases de conhecimento existentes
• Model: Escolha o LLM para pontuação (requer forte raciocínio - GPT-4o, Claude 3.7 Sonnet recomendados)
• API Key: Autenticação para o provedor de LLM selecionado (auto-oculto para modelos hospedados/Ollama ou compatíveis com VLLM)
• Confidence Threshold: Pontuação mínima para passar (0-10, padrão: 3)
• Top K (Avançado): Número de chunks da base de conhecimento para recuperar (padrão: 10)

Output:

• passed: true se pontuação de confiança ≥ limite
• score: Pontuação de confiança (0-10)
• reasoning: Explicação do LLM para a pontuação
• error: Mensagem de erro se a validação falhar

Casos de Uso:

• Validar respostas de Agent contra documentação
• Garantir que respostas de suporte ao cliente sejam factualmente precisas
• Verificar se o conteúdo gerado corresponde ao material fonte
• Controle de qualidade para aplicações RAG

Detecção de PII

Detecta informações pessoalmente identificáveis usando Microsoft Presidio. Suporta mais de 40 tipos de entidades em vários países e idiomas.

Como Funciona:

1. Passe o conteúdo para validar (ex: <agent1.content>)
2. Selecione os tipos de PII para detectar usando o seletor modal
3. Escolha o modo de detecção (Detect ou Mask)
4. O conteúdo é escaneado para entidades PII correspondentes
5. Retorna resultados da detecção e opcionalmente texto mascarado

Configuração:

• PII Types to Detect: Selecione das categorias agrupadas via seletor modal
  • Common: Nome da pessoa, Email, Telefone, Cartão de crédito, Endereço IP, etc.
  • USA: SSN, Carteira de motorista, Passaporte, etc.
  • UK: Número NHS, Número de seguro nacional
  • Spain: NIF, NIE, CIF
  • Italy: Código fiscal, Carteira de motorista, Código VAT
  • Poland: PESEL, NIP, REGON
  • Singapore: NRIC/FIN, UEN
  • Australia: ABN, ACN, TFN, Medicare
  • India: Aadhaar, PAN, Passaporte, Número de eleitor
• Mode:
  • Detect: Apenas identifica PII (padrão)
  • Mask: Substitui PII detectado com valores mascarados
• Language: Idioma de detecção (padrão: English)

Output:

• passed: false se qualquer tipo de PII selecionado for detectado
• detectedEntities: Array de PII detectado com tipo, localização e confiança
• maskedText: Conteúdo com PII mascarado (apenas se mode = "Mask")
• error: Mensagem de erro se a validação falhar

Casos de Uso:

• Bloquear conteúdo contendo informações pessoais sensíveis
• Mascarar PII antes de registrar ou armazenar dados
• Conformidade com GDPR, HIPAA e outras regulamentações de privacidade
• Sanitizar inputs de usuários antes do processamento

Configuração

Conteúdo para Validar

O conteúdo de entrada para validar. Normalmente vem de:

• Outputs de blocos Agent: <agent.content>
• Resultados de blocos Function: <function.output>
• Respostas de API: <api.output>
• Qualquer outro output de bloco

Tipo de Validação

Escolha entre quatro tipos de validação:

• Valid JSON: Verifica se o conteúdo está formatado corretamente como JSON
• Regex Match: Verifica se o conteúdo corresponde a um padrão regex
• Hallucination Check: Valida contra base de conhecimento com pontuação de LLM
• PII Detection: Detecta e opcionalmente mascara informações pessoalmente identificáveis

Outputs

Todos os tipos de validação retornam:

• <guardrails.passed>: Booleano indicando se a validação passou
• <guardrails.validationType>: O tipo de validação realizada
• <guardrails.input>: O input original que foi validado
• <guardrails.error>: Mensagem de erro se a validação falhou (opcional)

Outputs adicionais por tipo:

Hallucination Check:

• <guardrails.score>: Pontuação de confiança (0-10)
• <guardrails.reasoning>: Explicação do LLM

PII Detection:

• <guardrails.detectedEntities>: Array de entidades PII detectadas
• <guardrails.maskedText>: Conteúdo com PII mascarado (se mode = "Mask")

Exemplos de Uso

Validar JSON Antes do Parsing - Garante que o output do Agent seja JSON válido

Agent (Gerar) → Guardrails (Validar) → Condition (Verificar passou) → Function (Parsear)

Prevenir Alucinações - Valida respostas de suporte ao cliente contra base de conhecimento

Agent (Resposta) → Guardrails (Verificar KB) → Condition (Pontuação ≥ 3) → Enviar ou Sinalizar

Bloquear PII em Inputs de Usuários - Sanitiza conteúdo enviado por usuários

Input → Guardrails (Detectar PII) → Condition (Sem PII) → Processar ou Rejeitar

Boas Práticas

• Combine com blocos Condition: Use <guardrails.passed> para ramificar a lógica do workflow com base nos resultados da validação
• Use validação JSON antes do parsing: Sempre valide a estrutura JSON antes de tentar parsear outputs de LLM
• Escolha tipos de PII apropriados: Selecione apenas os tipos de entidade PII relevantes para seu caso de uso para melhor performance
• Defina limites de confiança razoáveis: Para detecção de alucinação, ajuste o limite com base nos seus requisitos de precisão (maior = mais rigoroso)
• Use modelos fortes para detecção de alucinação: GPT-4o ou Claude 3.7 Sonnet fornecem pontuação de confiança mais precisa
• Mascara PII para logging: Use o modo "Mask" quando precisar registrar ou armazenar conteúdo que pode conter PII
• Teste padrões regex: Valide seus padrões regex completamente antes de fazer deploy em produção
• Monitore falhas de validação: Acompanhe mensagens de <guardrails.error> para identificar problemas comuns de validação