Construa Agentes de IA seguros e controlados com Guardrails

Garanta a privacidade dos dados mascarando informações sensíveis e aplicando regras rígidas de resposta.

Este guia rápido mostra como usar guardrails para detectar e proteger automaticamente PII (Informações Pessoalmente Identificáveis), além de aplicar regras de negócio com padrões personalizados, mantendo suas integrações seguras e em conformidade.

O que são guardrails?

Guardrails atuam como camadas de segurança entre o usuário e o LLM. Na Digibee, eles:

• Detectam e mascaram dados sensíveis: Identificam e mascaram identificadores pessoais (CPF, CNPJ), dados financeiros (cartões de crédito, IBAN), informações de contato (email, telefone), identificadores técnicos (endereços IP, URLs), endereços de carteiras cripto e outros padrões configuráveis.

• Validam padrões de entrada: Bloqueiam formatos específicos de dados antes do processamento da requisição, garantindo que a IA siga um padrão pré-definido.

Pré-requisitos

Antes de começar, certifique-se de que você possui:

• Uma API key de um provedor de LLM (por exemplo, OpenAI, Anthropic ou Google).

• A API key cadastrada na Digibee como uma conta do tipo Secret Key. Para mais detalhes, consulte como criar uma conta Secret Key.

Configuração inicial

Adicione o Agent Component ao seu pipeline imediatamente após o gatilho e configure-o da seguinte forma:

• Modelo: Selecione o modelo desejado (por exemplo, OpenAI – GPT-4o Mini).

• Conta: Clique no ícone de engrenagem ao lado do parâmetro Model, vá em Conta e selecione a conta Secret Key criada na Digibee.

Após concluir a configuração básica, você estará pronto para configurar os guardrails.

Cenário

Você está construindo um Agent para processar solicitações de reembolso. Ele deve identificar se a solicitação é válida; nunca enviar dados sensíveis do cliente ao provedor de IA e garantir que o formato de saída seja legível por um banco de dados.

Para assegurar privacidade e conformidade, configure o Agent com as seguintes mensagens:

System Message

Você é um assistente de triagem de reembolsos. A partir da solicitação do usuário, retorne:
1. O código do pedido exatamente como exibido,
2. Se há ou não um código de pedido presente,
3. Um breve resumo sem dados sensíveis.
Retorne apenas o JSON.

User Message

{{ message.$ }}

Passo a passo

1. Ative a detecção de PII (Masking) e validação com JSON Schema

Proteja a privacidade dos seus clientes garantindo que dados sensíveis nunca sejam enviados em texto puro ao provedor de LLM.

1. Abra o Agent Component e clique no ícone de engrenagem (⚙️) ao lado de Guardrails.

2. Nas configurações, habilite Mask on detection.

3. Selecione os padrões específicos que deseja proteger. Para este exemplo, selecione:

   • CPF detection

   • Email detection

4. Após selecionar os padrões, habilite JSON Schema para validar a resposta do modelo com base na estrutura definida. Se a resposta não corresponder ao schema, o Agent solicita automaticamente uma correção. Se a validação continuar falhando, a execução é encerrada com erro.

2. Adicionar validação personalizada com Regex

Adicione um padrão personalizado para garantir que o Agent processe apenas códigos de pedido internos legítimos:

1. Na mesma página de Guardrails, habilite Regex.

2. Configure:

   • Nome do padrão: Valid_Order_Code

   • Padrão Regex: REF-\d{4}

3. Clique em Salvar.

3. Garantir saída estruturada (JSON Schema)

Os guardrails também monitoram a saída do modelo. A opção de JSON Schema foi habilitada no Passo 1. Agora você definirá o schema para garantir uma resposta legível por máquina.

Quando ambas as configurações estiverem ativas, o Agent valida as respostas com base nesse schema e tenta automaticamente novamente caso a saída não esteja em conformidade na primeira tentativa.

1. Clique no ícone de engrenagem (⚙️) ao lado de Model e habilite Use JSON Schema.

2. Defina o schema no campo JSON Schema definition (certifique-se de que a tag $schema esteja presente):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "order_id",
    "order_code_present",
    "customer_summary",
    "email_present"
  ],
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order identifier extracted from the text"
    },
    "order_code_present": {
      "type": "boolean",
      "description": "True if an order code is present in the input."
    },
    "email_present": {
      "type": "boolean",
      "description": "True if an email address is present in the input."
    },
    "customer_summary": {
      "type": "string",
      "description": "A summary without sensitive data."
    }
  }
}

4. Testar os Guardrails

Insira a seguinte entrada na seção Detalhes do output para verificar como a proteção é aplicada e clique em Executar para realizar o teste.

Input

{
  "body": {
    "text": "Hello, my name is João, my email is [e-mail], and my CPF is 000.111.222-33. I would like a refund for order REF-9988."
  }
}

Output (Resultado final)

{
  "success": true,
  "body": {
    "order_id": "{{{REDACTED-custom-regex-valid_order_code}}}",
    "order_code_present": true,
    "email_present": true,
    "customer_summary": "The customer is requesting a refund for an order. Personal identifiers like email and CPF have been redacted."
  },
  "tokenUsage": {
    "inputTokenCount": 209,
    "outputTokenCount": 55,
    "totalTokenCount": 264
  }
}

Como funciona

Para garantir segurança e consistência, o Agent Component segue este processo interno:

Redação de dados (Data redaction)

Antes que o prompt seja enviado ao LLM (OpenAI, Google ou outros), a Digibee analisa o texto em busca de dados sensíveis. Se informações como CPF, email ou outros dados identificáveis forem detectadas, a Plataforma as substitui por um placeholder. Assim, o provedor nunca recebe os dados reais, ajudando você a manter conformidade com leis de privacidade.

Lógica de reprompt

Quando a validação com JSON Schema está habilitada, o Agent valida a resposta do modelo com base na estrutura definida. Se a resposta não corresponder ao formato esperado (por exemplo, se um campo obrigatório estiver ausente), o Agent envia automaticamente uma solicitação de correção ao modelo. Se a resposta ainda falhar na validação, a execução é encerrada com erro.

Resultado

Parabéns! Você construiu um Agent de IA seguro e pronto para produção, com dados mascarados automaticamente, regras de negócio aplicadas via Regex e saídas garantidas por validação com JSON Schema.