Guardrails: Validação de Entradas e Saídas
Nesta página
O que é um guardrail?
Um guardrail é uma camada de validação situada entre o utilizador e o modelo na entrada, ou entre o modelo e o utilizador na saída. A distinção face à moderação abordada no capítulo anterior é nítida e deve mantê-la: a moderação responde à pergunta «Este conteúdo é ofensivo?», uma questão universal cuja resposta não depende do seu negócio. Os guardrails respondem a perguntas que só você pode formular: A mensagem está dentro do âmbito esperado? A resposta contém informações proibidas? A ação solicitada está autorizada para esta função? Um assistente bancário e um assistente de livraria partilham a mesma moderação, mas não têm guardrails em comum.
Em 2026, os guardrails tornaram-se um componente padrão das arquiteturas de agentes de IA, indispensáveis sempre que um modelo tem acesso a ferramentas ou dados sensíveis.
Uma arquitetura de pipeline
A escolha estrutural consiste em tratar cada guardrail como um objeto independente com uma única responsabilidade, encadeando-os depois numa ordem definida. O benefício manifesta-se durante a manutenção: adicionar uma regra de negócio não exige alterações ao código existente, e uma regra que se torne demasiado ruidosa pode ser removida numa única linha.
Um terceiro veredicto junta-se ao «permitir» e ao «bloquear»: «modificar». Isto altera a natureza do exercício. Muitas situações do mundo real não justificam uma recusa; uma resposta que contenha um caminho interno de servidor permanece útil assim que esse caminho seja mascarado. Bloquear faria perder a informação; modificar preserva-a, removendo apenas o que constitui um problema.
from dataclasses import dataclass
from enum import Enum
class Decision(Enum):
ALLOW = "allow"
BLOCK = "block"
MODIFY = "modify"
@dataclass
class ValidationResult:
decision: Decision
reason: str
modified_content: str | None = None
class Guardrail:
"""Classe base para um guardrail."""
def validate(self, content: str, context: dict) -> ValidationResult:
raise NotImplementedError
class GuardrailPipeline:
"""Encadeia múltiplos guardrails em sequência."""
def __init__(self):
self.input_guardrails: list[Guardrail] = []
self.output_guardrails: list[Guardrail] = []
def add_input(self, guardrail: Guardrail):
self.input_guardrails.append(guardrail)
def add_output(self, guardrail: Guardrail):
self.output_guardrails.append(guardrail)
def validate_input(self, message: str, context: dict) -> ValidationResult:
for g in self.input_guardrails:
result = g.validate(message, context)
if result.decision == Decision.BLOCK:
return result
if result.decision == Decision.MODIFY:
message = result.modified_content
return ValidationResult(Decision.ALLOW, "Todas as validações foram aprovadas")
def validate_output(self, response: str, context: dict) -> ValidationResult:
for g in self.output_guardrails:
result = g.validate(response, context)
if result.decision == Decision.BLOCK:
return result
if result.decision == Decision.MODIFY:
response = result.modified_content
return ValidationResult(Decision.ALLOW, "OK", response)
Três guardrails típicos
O guardrail de âmbito mantém a conversa dentro do seu domínio. Serve tanto a segurança como a reputação: um assistente de atendimento ao cliente treinado para responder a questões sobre entregas nada ganha ao comentar notícias políticas, e uma captura de ecrã de tal resposta circula rapidamente. A lista de tópicos proibidos deve ser discutida com a equipa de negócio, nunca elaborada apenas pela equipa técnica.
class ScopeGuardrail(Guardrail):
"""Verifica se a mensagem se mantém dentro do âmbito autorizado."""
def __init__(self, allowed_topics: list[str], forbidden_topics: list[str]):
self.allowed_topics = allowed_topics
self.forbidden_topics = forbidden_topics
def validate(self, content: str, context: dict) -> ValidationResult:
content_lower = content.lower()
# Verificar tópicos proibidos
for topic in self.forbidden_topics:
if topic.lower() in content_lower:
return ValidationResult(
Decision.BLOCK,
f"Tópico fora de âmbito detetado: {topic}"
)
return ValidationResult(Decision.ALLOW, "Dentro do âmbito")
O guardrail de formato parece trivial, mas fornece o maior valor diário. Custa alguns microssegundos, não depende de chamadas de rede e corta pela raiz as mensagens oversized utilizadas para injeções volumétricas e tentativas de esgotamento de orçamento. Coloque-o primeiro na cadeia: não faz sentido pagar por moderação via API numa mensagem de 200.000 caracteres que irá rejeitar de qualquer forma.
class FormatGuardrail(Guardrail):
"""Valida o formato e o comprimento da mensagem."""
def __init__(self, max_tokens: int = 4000, max_lines: int = 100):
self.max_tokens = max_tokens
self.max_lines = max_lines
def validate(self, content: str, context: dict) -> ValidationResult:
# Estimativa aproximada de tokens (1 token ~ 4 caracteres em inglês)
estimated_tokens = len(content) // 4
if estimated_tokens > self.max_tokens:
return ValidationResult(
Decision.BLOCK,
f"Mensagem demasiado longa: ~{estimated_tokens} tokens (máx. {self.max_tokens})"
)
line_count = content.count("\n") + 1
if line_count > self.max_lines:
return ValidationResult(
Decision.BLOCK,
f"Linhas em excesso: {line_count} (máx. {self.max_lines})"
)
return ValidationResult(Decision.ALLOW, "Formato válido")
O terceiro monitoriza a saída e ilustra o uso do veredicto «modificar». As quatro famílias que procura partilham uma propriedade conveniente: possuem uma forma reconhecível independente do significado. Uma chave de API, um endereço interno, um IP privado ou um caminho de servidor são identificados pela sua estrutura, sem necessidade de compreender a frase que os contém.
import re
class AntiExfiltrationGuardrail(Guardrail):
"""Previne a fuga de dados sensíveis nas saídas."""
def __init__(self):
self.sensitive_patterns = {
"api_key": r"(sk|pk|api[_-]?key)[_-][a-zA-Z0-9]{16,}",
"internal_email": r"[a-zA-Z0-9.]+@(company|internal|corp)\.\w+",
"private_ip": r"\b(10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})\b",
"server_path": r"(/data/|/etc/|/home/|C:\\Users\\)",
}
def validate(self, content: str, context: dict) -> ValidationResult:
for data_type, pattern in self.sensitive_patterns.items():
if re.search(pattern, content):
# Mascarar em vez de bloquear
cleaned_content = re.sub(pattern, "[REDACTED]", content)
return ValidationResult(
Decision.MODIFY,
f"Dados sensíveis redigidos: {data_type}",
cleaned_content,
)
return ValidationResult(Decision.ALLOW, "Nenhuma fuga detetada")
Montagem completa
A montagem completa mostra onde as peças se encaixam. A assimetria salta à vista: dois guardrails na entrada, apenas um na saída. Isto é frequente e saudável — filtra intensamente antes de chamar o modelo, porque é aí que os custos são evitáveis, e mantém o mínimo necessário na saída para não danificar respostas corretas. A mensagem devolvida ao bloquear na saída segue a mesma cautela: intencionalmente vaga, não diz o que foi detetado, informação que serviria principalmente alguém que tentasse mapear as suas defesas.
from openai import OpenAI
def create_secure_assistant():
"""Cria um assistente com um pipeline completo de guardrails."""
client = OpenAI()
pipeline = GuardrailPipeline()
# Guardrails de entrada
pipeline.add_input(FormatGuardrail(max_tokens=2000))
pipeline.add_input(ScopeGuardrail(
allowed_topics=["products", "orders", "delivery", "returns"],
forbidden_topics=["politics", "religion", "competitors"],
))
# Guardrails de saída
pipeline.add_output(AntiExfiltrationGuardrail())
def process(message: str) -> str:
context = {"user_role": "customer"}
# Validação de entrada
input_check = pipeline.validate_input(message, context)
if input_check.decision == Decision.BLOCK:
return f"Não posso processar este pedido: {input_check.reason}"
valid_message = input_check.modified_content or message
# Chamada ao modelo
response = client.chat.completions.create(
model="gpt-5.6-sol",
messages=[
{"role": "system", "content": "Assistente de atendimento ao cliente da Acme Corp."},
{"role": "user", "content": valid_message},
],
)
reply = response.choices[0].message.content
# Validação de saída
output_check = pipeline.validate_output(reply, context)
if output_check.decision == Decision.BLOCK:
return "Não consigo responder a esta pergunta."
return output_check.modified_content or reply
return process
Quando a regra não pode ser escrita em regex
Algumas regras de negócio resistem a qualquer formalização por padrões. «A resposta não deve constituir aconselhamento de investimento», «a mensagem não deve conter dados de saúde»: nenhuma expressão regular capta isto. Um segundo modelo, rápido e barato, pode então atuar como juiz, com uma resposta constrangida ao formato JSON para permanecer utilizável pelo código chamador. O compromisso é explícito — ganha precisão ao custo de latência e determinismo, o que reserva esta abordagem para regras que verdadeiramente a justifiquem.
def llm_guardrail(message: str, rule: str) -> ValidationResult:
"""Utiliza um modelo rápido para validar a conformidade."""
client = OpenAI()
response = client.chat.completions.create(
model="gpt-5.6-terra",
messages=[
{"role": "system", "content": f"""Você é um validador de conformidade.
Regra a verificar: {rule}
Responda APENAS com JSON: {{"compliant": true/false, "reason": "..."}}"""},
{"role": "user", "content": f"Mensagem a validar:\n{message}"},
],
)
import json
result = json.loads(response.choices[0].message.content)
if result["compliant"]:
return ValidationResult(Decision.ALLOW, result["reason"])
return ValidationResult(Decision.BLOCK, result["reason"])
Pontos-chave
- Os guardrails validam a conformidade com o negócio, não apenas conteúdo ofensivo
- A arquitetura de pipeline permite combinar múltiplas camadas de validação
- Cada guardrail tem uma única responsabilidade: âmbito, formato, exfiltração, etc.
- Os guardrails de saída são tão importantes como os de entrada
- Para casos complexos, um LLM rápido pode servir de validador