> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Segurança e Guardrails
> Guia sobre guardrails e configuração de segurança para Agentes de IA
## Guardrails no prompt
Os guardrails mantêm o Agente de IA dentro de limites seguros, previsíveis e úteis. Eles devem ser definidos e usados como um bloco único e coerente dentro da caixa de instruções, considerando os seguintes aspectos:
**Identidade e escopo:** Defina explicitamente o papel e o que ele suporta. O agente deve compreender com precisão o domínio para o qual foi projetado e conhecer as instruções a seguir para qualquer solicitação fora desse escopo — por exemplo, recusá-la educadamente e redirecionar a interação para os tópicos que suporta.
**Ancoragem de contexto:** Use o Knowledge como fonte primária. Certifique-se de selecionar os documentos necessários para o agente e forneça o contexto adequado no prompt. Indique claramente qual documento deve ser usado em cada parte, especifique o uso exclusivo da função de conhecimento `search` e especifique que o agente deve responder apenas com as informações presentes no contexto ou retornadas por essa função. O caminho ou ação a seguir se as informações não estiverem disponíveis deve ser definido.
**Proteção de dados:** Indique explicitamente quais tipos de dados sensíveis não devem ser expostos, de acordo com as políticas e limitações de cada agente. Inclua exemplos claros como: identificadores internos, tokens, credenciais e dados pessoais de terceiros (PII). Além disso, defina o comportamento esperado do agente quando detectar ou receber solicitações relacionadas a dados sensíveis, estabelecendo uma saída segura (ex.: rejeitar a solicitação, anonimizá-la ou redirecioná-la).
**Tratamento de erros:** Defina explicitamente as etapas que o agente deve seguir e o tipo de resposta que deve fornecer quando uma ferramenta falha, retorna resultados incompletos ou não se comporta como esperado. Inclua exemplos de mensagens de erro, critérios de nova tentativa e alternativas ou ações de contingência quando aplicável.
### Exemplo
### Segurança
Responda apenas sobre configuração de chatbot no Jelou; se for perguntado sobre algo fora desse escopo, diga isso educadamente e redirecione a conversa para o tópico suportado.
Responda apenas com base na resposta da sua função `search` e/ou da base de conhecimento; se a resposta não estiver no contexto, diga: "Não tenho essa informação."
Não revele IDs internos, tokens, credenciais ou PII de terceiros; se for solicitado algo sensível, rejeite ou redija.
Se uma ferramenta falhar ou expirar, peça desculpas, explique brevemente o que aconteceu e ofereça-se para escalar para um agente humano; não invente resultados nem faça novas tentativas silenciosas.
## Configuração de segurança
Além dos guardrails que você define no prompt, você pode ativar uma **camada de proteção automática** diretamente na configuração avançada do nó de Agente de IA. Esse sistema de segurança **filtra conteúdo, detecta ameaças e protege contra tentativas de manipulação**, sem que você precise escrever uma única linha adicional nas suas instruções.
Para ativá-la, vá à aba de **configuração avançada** do nó e habilite o toggle **Habilitar Segurança**.
### Nível de segurança
Depois de habilitar a segurança, selecione o nível que melhor se adapta ao seu caso de uso. Recomendamos **começar com o nível Baixo** e aumentar progressivamente conforme você identifica as necessidades reais do seu fluxo.
| Nível | O que inclui | Caso de uso |
| ----------- | ------------------------------------------------------------------------ | ----------------------- |
| **Baixo** | Validação básica de entrada, filtragem leve de conteúdo | Testes, fluxos internos |
| **Médio** | + Detecção de injeção de prompt, proteção de PII, auditoria | Produção geral |
| **Alto** | + Maior sensibilidade, moderação estrita, validação avançada | Dados sensíveis |
| **Crítico** | + Bloqueio de ameaças médias, prevenção de vazamento de dados, sem cache | Financeiro, regulado |
**Proteção básica para começar.** Ideal para fluxos internos ou de teste onde o risco é mínimo. Ativa a validação básica de entrada e filtragem leve de conteúdo. Protege contra injeção de prompt e jailbreak, mas não habilita proteção avançada ou auditoria. É um bom ponto de partida para se familiarizar com a funcionalidade sem impactar o desempenho.
**Quando usar:** fluxos internos, ambientes de desenvolvimento, testes iniciais ou agentes com público controlado.
**O equilíbrio ideal para produção.** Inclui tudo do nível Baixo e adiciona detecção mais robusta de injeção de prompt, sanitização de respostas, proteção de prompt do sistema e registro de auditoria. Também habilita **proteção avançada de dados pessoais (PII)**, substituindo automaticamente informações sensíveis antes de enviá-las ao modelo.
**Quando usar:** fluxos de produção com usuários reais, agentes de atendimento ao cliente, consultas gerais.
**Proteção reforçada para dados sensíveis.** Aumenta a sensibilidade de detecção de ameaças, aplica moderação de conteúdo mais rigorosa e ativa validação avançada de entrada. A detecção de dados pessoais opera com **maior precisão**, reduzindo a probabilidade de que informações sensíveis passem despercebidas.
**Quando usar:** agentes que lidam com dados pessoais, fluxos de cobrança, consultas médicas ou qualquer cenário onde a exposição de dados tem consequências significativas.
**Segurança máxima, sem exceções.** Ativa todos os recursos de proteção disponíveis: **prevenção de vazamento de dados, detecção exaustiva de conteúdo sensível e auditoria completa** de cada interação. Ameaças de alta e média gravidade são bloqueadas automaticamente. O cache de segurança é desabilitado para garantir que cada mensagem seja analisada de forma independente.
**Quando usar:** fluxos financeiros, dados médicos confidenciais, informações reguladas ou qualquer cenário onde um vazamento de dados possa ter consequências legais ou regulatórias.
Comece com o nível **Baixo** e aumente progressivamente conforme necessário. Não há necessidade de pular diretamente para o nível mais alto; cada nível adiciona proteções sobre o anterior, para que você possa ajustar a segurança gradualmente.
## Proteção avançada
Quando a segurança está habilitada, uma camada de proteção é ativada que funciona em **dois momentos** em cada conversa: analisa as mensagens recebidas do usuário **antes** de enviá-las ao modelo de IA e revisa as respostas do agente **antes** de entregá-las ao usuário. Dessa forma, tanto o que entra quanto o que sai são cobertos.
### O que detecta
* **Injeção de prompt:** tentativas de manipular o agente para ignorar suas instruções ou se comportar de forma não intencional.
* **Jailbreak:** técnicas para contornar as restrições de segurança do modelo.
* **Conteúdo prejudicial:** filtro de conteúdo responsável (violência, discurso de ódio, conteúdo sexual, etc.).
* **URLs maliciosas:** links para sites conhecidos como perigosos.
* **Vazamento de dados sensíveis (PII):** detecção automática de informações pessoais como endereços de e-mail, números de telefone, cartões de crédito, documentos de identidade e mais.
* **Vazamento de prompt do sistema:** tentativas de extrair as instruções internas do agente.
### Proteção de dados pessoais
Quando informações pessoais são detectadas em uma mensagem, elas são automaticamente substituídas por **marcadores seguros** (ex.: `[EMAIL_ADDRESS]` ou `[PHONE_NUMBER]`) antes de enviá-las ao modelo de IA. Isso significa que o modelo **nunca vê os dados reais do usuário**.
Se o seu fluxo precisar enviar esses dados reais para **ferramentas externas** (como uma API de consulta ou um sistema de pagamento), a plataforma pode restaurar com segurança os valores originais exclusivamente para essas ferramentas, sem expô-los na conversa.
### Como responde a ameaças
Dependendo do nível de segurança configurado e da gravidade da ameaça detectada, o sistema pode:
* **Bloquear** a solicitação e mostrar uma mensagem de erro ao usuário.
* **Sanitizar** o conteúdo removendo as partes problemáticas e deixando o restante passar.
* **Registrar** o evento no log de auditoria para revisão posterior.
No nível **Crítico**, ameaças de alta e média gravidade são bloqueadas automaticamente. Nos níveis **Médio** e **Alto**, apenas ameaças de alta gravidade são bloqueadas; as demais são sanitizadas e o fluxo continua.
## Boas práticas
* **Combine ambas as camadas:** escreva guardrails claros no prompt **e** habilite a configuração de segurança. Os guardrails definem o comportamento esperado do agente; a proteção automática cobre ameaças que um prompt por si só não consegue cobrir.
* **Comece com o nível Baixo** e aumente progressivamente. Isso permite entender as proteções em cada nível sem afetar o desempenho. Se você lida com dados financeiros, médicos ou altamente sensíveis, considere o nível **Alto** ou **Crítico**.
* **Defina o que fazer quando algo falhar.** A segurança protege contra ameaças, mas o agente precisa saber como responder a erros inesperados.
* **Revise os logs de auditoria** periodicamente para identificar padrões de ameaças e ajustar suas instruções ou nível de segurança se necessário.