Três checkpoints para Bedrock Guardrails em ferramentas

Configurar Amazon Bedrock Guardrails apenas na chamada do modelo não cobre automaticamente os parâmetros enviados às ferramentas nem os dados externos devolvidos por elas. Em um agente Strands, a proteção precisa alcançar três fronteiras: entrada, argumentos da ferramenta e resultado externo.

A arquitetura mínima registra um hook para cada etapa e transforma a avaliação em uma decisão explícita. O padrão de integração da AWS usa BeforeInvocationEvent, BeforeToolCallEvent e AfterToolCallEvent; os dois últimos fecham a lacuna entre o limite do modelo e a execução das ferramentas.

Arquitetura mínima: três fronteiras, três decisões

Fluxo de um agente Strands validando entrada, parâmetros da ferramenta e retorno externo antes de avançar.

Implemente um HookProvider e registre callbacks para os três eventos. Cada callback deve extrair o conteúdo pertinente, executar verificações determinísticas e semânticas e devolver uma decisão que o agente consiga aplicar antes de cruzar a fronteira seguinte.

BeforeInvocationEvent: verifica a entrada antes da inferência ou da execução de ferramentas. Conteúdo reprovado não deve chegar ao modelo.
BeforeToolCallEvent: verifica os parâmetros depois que o modelo escolhe a ferramenta, mas antes do efeito externo. A reprovação deve preencher event.cancel_tool.
AfterToolCallEvent: verifica o retorno antes que ele volte ao ciclo do agente. A reprovação deve substituir event.result por um resultado seguro.

Nos argumentos, valide primeiro esquema, tipos, tamanho, enumerações e permissões. Para a avaliação semântica, uma recomendação útil é serializar nome da ferramenta, nomes dos campos e valores textuais: isso preserva o contexto que seria perdido ao enviar apenas valores isolados.

Checkpoint 1: intercepte a entrada antes do modelo

No callback de BeforeInvocationEvent, encontre a mensagem que iniciou a execução e avalie os blocos de texto relevantes. Esse ponto permite detectar PII proibida, conteúdo nocivo, assuntos negados e tentativas de manipulação antes de incorporá-los ao contexto.

Com ApplyGuardrail, envie esse conteúdo com source igual a INPUT. Se a resposta trouxer action igual a GUARDRAIL_INTERVENED, encerre o caminho ou devolva uma resposta fixa controlada pela aplicação; apenas reescrever a solicitação como outra instrução ainda deixaria texto interpretável no fluxo.

Esse controle não substitui autenticação nem autorização. Mesmo uma entrada aprovada pode pedir uma operação fora do escopo do usuário, por isso a ferramenta ainda precisa verificar identidade, privilégios e regras de negócio.

Checkpoint 2: valide os argumentos antes do efeito externo

BeforeToolCallEvent é o último ponto de bloqueio antes de uma ação real. Confira o contrato local da ferramenta e, em seguida, aplique as salvaguardas semânticas aos campos que possam transportar texto livre, credenciais, PII ou instruções.

Em uma ferramenta hipotética send_email, valide destinatários com regras determinísticas e examine assunto e corpo para evitar divulgação indevida. Em uma execute_sql, restrinja operações, tabelas e credenciais por autorização; um filtro de linguagem não deve decidir sozinho se uma consulta pode ser executada.

A política pode variar por ferramenta. Uma busca pública tolera consultas mais amplas, enquanto um CRM pode proibir CPF, segredos ou registros completos nos argumentos. Ao reprovar a chamada, defina event.cancel_tool antes de abrir conexão, gravar dados ou enviar mensagens.

Checkpoint 3: trate o retorno como entrada não confiável

AfterToolCallEvent deve examinar textos vindos de APIs, páginas, documentos e servidores MCP antes que retornem ao agente. Uma solicitação legítima pode produzir uma resposta externa com PII ou prompt injection, como uma ordem para ignorar instruções anteriores.

Extraia os blocos textuais, preserve o identificador da chamada e use a política de saída. Se houver intervenção, substitua o retorno por um erro sanitizado; acrescentar um aviso sem remover o conteúdo reprovado mantém esse conteúdo disponível para a próxima inferência.

Resultados estruturados também precisam de esquema e limites de volume. Binários e formatos não abrangidos pela inspeção textual exigem controles próprios antes de serem convertidos em texto ou incluídos no contexto.

ApplyGuardrail ou InvokeGuardrailChecks

Comparação entre uma intervenção do ApplyGuardrail e pontuações do InvokeGuardrailChecks convertidas em decisões pela aplicação.

Use ApplyGuardrail quando já existe um guardrail identificado e versionado, com políticas configuradas para INPUT ou OUTPUT. O hook pode converter GUARDRAIL_INTERVENED diretamente em bloqueio da entrada, cancelamento da ferramenta ou substituição do retorno.

InvokeGuardrailChecks atende fluxos que precisam selecionar verificações em cada etapa sem criar previamente um recurso de guardrail. A documentação do modo detect-only confirma que a API pode ser chamada antes ou depois de ferramentas, retorna pontuações entre zero e um e não bloqueia, aprova nem oculta conteúdo por conta própria.

Nesse desenho, a aplicação converte os achados em política operacional: pode bloquear acima de um limiar definido, permitir abaixo dele ou encaminhar casos intermediários para revisão humana. Uma nova tentativa só é segura quando puder corrigir a causa sem repetir um efeito externo já iniciado.

Permissões e testes contra falsa proteção

O papel de execução deve receber apenas as ações necessárias. ApplyGuardrail exige bedrock:ApplyGuardrail; para a alternativa detect-only, a política IAM de InvokeGuardrailChecks usa bedrock:InvokeGuardrailChecks com Resource igual a *, pois a operação não possui um ARN de guardrail ao qual a permissão possa ser limitada. Políticas de identidade, SCPs e chaves de condição podem restringir quem faz a chamada.

Automatize casos positivos e negativos em cada fronteira:

Envie uma solicitação permitida e confirme que os três checkpoints deixam o fluxo avançar.
Inclua um CPF ou e-mail fictício de teste na entrada e confirme o bloqueio conforme a política, sem executar ferramentas.
Produza, em ambiente controlado, PII em um argumento e confirme que BeforeToolCallEvent cancela a chamada antes do efeito externo.
Simule uma busca que devolve prompt injection e confirme que AfterToolCallEvent substitui o conteúdo antes da inferência seguinte.
Simule PII no retorno e verifique bloqueio, ocultação ou revisão segundo a política, sem registrar o valor bruto.
Force timeout da avaliação e confirme o comportamento fail-closed nas ferramentas de alto impacto.

Nos registros, guarde checkpoint, ferramenta, versão da política, decisão e latência, não o conteúdo sensível. A cobertura só está completa quando cada fronteira tem uma decisão definida para aprovação, bloqueio, falha da avaliação e revisão humana.

Bedrock Guardrails não vigia as ferramentas: feche a brecha em três pontos