São 3 da manhã. Seu agente tem trabalhado em uma fila de tickets de suporte enquanto você dorme. Um ticket parece uma escalada, então o agente escreve um resumo e o envia por e-mail para seu chefe. O resumo é preciso. A gramática está impecável. O problema é que ninguém pediu aquele e-mail, ninguém o leu primeiro, e nada poderia tê-lo impedido uma vez que o agente decidiu enviá-lo. O agente fez exatamente o que suas instruções permitiam. Essa é a parte que deveria tirar seu sono.
As falhas que mais doem não são aquelas em que o modelo alucina ou o processo trava. Essas são óbvias, e falhas óbvias são detectadas. As perigosas são silenciosas. O agente faz precisamente o que lhe foi dito, e o resultado ainda é ruim, porque ele enviou o e-mail, excluiu o registro ou fez o pedido, e nada se interpôs entre a decisão do modelo e a ação ao vivo.
Mecanismos de segurança (guardrails) são o que se interpõem. Um mecanismo de segurança é a camada que inspeciona uma ação antes que ela aconteça e decide se deve permiti-la, bloqueá-la ou perguntar a um humano primeiro. Este guia cobre quatro tipos que você pode construir (listas de permissão de ações, portões de aprovação, modo de simulação e limites de raio de impacto) e, em seguida, o passo que a maioria das equipes pula: provar que o mecanismo de segurança funciona. Se você quiser o contexto mais amplo primeiro, nosso pilar sobre por que agentes de IA falham em produção classifica as falhas dos agentes em cinco modos, e a ausência de mecanismos de segurança é o quinto.
Classifique as ações pelo seu potencial de dano
Nem toda ação precisa de um portão. Um agente que lê um calendário, busca uma previsão ou consulta um relatório somente leitura pode operar em velocidade máxima sem supervisão humana. Envolver essas ações em aprovações apenas treina sua equipe para clicar em "sim" sem pensar, o que torna as aprovações inúteis quando elas realmente importam.
Então, o primeiro mecanismo de segurança é um trabalho de classificação. Divida as ações que seu agente pode realizar em duas listas. A lista de permissões (allowlist) contém chamadas seguras para serem executadas automaticamente: leituras, buscas, consultas idempotentes, qualquer coisa reversível. Tudo o mais precisa de um portão: envios, exclusões, pagamentos, escritas em sistemas de registro, qualquer coisa que um cliente ou colega veria. Um teste útil para a segunda lista é a pergunta "se o agente fizesse isso cem vezes por engano, quão ruim seria?". Se a resposta for pior do que um encolher de ombros, a ação não pertence à lista de permissões.
Seja honesto sobre os casos intermediários. Um `POST` que cria um rascunho é reversível. Um `POST` que cria um rascunho e o envia por e-mail não é. Duas chamadas que parecem semelhantes em seu código podem estar em lados opostos da linha. Classifique pela consequência, não pelo verbo HTTP.
Coloque um humano no circuito para ações destrutivas
Uma vez que você sabe quais ações são perigosas, o próximo mecanismo de segurança é um portão de aprovação: o agente pausa antes da ação, mostra o que pretende fazer e espera que uma pessoa confirme. Este é o padrão "humano no circuito" (human-in-the-loop), e é o mecanismo de segurança de maior valor que você pode adicionar, porque transforma um erro irreversível em uma solicitação rejeitada.
Um bom portão mostra ao humano o suficiente para decidir. Não "o agente quer enviar um e-mail", mas o destinatário, o assunto e o corpo. Não "excluir um registro", mas qual registro e por quê. O desenvolvedor que aprova a ação nunca deve ter que confiar no resumo do agente sobre o que ele está prestes a fazer. Mostre a solicitação real.
Mantenha o portão barato para recusar. Se rejeitar uma ação for lento ou confuso, as pessoas aprovam por reflexo, e você estará de volta a não ter nenhum mecanismo de segurança. Os fóruns do SDK da Anthropic têm uma discussão recorrente sobre adicionar uma etapa de aprovação humana antes que um agente atue, e o tema que continua retornando é que o portão deve ser legível: um revisor que não consegue ver a carga útil concreta não pode tomar uma decisão real. Registre cada aprovação e rejeição também. Quando algo escapar, o registro é como você descobrirá qual portão falhou.
Dê ao agente um modo de simulação
Portões de aprovação protegem a produção. O modo de simulação (dry-run) protege sua confiança antes de chegar lá. No modo de simulação, o agente faz tudo o que faria normalmente, escolhe a ferramenta, constrói a solicitação, decide os argumentos, mas para na última etapa e relata o que teria enviado em vez de realmente enviar.
Isso vale por si só por duas razões. Primeiro, permite que você observe uma execução completa do agente contra entradas reais sem efeitos colaterais ao vivo, o que é a maneira segura de ver como o agente se comporta em uma nova tarefa. Segundo, torna as intenções do agente inspecionáveis. Você obtém uma transcrição de cada chamada que ele quis fazer, em ordem, com argumentos, e pode ler isso como um plano. Se o plano estiver errado, você descobriu de graça. Uma ferramenta dedicada de depuração de agentes de IA para essas chamadas pretendidas transforma um vago "o agente fez algo estranho" em um específico "ele tentou chamar o endpoint de exclusão na quarta etapa".
O modo de simulação não é o mesmo que um portão de aprovação, e você quer ambos. O modo de simulação é para desenvolvimento e homologação, onde nada é real. O portão de aprovação é para produção, onde tudo é.
Limite o raio de impacto
Listas de permissões, portões e modo de simulação decidem se uma única ação acontece. Os limites de raio de impacto decidem o tamanho do dano que o agente pode causar em muitas ações, incluindo as que você aprovou. Eles são o limite máximo de dano total.
Três limites carregam a maior parte do peso. Escopos: dê ao agente credenciais que só podem tocar no que ele precisa. Um agente que gerencia os problemas de um projeto deve ter um token com escopo para esse projeto, não uma chave de administrador para toda a organização. Cotas: limite quantas vezes uma ação pode ser executada em um período, para que um loop travado atinja uma parede em vez de enviar mil e-mails. Limites de gastos: coloque um teto rígido em tokens e em qualquer ação que custe dinheiro, por tarefa e por dia, para que um agente descontrolado falhe de forma controlada em vez de gerar faturas para o próximo trimestre.
Esses limites também são sua rede de segurança quando um mecanismo de segurança mais sutil falha. Um agente que passa por um portão ainda não pode exceder seu escopo. Para saber se um limite está funcionando, você precisa observá-lo, então rastreie as contagens que alimentam cada limite, chamadas por ação, gastos por tarefa, taxas de erro próximas ao teto, da mesma forma que faria com a observabilidade de API em qualquer serviço de produção. A OWASP nomeia o risco subjacente diretamente. "Agência excessiva" está no Top 10 da OWASP para aplicações LLM, e cada limite aqui é uma maneira de conceder menos disso.
Como testar um mecanismo de segurança
Aqui está a verdade desconfortável. Cada mecanismo de segurança acima é um ramificação em seu código que só é executado quando algo perigoso está prestes a acontecer. Esses ramificações são os caminhos menos exercitados em todo o sistema, o que os torna os mais propensos a estarem silenciosamente quebrados. Um portão que nunca é acionado parece idêntico a um portão que é acionado e ignorado. Um mecanismo de segurança que você não testou é um mecanismo de segurança que você não tem.
Você não pode testar isso contra a API real, porque testar contra a API real significa enviar o e-mail de verdade para descobrir se você queria. O método é simular o endpoint com efeito colateral e verificar qual caminho o agente toma.
O ciclo é assim:
- Simule o endpoint destrutivo. Crie um simulacro da API de envio, exclusão ou pagamento para que a real nunca seja tocada. O simulacro registra o que recebe e retorna a resposta que você lhe disser.
- Execute o agente na ação perigosa. Conduza-o pelo cenário que deveria acionar o mecanismo de segurança: o ticket de escalada, a solicitação de exclusão, o pedido de alto valor.
- Verifique o caminho, não o resultado. Verifique se o simulacro do endpoint ao vivo recebeu zero chamadas e se a solicitação de aprovação foi acionada, com a carga útil correta. A condição de aprovação é "o agente perguntou" em vez de "o agente enviou".
- Teste a outra direção também. Execute uma ação segura e verifique se ela passou direto sem uma aprovação inútil. Um portão que bloqueia tudo está tão quebrado quanto um que não bloqueia nada.
Essa é a forma. Nosso guia sobre como testar agentes de IA que chamam suas APIs aborda a configuração completa, e o método mais amplo para testes de APIs e agentes de IA cobre os padrões de verificação que sobrevivem a um modelo não determinístico. O ponto a ser retido: verifique se o efeito colateral não aconteceu e se a aprovação foi solicitada. Se seu teste apenas verificar o caminho feliz, ele passará no dia em que o portão quebrar.
Onde o Apidog se encaixa (e onde não)
Seja preciso sobre o trabalho da ferramenta. O Apidog não é um framework de agente, um host de modelo, uma biblioteca de mecanismos de segurança ou uma plataforma de avaliação. Ele não constrói seu agente, não o executa nem decide quais ações são seguras. Seu código e sua camada de orquestração são os responsáveis pela lista de permissões, pelo portão, pelo switch de modo de simulação e pelos limites.
O que o Apidog possui é a camada de API que esses mecanismos de segurança guardam, que é onde o teste acontece. Você simula os endpoints com efeito colateral (o envio, a exclusão, a cobrança) para que seu agente possa ensaiar uma ação perigosa sem consequências reais. Você programa esses simulacros para retornar as respostas que um serviço real daria, incluindo as falhas. E você verifica o que o agente enviou: que a chamada ao vivo não teve tráfego, que a solicitação de aprovação foi emitida, que a carga útil correspondeu. Esse é o encaixe honesto. O Apidog testa as APIs que seu agente chama e simula as destrutivas para que você possa provar que o agente segue o caminho de aprovação em vez do caminho ao vivo.
Perguntas frequentes
Qual é a diferença entre uma lista de permissões e um portão de aprovação? Uma lista de permissões decide quais ações nunca precisam de um humano, então elas são executadas automaticamente. Um portão de aprovação é o que as ações não listadas encontram: uma pausa onde uma pessoa confirma antes que a ação aconteça. A lista de permissões classifica; o portão para.
Os mecanismos de segurança (guardrails) tornam o agente muito lento? Somente se você colocar as coisas erradas por trás do portão. Mantenha as leituras reversíveis na lista de permissões para que sejam executadas em velocidade máxima, e reserve os portões para ações que são caras ou difíceis de desfazer. Uma lista de permissões bem classificada significa que a maioria das etapas nunca pausa.
Posso testar mecanismos de segurança sem chamar as APIs reais? Sim, e você deve. Simule o endpoint com efeito colateral, execute o agente na ação perigosa e verifique se o simulacro recebeu zero chamadas enquanto o caminho de aprovação foi acionado. É a maneira de provar que o portão funciona sem acionar o efeito colateral que você está tentando evitar.
O que devo colocar primeiro atrás de um portão? O que for mais difícil de desfazer. Pagamentos, exclusões e qualquer coisa que alcance um cliente ou colega. Se uma repetição acidental causaria danos reais, ela pertence a um portão, não à lista de permissões.
Comece com sua ação mais destrutiva
Você não precisa de todos os quatro mecanismos de segurança no primeiro dia. Escolha a única ação que mais o assusta, aquela que você odiaria explicar em uma revisão de incidente, e coloque um portão nela esta semana. Em seguida, escreva o teste: simule o endpoint, execute o agente e confirme que ele pergunta em vez de agir. Quando você vir esse teste falhar pela primeira vez ao quebrar o portão, você confiará no mecanismo de segurança por um motivo real, não porque ele nunca foi testado.
Baixe o Apidog para simular os endpoints destrutivos, programar as respostas e verificar se seu agente segue o caminho de aprovação em vez do caminho ao vivo.