Como Construí Barreiras de Segurança para Impedir que Meu Agente de IA Saísse do Controle
Um desenvolvedor relata um incidente crítico onde um agente de IA vazou dados de clientes e detalha o sistema de 'guardrails' que ele construiu para prevenir falhas futuras, cobrindo validação de entrada, saída, controle de custos e chamadas de ferramentas.
MundiX News·13 de junho de 2026·10 min de leitura·👁 6 views
No terceiro dia de operação, meu agente de IA vazou o e-mail de um cliente em uma conversa com outro. Esta não foi uma história hipotética de uma conferência; foi meu código em produção, fazendo algo que eu nunca havia testado. Eu havia montado um agente de suporte usando LangGraph e GPT-4o, capaz de pesquisar em uma base de conhecimento, buscar detalhes da conta e preparar respostas. No ambiente de staging, ele funcionava perfeitamente. Em produção, levou exatamente 72 horas para que ele extraísse informações de identificação pessoal (PII) de um usuário e as inserisse na conversa com outro. A razão era embaraçosamente simples: o modelo incluiu o contexto bruto do banco de dados diretamente na resposta, e nada em meu pipeline o verificou.
O conserto, em retrospecto, foi óbvio. Frameworks de agentes de IA oferecem orquestração, chamadas de ferramentas e memória. Eles não oferecem segurança. Isso é responsabilidade sua. LangChain, CrewAI, LangGraph, Agents SDK da OpenAI – escolha qualquer um. Nenhum deles vem com validação de entrada, filtragem de saída ou controle de gastos. Eles assumem que você adicionará isso por conta própria. A maioria das equipes nunca o faz. Por que isso é importante é explicado por uma simples aritmética: com 90% de precisão por etapa, um fluxo de trabalho de agente de 5 etapas tem sucesso em 59% dos casos. Um fluxo de trabalho de 10 etapas cai para 35%. Em 20 etapas, você está em 12%. Cada etapa desprotegida multiplica sua probabilidade de falha. As barreiras de segurança (guardrails) não corrigem a precisão; elas limitam o raio de dano quando a precisão falha. A diferença entre 'o agente deu uma resposta errada' e 'o agente deu uma resposta errada que continha o número de seguro social de alguém' é um único validador de saída. Nas duas semanas seguintes, construí uma pilha de guardrails. O código abaixo é o que eu finalmente cheguei.
Quatro Guardrails Essenciais para Qualquer Agente
Todo agente precisa de proteção em quatro pontos: Guardrails de Entrada (Input Guardrails): capturam injeções de prompt e limpam dados sensíveis antes que a LLM os veja. Guardrails de Saída (Output Guardrails): validam respostas antes que os usuários as vejam, bloqueando alucinações e vazamentos de contexto. Disjuntores de Custo (Cost Circuit Breakers): impedem que a conta da API dispare devido a loops ou conversas inesperadamente longas. Validadores de Chamada de Ferramenta (Tool Call Validators): confirmam que o agente está chamando apenas ferramentas permitidas com parâmetros que passam na validação de esquema. Todos os quatro cabem em menos de 200 linhas de Python. A sobrecarga de latência é de 10-50 ms por camada. A alternativa é descobrir sobre falhas com seus clientes.
Guardrails de Entrada: Capturando Prompts Maliciosos Antes da Execução
Seu validador de entrada opera antes mesmo que a LLM veja o prompt. Ele faz duas coisas: bloqueia tentativas de injeção e edita PII. O código Python fornecido implementa padrões regex para identificar e bloquear tentativas de injeção de prompt, como instruções para ignorar comandos anteriores ou redefinir o comportamento do sistema. Além disso, ele escaneia e substitui informações de identificação pessoal (PII), como números de seguro social (SSN), cartões de crédito e endereços de e-mail, por marcadores genéricos como [REDACTED_SSN]. Embora essa abordagem baseada em regex não seja infalível contra atacantes persistentes, ela captura a maioria das tentativas comuns, que representam cerca de 80% dos ataques reais, de acordo com a experiência do autor. Para ambientes de produção com dados sensíveis, recomenda-se complementar essa verificação com um classificador de modelo (como Lakera Guard ou um DistilBERT pré-treinado). A limpeza de PII é a funcionalidade que teria evitado o incidente do terceiro dia; se o guardrail de entrada tivesse removido o e-mail do contexto do banco de dados antes que ele entrasse na conversa, o vazamento não teria ocorrido.
Guardrails de Saída: Impedindo Alucinações Antes de Chegarem ao Usuário
A validação de saída é onde a maioria das equipes negligencia os guardrails. O modelo gera uma resposta, ela parece razoável, e é enviada. No entanto, 'parecer razoável' não é um padrão confiável. O código utiliza um modelo Pydantic para definir a estrutura esperada de uma resposta do agente, incluindo campos como answer, confidence e sources. O validador de saída verifica se a confiança está dentro de um limite aceitável (por exemplo, 0.7) e se a resposta não contém PII, além de garantir que fontes sejam fornecidas para as afirmações. Quando a validação falha, o agente é instruído a tentar novamente com contexto adicional, explicando o motivo da rejeição. Após duas tentativas de repetição com instruções mais específicas, se a validação ainda falhar, uma resposta de fallback predefinida é retornada e o incidente é registrado. Isso garante que respostas incorretas ou perigosas não cheguem ao usuário final.
Kill Switch: Disjuntor de Custos e Tokens
Este é um guardrail raramente discutido, mas que custou ao autor US$ 400. Um bug causou um loop de repetição no agente: a chamada de uma ferramenta falhava, o agente tentava novamente, a falha era ligeiramente diferente, e o agente repetia. Cada repetição consumia tokens para o raciocínio e a chamada da ferramenta. O agente ficou em loop por seis horas durante a noite antes de ser notado. A classe CostCircuitBreaker implementa limites para tokens por solicitação, tokens por sessão, chamadas de API por minuto e gastos diários em USD. Se qualquer um desses limites for excedido, a chamada da API é bloqueada e uma mensagem de serviço indisponível é retornada. O autor definiu um limite diário de US$ 50, preferindo interrupções de serviço a contas inesperadas. Essa medida é crucial para prevenir gastos excessivos causados por bugs ou uso indevido.
Validação de Chamada de Ferramentas: O Agente Não Deve Chamar o Que Você Não Aprovou
Quando um agente tem acesso a bancos de dados, sistemas de arquivos ou APIs externas, a validação das chamadas de ferramentas não é opcional. Sem ela, um agente comprometido ou confuso pode executar operações destrutivas. A classe ToolCallGuardrail implementa uma política de negação padrão (default deny). Se uma ferramenta não estiver na lista de permissões (allowlist), o agente não pode chamá-la. Se um parâmetro não estiver listado como permitido para essa ferramenta específica, a chamada é rejeitada. Isso impede tanto tentativas de jailbreak (onde o modelo tenta chamar execute_sql ou delete_record) quanto nomes de ferramentas alucinados, que ocorrem com mais frequência do que se imagina. Limites de frequência de chamadas são mantidos separadamente para cada ferramenta, pois diferentes ferramentas têm perfis de risco distintos. Pesquisas são baratas e podem ser chamadas 20 vezes, enquanto atualizações de conta devem ocorrer no máximo uma ou duas vezes por conversa.
Montando Tudo: A Pilha de Guardrails de Produção
Os quatro componentes de guardrails se integram em um pipeline de agente: Entrada do Usuário -> [Input Guardrail] -> [Cost Circuit Breaker] -> [LLM Reasoning] -> [Tool Call Guardrail] -> [Tool Execution] -> [LLM Response Generation] -> [Output Guardrail] -> Resposta do Usuário. Cada guardrail registra suas decisões, criando um log estruturado com o motivo da falha, a entrada que a causou e o timestamp. Esses logs são analisados semanalmente para identificar padrões, como ataques automatizados ou problemas de qualidade de recuperação (retrieval). A sobrecarga total de latência para os quatro guardrails é inferior a 40 ms (excluindo classificadores de ML), tornando-a imperceptível para o usuário. Se o autor pudesse recomeçar, ele adicionaria os guardrails antes de escrever qualquer lógica do agente. A pilha descrita, cerca de 200 linhas de Python, levou duas semanas para ser implementada apenas porque foi integrada a um sistema existente e o autor estava paralelamente lidando com o incidente de PII. A previsão é que, em 12 meses, os principais frameworks de agentes incluirão guardrails como uma função de primeira classe. LangGraph já está avançando nessa direção com seu mecanismo de interrupção. Enquanto isso, você está por conta própria. Comece com os guardrails de entrada e o disjuntor de custos; esses dois teriam prevenido ambos os incidentes (vazamento de PII e a conta noturna de US$ 400). Adicione validação de saída quando o tráfego de produção aumentar para ajustar os limites de confiança. Adicione validação de chamada de ferramentas se o agente tiver acesso de escrita a qualquer coisa. Guardrails não tornarão seu agente mais inteligente, mas impedirão que momentos de estupidez se transformem em incidentes.
No terceiro dia de operação, meu agente de IA vazou o e-mail de um cliente em uma conversa com outro. Esta não foi uma história hipotética de uma conferência; foi meu código em produção, fazendo algo que eu nunca havia testado. Eu havia montado um agente de suporte usando LangGraph e GPT-4o, capaz de pesquisar em uma base de conhecimento, buscar detalhes da conta e preparar respostas. No ambiente de staging, ele funcionava perfeitamente. Em produção, levou exatamente 72 horas para que ele extraísse informações de identificação pessoal (PII) de um usuário e as inserisse na conversa com outro. A razão era embaraçosamente simples: o modelo incluiu o contexto bruto do banco de dados diretamente na resposta, e nada em meu pipeline o verificou.
O conserto, em retrospecto, foi óbvio. Frameworks de agentes de IA oferecem orquestração, chamadas de ferramentas e memória. Eles não oferecem segurança. Isso é responsabilidade sua. LangChain, CrewAI, LangGraph, Agents SDK da OpenAI – escolha qualquer um. Nenhum deles vem com validação de entrada, filtragem de saída ou controle de gastos. Eles assumem que você adicionará isso por conta própria. A maioria das equipes nunca o faz. Por que isso é importante é explicado por uma simples aritmética: com 90% de precisão por etapa, um fluxo de trabalho de agente de 5 etapas tem sucesso em 59% dos casos. Um fluxo de trabalho de 10 etapas cai para 35%. Em 20 etapas, você está em 12%. Cada etapa desprotegida multiplica sua probabilidade de falha. As barreiras de segurança (guardrails) não corrigem a precisão; elas limitam o raio de dano quando a precisão falha. A diferença entre 'o agente deu uma resposta errada' e 'o agente deu uma resposta errada que continha o número de seguro social de alguém' é um único validador de saída. Nas duas semanas seguintes, construí uma pilha de guardrails. O código abaixo é o que eu finalmente cheguei.
Quatro Guardrails Essenciais para Qualquer Agente
Todo agente precisa de proteção em quatro pontos: Guardrails de Entrada (Input Guardrails): capturam injeções de prompt e limpam dados sensíveis antes que a LLM os veja. Guardrails de Saída (Output Guardrails): validam respostas antes que os usuários as vejam, bloqueando alucinações e vazamentos de contexto. Disjuntores de Custo (Cost Circuit Breakers): impedem que a conta da API dispare devido a loops ou conversas inesperadamente longas. Validadores de Chamada de Ferramenta (Tool Call Validators): confirmam que o agente está chamando apenas ferramentas permitidas com parâmetros que passam na validação de esquema. Todos os quatro cabem em menos de 200 linhas de Python. A sobrecarga de latência é de 10-50 ms por camada. A alternativa é descobrir sobre falhas com seus clientes.
Guardrails de Entrada: Capturando Prompts Maliciosos Antes da Execução
Seu validador de entrada opera antes mesmo que a LLM veja o prompt. Ele faz duas coisas: bloqueia tentativas de injeção e edita PII. O código Python fornecido implementa padrões regex para identificar e bloquear tentativas de injeção de prompt, como instruções para ignorar comandos anteriores ou redefinir o comportamento do sistema. Além disso, ele escaneia e substitui informações de identificação pessoal (PII), como números de seguro social (SSN), cartões de crédito e endereços de e-mail, por marcadores genéricos como [REDACTED_SSN]. Embora essa abordagem baseada em regex não seja infalível contra atacantes persistentes, ela captura a maioria das tentativas comuns, que representam cerca de 80% dos ataques reais, de acordo com a experiência do autor. Para ambientes de produção com dados sensíveis, recomenda-se complementar essa verificação com um classificador de modelo (como Lakera Guard ou um DistilBERT pré-treinado). A limpeza de PII é a funcionalidade que teria evitado o incidente do terceiro dia; se o guardrail de entrada tivesse removido o e-mail do contexto do banco de dados antes que ele entrasse na conversa, o vazamento não teria ocorrido.
Guardrails de Saída: Impedindo Alucinações Antes de Chegarem ao Usuário
A validação de saída é onde a maioria das equipes negligencia os guardrails. O modelo gera uma resposta, ela parece razoável, e é enviada. No entanto, 'parecer razoável' não é um padrão confiável. O código utiliza um modelo Pydantic para definir a estrutura esperada de uma resposta do agente, incluindo campos como answer, confidence e sources. O validador de saída verifica se a confiança está dentro de um limite aceitável (por exemplo, 0.7) e se a resposta não contém PII, além de garantir que fontes sejam fornecidas para as afirmações. Quando a validação falha, o agente é instruído a tentar novamente com contexto adicional, explicando o motivo da rejeição. Após duas tentativas de repetição com instruções mais específicas, se a validação ainda falhar, uma resposta de fallback predefinida é retornada e o incidente é registrado. Isso garante que respostas incorretas ou perigosas não cheguem ao usuário final.
Kill Switch: Disjuntor de Custos e Tokens
Este é um guardrail raramente discutido, mas que custou ao autor US$ 400. Um bug causou um loop de repetição no agente: a chamada de uma ferramenta falhava, o agente tentava novamente, a falha era ligeiramente diferente, e o agente repetia. Cada repetição consumia tokens para o raciocínio e a chamada da ferramenta. O agente ficou em loop por seis horas durante a noite antes de ser notado. A classe CostCircuitBreaker implementa limites para tokens por solicitação, tokens por sessão, chamadas de API por minuto e gastos diários em USD. Se qualquer um desses limites for excedido, a chamada da API é bloqueada e uma mensagem de serviço indisponível é retornada. O autor definiu um limite diário de US$ 50, preferindo interrupções de serviço a contas inesperadas. Essa medida é crucial para prevenir gastos excessivos causados por bugs ou uso indevido.
Validação de Chamada de Ferramentas: O Agente Não Deve Chamar o Que Você Não Aprovou
Quando um agente tem acesso a bancos de dados, sistemas de arquivos ou APIs externas, a validação das chamadas de ferramentas não é opcional. Sem ela, um agente comprometido ou confuso pode executar operações destrutivas. A classe ToolCallGuardrail implementa uma política de negação padrão (default deny). Se uma ferramenta não estiver na lista de permissões (allowlist), o agente não pode chamá-la. Se um parâmetro não estiver listado como permitido para essa ferramenta específica, a chamada é rejeitada. Isso impede tanto tentativas de jailbreak (onde o modelo tenta chamar execute_sql ou delete_record) quanto nomes de ferramentas alucinados, que ocorrem com mais frequência do que se imagina. Limites de frequência de chamadas são mantidos separadamente para cada ferramenta, pois diferentes ferramentas têm perfis de risco distintos. Pesquisas são baratas e podem ser chamadas 20 vezes, enquanto atualizações de conta devem ocorrer no máximo uma ou duas vezes por conversa.
Montando Tudo: A Pilha de Guardrails de Produção
Os quatro componentes de guardrails se integram em um pipeline de agente: Entrada do Usuário -> [Input Guardrail] -> [Cost Circuit Breaker] -> [LLM Reasoning] -> [Tool Call Guardrail] -> [Tool Execution] -> [LLM Response Generation] -> [Output Guardrail] -> Resposta do Usuário. Cada guardrail registra suas decisões, criando um log estruturado com o motivo da falha, a entrada que a causou e o timestamp. Esses logs são analisados semanalmente para identificar padrões, como ataques automatizados ou problemas de qualidade de recuperação (retrieval). A sobrecarga total de latência para os quatro guardrails é inferior a 40 ms (excluindo classificadores de ML), tornando-a imperceptível para o usuário. Se o autor pudesse recomeçar, ele adicionaria os guardrails antes de escrever qualquer lógica do agente. A pilha descrita, cerca de 200 linhas de Python, levou duas semanas para ser implementada apenas porque foi integrada a um sistema existente e o autor estava paralelamente lidando com o incidente de PII. A previsão é que, em 12 meses, os principais frameworks de agentes incluirão guardrails como uma função de primeira classe. LangGraph já está avançando nessa direção com seu mecanismo de interrupção. Enquanto isso, você está por conta própria. Comece com os guardrails de entrada e o disjuntor de custos; esses dois teriam prevenido ambos os incidentes (vazamento de PII e a conta noturna de US$ 400). Adicione validação de saída quando o tráfego de produção aumentar para ajustar os limites de confiança. Adicione validação de chamada de ferramentas se o agente tiver acesso de escrita a qualquer coisa. Guardrails não tornarão seu agente mais inteligente, mas impedirão que momentos de estupidez se transformem em incidentes.
