Guardrails: a barreira que o agente não consegue contornar

Correções de 12/10/2026 (PR #898, 11/10/2026). (1) O modo sombra foi substituído pelo desfecho Sinalizar: a regra avalia, registra na trilha e numa lista de sinais, e nunca nega; onde este documento diz "modo sombra", leia "sinalizar". (2) Há um quinto tipo de decisor, o classificador IA (uma pergunta de sim ou não ao classificador da plataforma), que vale em qualquer momento, inclusive antes de uma ferramenta. (3) A área da organização não é mais a tela "Guardrails": é a sub-aba Regras da aba Classificações e Guardrails — o endereço antigo redireciona. (4) Criar, editar, excluir e testar guardrails da organização exige a permissão Gerenciar regras (e não mais ser dono ou administrador). Detalhes em cada seção abaixo, que mantém o texto anterior como histórico.

Camada funcional

Pedir a um agente, nas instruções, que ele não faça algo depende de o modelo lembrar do pedido. Isso não é barreira: é torcida.

Um guardrail é a outra coisa. Ele roda fora do agente, em pontos definidos do turno, e o resultado dele não é uma sugestão: é permissão, recusa ou correção — e qual desses três está disponível depende de quando ele dispara, porque uma ferramenta que já rodou não dá para impedir. Três eixos o descrevem:

• Onde vale — na organização inteira, ou num agente específico.
• Quando dispara — um dos quatro momentos do turno, e não só "antes de usar uma ferramenta".
• Quem decide — negar direto pela regra, perguntar a um sistema seu, perguntar a um modelo, perguntar a um agente da sua própria organização, que julga pelas instruções que ele tem, ou (desde 11/10/2026) perguntar ao classificador IA da plataforma.

O que a organização define, o agente não afrouxa

O guardrail da organização é sempre avaliado. A configuração de um agente pode somar restrições — nunca relaxar, nunca desligar o que a organização definiu.

E a tela do agente mostra a política da organização primeiro, em modo leitura. A intenção é que ninguém descubra que ela existe só no momento em que o agente travar.

Como você usa

1. Para a organização, na aba "Classificações e Guardrails" da Governança (sub-aba Regras): quem tem a permissão "Gerenciar regras" cria, edita, remove e testa; quem só tem "Ver a governança" vê a aba em leitura. Antes de 11/10/2026: quem administrava a organização escrevia e qualquer membro lia a lista na tela de guardrails (a leitura da tabela continua aberta a membros no banco; a tela exige "Ver a governança").
2. Para um agente, no menu de mais opções do diálogo do agente: disponível para quem pode configurar aquele agente. A tela mostra primeiro, em leitura, o que vem da organização — com o selo da origem — e depois o que é daquele agente.
3. Ao criar um guardrail você escolhe quando ele dispara, em que ferramentas (todas, ou uma lista), que condição filtra a chamada antes de acionar o julgamento, quem decide e o que fazer com uma reprovação: bloquear, ou — só no gatilho de antes da ferramenta — reescrever o argumento.
4. O formulário documenta o contrato enquanto você preenche: para cada gatilho, quais dados chegam ao julgamento; para cada tipo de decisor, o formato de resposta esperado, com exemplo copiável. Esse texto sai da mesma definição que o avaliador consome, então ele não pode divergir do que a máquina faz.
5. O botão Testar roda o guardrail contra uma entrada de exemplo, sem gravar nada, e mostra o veredito cru — inclusive o motivo que o agente receberia. Ele existe porque, antes, um sistema seu respondendo fora do formato só dava sinal quando um agente real travava no meio de uma tarefa. Desde 21/09/2026, o teste também respeita a lista de ferramentas do guardrail antes de avaliar a condição: um guardrail restrito a uma ferramenta, testado com o exemplo de outra, responde que nem chegaria a ser consultado — antes, respondia como se a condição tivesse passado, o que podia convencer alguém de que uma regra estava certa sem ela nunca ter sido de fato exercitada.
6. O efeito vale a partir da próxima execução. A política é montada quando o agente parte. Uma conversa já em andamento não recebe a política nova, e a tela diz isso em vez de prometer efeito imediato.

Os quatro momentos

Antes de usar uma ferramenta vale em todos os motores de execução. Depois de usar uma ferramenta e ao encerrar o turno só são avaliados quando o agente roda no executor Claude Code — nos outros motores eles não chegam a ser consultados.

Antes de o agente formular a resposta é a exceção, desde 27/08/2026: essa barreira passou a ser avaliada assim que a mensagem chega, antes de o agente começar a trabalhar — e por isso independe do motor. A seção abaixo conta o que muda na conversa.

A tela avisa isso ao escolher depois de usar uma ferramenta ou ao encerrar o turno — os dois que ela marca como indisponíveis fora do executor Claude Code. O aviso não impede salvar, porque o mesmo agente pode trocar de executor depois, e uma configuração recusada agora teria que ser refeita lá na frente.

A recusa passou a aparecer na hora, e com o motivo certo (27/08/2026)

Até 26/08/2026, a barreira antes de o agente formular a resposta só era decidida depois que o agente já tinha começado a trabalhar. Ela funcionava — nenhum texto barrado chegava ao modelo —, mas o que a conversa mostrava enganava: o turno terminava sem resposta nenhuma, e aparecia "O agente interrompeu o trabalho inesperadamente", igual a uma falha real, no lugar do motivo da política. Em alguns casos a plataforma chegava a trocar o agente de executor, como se a causa fosse o executor e não uma decisão de governança.

Agora a mesma barreira é avaliada assim que a mensagem chega. Duas consequências:

• O motivo da política aparece na hora, como uma mensagem do agente na conversa, em vez de um aviso de falha depois da espera.
• Passa a valer em todos os motores, inclusive naqueles que não tinham como avaliá-la antes.

Essa avaliação antecipada é o único ponto do mecanismo que, ao falhar por conta própria, deixa a mensagem seguir em frente — e ela segue direto para a barreira que já existia, que continua recusando por padrão. O contrário custaria mais caro do que protege: uma instabilidade em ler a política pararia toda conversa da plataforma, e não só as que a política alcança.

A mensagem barrada e o aviso da política continuam visíveis na conversa, para mostrar o que aconteceu, mas não voltam a ser enviados ao agente nas mensagens seguintes.

Na dúvida, bloqueia

Um guardrail é uma barreira de segurança, e barreira de segurança que falha aberta não é barreira. Todas as situações de falha foram desenhadas para o mesmo lado:

A única exceção deliberada é o desfecho Sinalizar (que substituiu o modo sombra em 11/10/2026): o guardrail avalia, registra na trilha e na lista de sinalizadas e nunca nega; a falha técnica de uma regra que só sinaliza vira sinal, não bloqueio. Serve para medir o efeito de uma regra antes de fazê-la bloquear.

Toda reprovação fica registrada

Reprovar — inclusive numa regra que só sinaliza (antes, modo sombra) — grava na trilha de auditoria, como evento de segurança, com o agente identificado como autor.

Criar, editar e remover um guardrail da organização também grava, como acesso administrativo. Remover é a única ação dessa tela que amplia o que os agentes podem fazer, e por isso é a que mais importa ter registrada.

Desde 21/09/2026, cada avaliação de uma chamada carrega um identificador próprio na trilha. Sem ele, duas linhas de guardrails diferentes reprovando na mesma trilha só compartilhavam agente, conversa, nome da ferramenta e um horário parecido — o suficiente para parecer a mesma chamada sem necessariamente ser. Com o identificador, dá para confirmar que duas regras em modo sombra reprovaram exatamente a mesma chamada, e é assim que se simula "isto E aquilo" cruzando duas regras separadas, sem trazer a condição composta de volta para dentro do guardrail em si.

Três decisões que valem explicar

A condição não aceita expressão regular. Só "sempre" e "contém". Isso é decisão, não lacuna: a condição roda antes de cada chamada de ferramenta, e um padrão mal formado travaria a ferramenta até o teto de tempo, em vez de apenas degradar. A mesma razão já valia para as condições de esteira.

A condição recusa o que não reconhece, em vez de aceitar em silêncio. Até 21/09/2026, uma condição com um campo a mais (tentando expressar "isto E aquilo", por exemplo) não dava erro nenhum — o campo extra era simplesmente ignorado, e a regra passava a valer só pela metade que sobrou, quase sempre a metade mais ampla dela. Uma regra pensada como "bloqueia a leitura E a escrita de um arquivo sensível" que perdesse a segunda metade em silêncio passava a bloquear qualquer leitura — inclusive as que a pessoa nunca quis travar. Hoje esse campo extra é recusado na hora, nomeando o que não é reconhecido: a condição não tem "e"/"ou" mesmo, e quem precisa das duas coisas ao mesmo tempo cria dois guardrails e cruza os dois na trilha de auditoria (ver abaixo).

O agente que julga julga, não executa. Quando o decisor é um agente da organização, o que se usa são as instruções e o modelo dele — ele não roda as próprias ferramentas nem abre conversa. O motivo é temporal: toda execução de agente é assíncrona por construção, e um veredito síncrono exigiria subir uma máquina e ficar perguntando se já acabou. A partida a frio, sozinha, costuma estourar o teto de espera do guardrail — que, bloqueando por padrão, travaria tudo.

O classificador IA (11/10/2026)

Um decisor novo: em vez de um sistema seu ou de um modelo com critério livre, a regra faz uma pergunta de sim ou não ao classificador da plataforma ("a ação envia dado de cliente para fora da empresa?"), com o critério do que conta como sim e como não, e uma certeza mínima para reprovar. "Sim" quer dizer que a ação viola a regra. Não reescreve (só bloqueia ou sinaliza). Roda em qualquer um dos quatro momentos.

O custo em tempo, dito com franqueza. Medido em 11/10/2026 (80 chamadas reais): mediana de cerca de 0,19 s, mas a cauda chega a cerca de 1,3 s no percentil 95 e 1,5 s no máximo, sem relação com o tamanho da chamada. Primeiro, o classificador ficou de fora do momento "antes de uma ferramenta" por causa disso; no mesmo dia a decisão foi liberar todos os momentos, como no protótipo aprovado: antes de uma ferramenta, o agente espera essa latência a cada chamada que a regra cobre. Quem cria a regra escolhe o momento sabendo disso. Falha técnica (tempo esgotado ou erro) reprova, como no juiz por modelo.

Sinalizadas e números por regra

Cada reprovação de uma regra que só sinaliza grava um sinal (regra, agente, conversa, execução, momento, certeza quando houver e um trecho do conteúdo com segredos mascarados), visível na sub-aba Sinalizadas. O cartão de cada regra mostra "Sinalizou N vezes nos últimos 30 dias" (regra que só sinaliza) ou "Barrou N vezes" (regra que bloqueia): é o número que diz se uma regra está pronta para passar a bloquear.

O que dá para fazer, e onde