# 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](/documentation/developer-guide/pt-br/development-cycle/build-overview/accounts.md#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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digibee.com/documentation/resources/pt-br/quickstarts/agent-guardrails.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.