O guardrail

O guardrail verifica cada chamada de ferramenta que um agente de LLM faz antes de ela rodar, e responde permitir, perguntar à pessoa ou recusar, citando a regra que decidiu. Ele funciona com qualquer agente: dê a ele as ferramentas que você dá ao seu modelo, e ele verifica cada chamada que o modelo propõe.

Nada nele é adivinhado por um modelo de linguagem: a mesma chamada e as mesmas regras sempre dão a mesma resposta.

Garantido:

• Toda chamada de ferramenta é verificada antes de ser executada, pelas mesmas regras, e a mesma chamada, contexto e regras sempre dão a mesma resposta.
• Uma ferramenta fora da sua lista nunca é executada; uma chamada cujos valores quebram a descrição da própria ferramenta nunca é executada.
• Uma escrita que nenhuma regra permitiu nunca é executada sem o sim de uma pessoa, e esse sim cobre exatamente a chamada mostrada.
• Um valor numa escrita que ninguém disse e nenhuma ferramenta devolveu é perguntado.
• Nada numa decisão é adivinhado por um modelo de linguagem.

Não garantido:

• Ele julga ferramentas, argumentos, rótulos, histórico e regras, não o que uma resposta quer dizer.
• Ele não distingue um valor certo de um errado que alguém de fato disse.
• Suas regras são tão completas quanto você as escreveu: o caçador de falhas procura brechas.
• Uma ferramenta cujo nome e descrição escondem o que ela faz pode ser classificada errado: marque-a.
• Chamadas feitas fora do guardrail não são verificadas.

Os passos abaixo seguem um atendimento ao cliente, com quatro ferramentas: consultar um pedido, reembolsar um cartão, enviar um e-mail e salvar uma nota. Os números de cada imagem correspondem aos passos numerados abaixo dela, e cada linha de uma imagem foi impressa pelo próprio guardrail.

O que cada verificação faz

Todas as regras do guardrail, na ordem em que são aplicadas; decide a primeira que se aplica.

Verificação	O que faz, simplesmente	Quando barra uma chamada	Pode ser desligada
Tipos de ferramenta	Sabe-se se cada ferramenta lê, altera algo ou envia algo para fora: pelo seu arquivo, pelas marcas da própria ferramenta, ou pelo nome, descrição e argumentos. Uma ferramenta que ninguém marcou conta como uma que altera algo.	perguntada (uma ferramenta que não se sabe que lê é uma escrita)	sim
Ferramenta retirada	Uma ferramenta que o dono retirou do registro não pode ser usada.	recusada	não
Endereço não permitido	Uma chamada não pode chegar a um endereço que você não permite, como o serviço de metadados da nuvem ou a rede interna da empresa.	recusada	sim
Fora do plano aprovado	Onde uma pessoa aprovou um plano, uma chamada que não é o próximo passo dele não é executada.	recusada	sim
Nível de ferramentas do plano	Ainda não ativa: toda chamada passa.	nunca (ainda não ativa)	sim
Rótulos	Ainda não ativa: toda chamada passa. Conteúdo de fora é barrado pela verificação de conteúdo de fora.	nunca (ainda não ativa)	sim
Limite de pagamento	Ainda não ativa: toda chamada passa. Limites de gasto ficam nas suas regras.	nunca (ainda não ativa)	sim
Ferramentas permitidas	Só ferramentas da sua lista podem ser usadas, e só por um agente nomeado onde você indicar.	recusada	não
Registro da sessão	O registro das chamadas já feitas deve estar intacto; se alguém o alterou, nada mais é executado.	recusada	não
Argumentos	Os valores de cada chamada devem caber na descrição da própria ferramenta (tipos, campos obrigatórios, valores permitidos).	recusada	sim
Destinos	Uma ferramenta só pode enviar algo a um endereço se for conhecida por enviar coisas para fora.	recusada	sim
Ordem	Uma ferramenta só é executada num ponto permitido: depois de outra, nunca depois de outra, ou no máximo N vezes.	recusada	sim
Desfazer	Um desfazer deve corresponder ao passo que reverte, e um passo só é desfeito uma vez.	recusada	sim
Suas regras	Sua própria planilha de regras decide, por ex. "reembolsos acima de 100 precisam de um gerente"; limites por período e de gasto também.	recusada ou perguntada, como a regra diz	sim
Conteúdo de fora	Uma chamada proposta depois de ler conteúdo de fora (uma página, um e-mail) é barrada onde você proíbe.	recusada, ou perguntada onde sua configuração pede	sim
Confirmação	Uma chamada que precisa do sim de uma pessoa só é executada com esse sim, assinado; se ninguém pode dá-lo, ela não é executada.	recusada	não
Qualquer outra escrita	Qualquer coisa que altera algo e que nenhuma regra permitiu espera o sim de uma pessoa.	perguntada	não
Origem dos valores	Um valor numa escrita que ninguém disse e nenhuma ferramenta devolveu é perguntado, nunca permitido e nunca recusado.	perguntada	sim
S1: verbo de envio	Onde a fala da pessoa pede para enviar algo para fora e nenhuma ferramenta envia, a chamada é barrada.	perguntada por padrão; recusada no modo estrito	sim
S2: destino	Onde a fala nomeia um lugar para onde enviar que nenhuma ferramenta recebe, e a chamada também não o recebe, a chamada é barrada.	perguntada por padrão; recusada no modo estrito	sim
Leitura de confirmação	A chamada é lida contra a fala, com os valores como digitados. Onde a fala dá um valor que falta na chamada, ou um diferente, a pessoa vê os dois e é perguntada. A chamada nunca é alterada.	perguntada por padrão; recusada no modo estrito	sim

1. Coloque o guardrail na frente das suas ferramentas

1. Em Python, três linhas: o guardrail é criado a partir das ferramentas que você dá ao seu modelo, e cada chamada é verificada antes de o seu código executá-la. Instale com pip install stalwart-agents.
2. Na frente de um servidor MCP, o stalwart gateway verifica cada chamada a caminho do servidor. A ferramenta snippet do stalwart mcp escreve a configuração para você.

2. Escreva as suas regras

1. As suas regras são uma planilha de regras: YAML simples que uma pessoa consegue ler em voz alta. Aqui, um reembolso acima de 100 precisa da aprovação de um gerente, e todo e-mail espera o sim de uma pessoa.
2. A planilha é compilada uma vez; as decisões são tomadas depois na sua própria máquina.
3. A planilha é conferida contra as suas ferramentas: aqui, save_note altera algo e nenhuma regra a nomeia, então você é avisado e pode decidir.

3. Uma chamada é permitida, perguntada ou recusada

1. Consultar um pedido só lê, então é permitido.
2. Um reembolso de 20 altera algo e nenhuma regra o permite de vez, então espera o sim de uma pessoa.
3. Um reembolso de 150 quebra a regra do passo 2, então é recusado, e a resposta cita a regra e dá um id para consultá-la.

4. Um valor que ninguém disse é perguntado

1. A pessoa pediu um reembolso mas nunca disse quanto. O modelo propôs 35 mesmo assim.
2. Ninguém disse 35 e nenhuma ferramenta o devolveu, então o guardrail pergunta à pessoa antes de qualquer coisa rodar. Ele nunca preenche um valor, e nunca altera a chamada.

5. Adicione ao seu guard do Guardrails AI

1. Instale stalwart-agents[guardrails] e acrescente o nosso validador ao seu guard. Uma chamada recusada chega como a própria falha do Guardrails AI, com a frase da regra.
2. Com on_fail=gai.ask, uma chamada que precisa de uma pessoa é retida, e gai.asked(guard) dá a frase para mostrar a ela. Com o sim, valide a mesma chamada de novo com o token que gai.approve dá.

6. Pergunte ao servidor MCP o que ele faz

1. Acrescente o stalwart mcp ao seu assistente de IA (Claude Code, Cursor, VS Code) e pergunte o que o guardrail consegue verificar: ele responde a partir da própria lista do guardrail.
2. Pergunte como adicioná-lo ao seu guard do Guardrails AI, e você recebe os passos. O prompt build-guardrail conduz o seu assistente para construir um com você; ele nunca chama um modelo nosso.

7. Meça nas suas próprias chamadas

1. replay passa as chamadas antigas do seu agente pelo guardrail: quantas ele teria permitido, perguntado e recusado, por qual regra, e se uma segunda execução deu as mesmas respostas.
2. Rotule cada chamada com o que deveria ter acontecido, e evaluate conta os alarmes falsos (chamadas que deveriam rodar, barradas) e as falhas (chamadas que deveriam ser barradas, deixadas passar).

8. Procure brechas nas suas regras

1. hunt roda o caçador de falhas na sua planilha de regras. Cada achado é algo que as suas regras deixam passar, com o que olhar; aqui, ele pede que você diga sem o que refund_card nunca pode rodar, já que nenhuma tabela sua o diz.

9. Por que esta chamada foi recusada?

1. explain_decision lê de volta uma decisão pelo seu id: a regra, o que ela leu, a ferramenta e os nomes dos seus argumentos. Os valores em si, e o que a pessoa disse, nunca são guardados.

Para ir além

O manual completo, em inglês e português, está na documentação do SDK: construindo um guardrail, as verificações, a planilha de regras, avaliando e conectando. O stalwart mcp serve as mesmas páginas ao seu assistente.