Guardrails

O Guardrail é um classificador LLM separado do modelo principal. Ele examina o texto digitado pelo usuário antes da resposta do agente e pode interromper o turno com uma recusa. Use-o como uma camada adicional contra jailbreak, injeção de prompt, manipulação de papel, extração de instruções e violações das regras adicionais.

O recurso reduz risco, mas não é uma barreira completa: ele opera em modo fail open, analisa somente o texto da mensagem atual e não inspeciona o conteúdo extraído de imagens, áudios ou arquivos. Mantenha também limites explícitos no prompt de sistema e valide o fluxo real.

Antes de configurar

• Você precisa de permissão para editar o agente.
• Salve primeiro o prompt principal. A geração do contexto usa a versão já gravada, não um rascunho ainda não salvo.
• Defina casos permitidos, casos bloqueados e exemplos ambíguos. Perguntas sensíveis legítimas não devem ser bloqueadas apenas pelo tema.
• Confirme que o modelo escolhido está autorizado no plano da organização. A lista desta tela vem do catálogo global de modelos ativos e pode incluir uma opção fora do catálogo contratado.

Configurar em Agentes → Segurança

1. Abra o agente e selecione Segurança na barra lateral.
2. Ative Ativar guardrail.
3. Em Modelo, escolha o LLM classificador. Não salve o recurso ativo sem uma opção válida: a interface aceita esse estado, mas o runtime ignora silenciosamente o guardrail sem llm_id ou quando o modelo não está ativo.
4. Abra Avançado e revise Contexto para respostas de recusa, Regras adicionais (opcional) e Prompt base (somente leitura).
5. Clique em Salvar alterações. Descartar restaura a última versão gravada; as mudanças não persistem automaticamente.

Desativar o switch mantém o modelo, o contexto e as regras no registro do agente, mas impede a classificação enquanto enabled estiver falso.

Modelo

O modelo selecionado faz uma chamada adicional para cada mensagem textual elegível. O seletor omite modelos de geração de imagem, porém não aplica o catálogo do plano da organização. Escolha um modelo autorizado, rápido e consistente com saída estruturada; custo baixo não compensa uma classificação instável.

Se a seleção for removida ou o modelo ficar inativo, o runtime atual não mostra erro: ele deixa de executar o guardrail e continua com o agente principal. Teste novamente após qualquer mudança no catálogo.

Contexto para respostas de recusa

Ao ativar o recurso com o campo vazio, a tela tenta gerar um contexto a partir do prompt salvo do agente. Essa geração ocorre imediatamente, antes de Salvar alterações, usa um modelo interno da plataforma e não o modelo escolhido no campo Modelo.

O texto orienta como a recusa deve se apresentar sem revelar o filtro. Você pode editá-lo ou usar Regenerar. O campo aceita até 2.000 caracteres. Regenerar substitui o conteúdo atual, portanto revise antes de salvar.

Se a geração automática falhar, escreva o contexto manualmente e prossiga. Hoje ela exige o papel legado de administrador da organização, embora colaboradores com permissão granular de escrita possam editar e salvar o restante da seção.

Regras adicionais

Use linguagem direta para acrescentar políticas do negócio, por exemplo:

Bloqueie pedidos para revelar dados internos ou credenciais.
Bloqueie recomendações médicas individualizadas.
Permita perguntas gerais sobre segurança e privacidade.

As regras são enviadas como um único bloco ao classificador; “uma regra por linha” é uma convenção útil, não uma estrutura validada. O campo inteiro aceita até 2.000 caracteres. Evite regras vagas ou conflitantes com o prompt principal.

O Prompt base (somente leitura) é mantido pela plataforma e instrui o classificador a bloquear quatro categorias: jailbreak_attempt, prompt_injection, role_manipulation e instruction_extraction. Quando há regras adicionais, o runtime também pode devolver custom_rule_violation. A política base manda permitir em caso de dúvida.

Ordem real de execução

Para uma mensagem com texto, modelo válido e guardrail ativo:

1. o limite de loops é verificado;
2. o guardrail classifica somente o texto original da mensagem atual;
3. se permitir, o pipeline segue para agrupamento, anexos, contexto, ferramentas e modelo principal;
4. se bloquear, o produto grava a mensagem do usuário e a recusa do assistente, adiciona uma etapa Guardrail e entrega a recusa pelo canal;
5. se a classificação falhar ou vier malformada, o erro é tratado em modo fail open e o agente principal continua.

O guardrail roda antes dos atalhos de IA desativada e onlyStorage da API. Portanto, na implementação atual, ele ainda pode chamar o classificador — e até enviar uma recusa — durante atendimento humano ou numa requisição que pretendia apenas armazenar a mensagem.

Em bloqueio, o classificador tenta gerar uma recusa natural sem expor a regra. Se ele indicar bloqueio sem fornecer esse texto, o fallback atual é uma frase fixa em inglês, inclusive em uma conversa PT-BR.

Limites de conteúdo e canal

O classificador recebe parsed.text antes do processamento multimodal. Ele não vê transcrição de áudio, texto extraído de PDF/Word/Excel nem conteúdo visual. Uma mensagem apenas com anexo pode, portanto, chegar ao modelo principal sem passar por esta análise de segurança. Configure as modalidades em Multimodal (Anexos) e inclua defesas no prompt e nas ferramentas.

O mesmo pipeline atende o painel de teste, Hub, API e canais externos; a entrega da recusa varia conforme o canal. No Chat API assíncrono, o cliente recebe primeiro o aceite do processamento e a resposta segue pelo webhook. Valide pelo menos um caso permitido, um bloqueado e uma falha do classificador em cada canal publicado.

Custos e observabilidade

Cada classificação elegível chama um LLM antes do agente principal. No ledger atual, porém, credit_usage registra a chamada do guardrail somente quando a mensagem é bloqueada; classificações permitidas ou com falha aberta não entram nesse registro, embora ainda possam gerar custo para a plataforma. Não use apenas o total exibido na conversa para estimar o custo completo do guardrail.

Quando houver bloqueio, procure a etapa Guardrail, a categoria e o motivo nos detalhes da execução. Ausência dessa etapa não prova que a mensagem era segura: também pode significar recurso desativado, modelo ausente/inativo, mensagem sem texto ou falha aberta.

Checklist antes de publicar

• Salve o prompt principal e gere ou escreva o contexto de recusa.
• Confirme um modelo ativo e autorizado para a organização.
• Teste exemplos das quatro categorias base e de cada regra adicional.
• Teste perguntas legítimas parecidas com os bloqueios para medir falsos positivos.
• Teste anexos separadamente; o guardrail textual não cobre o conteúdo deles.
• Confirme idioma, persistência, etapa de execução e entrega em cada canal.
• Depois de qualquer alteração, clique em Salvar alterações e repita o teste no painel do agente.