Guardrails: segurança e responsible AI

Um guardrail é um conjunto de políticas que você compõe. Cada uma é opcional e independente — habilite só o que o caso exige, porque cada uma tem custo e latência. São seis famílias, das mais simples (match de palavra) às mais sofisticadas (prova matemática):

Os content filters classificam texto (e imagem) em seis categorias de dano — hate, insults, sexual, violence, misconduct e prompt attack. Para cada uma você escolhe a força do filtro (none/low/medium/high) e aplica separadamente ao input (o prompt) e ao output (a resposta do modelo). Um detalhe que morde na integração: a categoria prompt attack só se aplica ao input — jailbreak e prompt injection são tentativas de entrada, então não adianta esperar que ela filtre a saída.

Três salvaguardas cobrem o dia a dia de compliance e privacidade. São determinísticas ou quase — não dependem de julgar 'toxicidade', e sim de regras que você declara:

• Denied topics — você descreve o assunto proibido em português mesmo ('recomendação de dosagem de medicamento', 'aconselhamento jurídico vinculante'). O guardrail bloqueia perguntas E respostas que caírem no tópico, sem exigir uma lista de palavras que sempre fica incompleta.
• Word filters — lista literal de palavras/frases (nomes de concorrentes, termos internos que não podem vazar) mais um filtro de profanidade já pronto. É match exato, previsível e barato — costuma ser gratuito.
• Sensitive information filters (PII) — detecta tipos prontos (e-mail, telefone, nome, endereço, cartão de crédito...) e aceita regex custom para o que é específico do seu domínio (CPF, matrícula). Para cada tipo você escolhe BLOCK (recusa a resposta inteira) ou MASK (troca por {EMAIL}, {CPF}...). MASK é o que você quer em log e RAG; BLOCK, em fluxo que não pode nem tocar no dado.

As duas salvaguardas contra alucinação parecem fazer a mesma coisa — garantir que a resposta seja verdadeira — mas são de naturezas opostas, e essa é a distinção mais importante do módulo. Uma estima uma confiança; a outra prova uma verdade.

O contextual grounding check ficou GA em julho de 2024 e devolve dois números: um grounding score (quão ancorada a resposta está na fonte) e um relevance score (quão relevante ela é para a pergunta). Você define um threshold para cada; abaixo do corte, o guardrail bloqueia e você devolve um fallback do tipo 'não encontrei isso na base'. É probabilístico: o serviço estima uma confiança, não uma verdade. Threshold alto reduz alucinação mas aumenta falsos positivos (bloqueia resposta boa). É a checagem certa para toda resposta de um RAG.

Os automated reasoning checks ficaram GA em agosto de 2025 e são de outra espécie. Você cria uma Automated Reasoning Policy: descreve as regras do domínio em documentos, e o serviço as traduz para lógica formal (fórmulas matemáticas). Em runtime, ele prova se a resposta é logicamente consistente com a policy e devolve verified (provado verdadeiro), contradicted (provado falso) ou indeterminate (não deu para provar). A AWS reivindica até 99% de acurácia de verificação — trate como claim deles. Desde nov/2025 a policy gera automaticamente perguntas-e-respostas de teste em linguagem natural para você validá-la. É determinístico: mesma entrada, mesma prova.

A ApplyGuardrail API é o que transforma o guardrail de 'anexo de uma chamada Converse' em 'serviço de moderação standalone'. Ela avalia um texto ou imagem contra suas políticas sem invocar nenhum foundation model — você não paga inferência, só as text units do guardrail. Como o texto avaliado pode ter vindo de qualquer lugar, o guardrail vira uma etapa reutilizável do seu pipeline, não um acessório de uma chamada específica.

Isso se completa com o policy-based enforcement (mar/2025): via IAM você pode exigir que toda invocação de modelo passe por um guardrail, de modo que nenhum time consiga chamar um FM 'pelado'. É governança centralizada de verdade — segurança define a baseline, produto não tem como burlar.

Há dois caminhos. Desacoplado: você chama apply_guardrail direto sobre qualquer texto — serve para qualquer FM, inclusive de fora do Bedrock. Acoplado: você passa guardrailConfig na chamada Converse, e o Bedrock aplica o guardrail ao prompt e/ou à resposta — e pode marcar só blocos específicos com guardContent (útil para não moderar o system prompt).

import boto3

# bedrock-runtime: o MESMO client de inferencia
brt = boto3.client("bedrock-runtime", region_name="us-east-1")

# 'saida' pode ter vindo de QUALQUER modelo: OpenAI, Gemini, ou um
# Llama self-hosted no seu EC2/SageMaker. O Bedrock nao precisa ter
# gerado esse texto para avalia-lo.
saida = chamar_meu_modelo_externo(prompt_do_usuario)

resp = brt.apply_guardrail(
    guardrailIdentifier="arn:aws:bedrock:us-east-1:111122223333:guardrail/gr-abc123",
    guardrailVersion="1",              # "DRAFT" em dev; "1", "2"... em prod
    source="OUTPUT",                   # avaliando a RESPOSTA (use "INPUT" p/ o prompt)
    content=[{"text": {"text": saida}}],
)

if resp["action"] == "GUARDRAIL_INTERVENED":
    # texto ja mascarado/bloqueado conforme suas politicas
    saida = resp["outputs"][0]["text"]
    for assessment in resp["assessments"]:
        print("politicas acionadas:", list(assessment.keys()))

usage = resp["usage"]  # text units por politica -> base do custo

import boto3

brt = boto3.client("bedrock-runtime", region_name="us-east-1")

# Caminho ACOPLADO: o guardrail roda dentro da propria chamada Converse,
# no prompt e na resposta, numa unica ida ao servico.
resp = brt.converse(
    modelId="anthropic.claude-3-5-sonnet-20241022-v2:0",
    messages=[{"role": "user", "content": [{"text": "Pergunta do usuario..."}]}],
    guardrailConfig={
        "guardrailIdentifier": "gr-abc123",
        "guardrailVersion": "1",
        "trace": "enabled",   # devolve o assessment em resp['trace']['guardrail']
    },
)

stop = resp["stopReason"]  # "guardrail_intervened" se o guardrail agiu
texto = resp["output"]["message"]["content"][0]["text"]

Guardrails cobram por text unit (≈ 1.000 caracteres) e por política acionada — o custo de uma chamada é a soma das políticas que rodaram nela. Por isso a regra de ouro é habilitar o que o caso pede, não tudo por padrão.