# Construa Agentes de IA seguros e controlados com Guardrails

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](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/accounts#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):

```json
{
  "$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**

```json
{
  "body": {
    "text": "Hello, my name is João, my email is joao@email.com, and my CPF is 000.111.222-33. I would like a refund for order REF-9988."
  }
}

```

**Output (Resultado final)**

```json
{
  "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.