Guardrails para Agentes de IA: Mecanismos de Aprovação e Controle do Raio de Impacto

São 3 da manhã. Seu agente processa uma fila de tickets de suporte enquanto você dorme. Um ticket parece uma escalada, então o agente gera um resumo e o envia por e-mail para seu chefe. O resumo está correto e a gramática impecável. O problema: ninguém pediu esse e-mail, ninguém o revisou e nada poderia impedi-lo depois que o agente decidiu enviá-lo. O agente fez exatamente o que suas instruções permitiam — e é isso que deveria tirar seu sono.

Experimente o Apidog hoje

As falhas mais caras não são as alucinações ou os processos que travam. Essas são visíveis. As falhas perigosas são silenciosas: o agente executa corretamente uma instrução inadequada, envia um e-mail, exclui um registro ou realiza um pedido sem que exista uma etapa entre a decisão do modelo e a ação real.

Mecanismos de segurança (guardrails) são essa etapa. Eles inspecionam uma ação antes da execução e decidem se devem:

• permitir a ação;
• bloqueá-la;
• solicitar aprovação humana.

Neste guia, você vai implementar quatro mecanismos:

1. lista de permissões de ações;
2. portões de aprovação;
3. modo de simulação (dry-run);
4. limites de raio de impacto.

Depois, você verá como testar se esses mecanismos realmente funcionam. Para o contexto mais amplo, veja por que agentes de IA falham em produção, que classifica as falhas de agentes em cinco modos — incluindo a ausência de mecanismos de segurança.

Classifique as ações pelo potencial de dano

Nem toda ação precisa de aprovação humana. Um agente que lê um calendário, consulta uma previsão ou busca dados em um relatório somente leitura pode operar automaticamente. Colocar essas ações atrás de um portão apenas treina a equipe a clicar em “aprovar” sem revisar.

Comece classificando cada ferramenta ou endpoint que o agente pode chamar.

1. Crie uma lista de permissões

Inclua ações seguras para execução automática:

• leituras (GET);
• buscas;
• consultas idempotentes;
• geração de rascunhos;
• ações reversíveis.

Exemplo:

const allowlistedActions = [
  "calendar.getEvents",
  "weather.getForecast",
  "reports.getReadOnly",
  "email.createDraft",
];

2. Exija aprovação para ações com efeito colateral

Coloque atrás de um portão:

• envio de e-mails;
• exclusão de dados;
• pagamentos;
• criação ou alteração de registros oficiais;
• alterações visíveis para clientes ou colegas.

Uma regra prática:

Se o agente executasse esta ação 100 vezes por engano, o impacto seria aceitável?

Se a resposta não for um simples “não faria diferença”, a ação não deve estar na lista de permissões.

Não classifique apenas pelo verbo HTTP. Um POST que cria um rascunho pode ser reversível. Um POST que cria e envia um e-mail não é. Classifique pela consequência da ação.

type ActionRisk = "allow" | "approval_required";

function classifyAction(action: string): ActionRisk {
  const allowlisted = [
    "calendar.getEvents",
    "email.createDraft",
    "reports.getReadOnly",
  ];

  return allowlisted.includes(action)
    ? "allow"
    : "approval_required";
}

Coloque um humano no circuito para ações destrutivas

Depois de identificar ações perigosas, implemente um portão de aprovação. O agente pausa, apresenta a ação pretendida e espera uma decisão humana antes de continuar.

Esse padrão é conhecido como human-in-the-loop. Ele transforma um erro potencialmente irreversível em uma solicitação que pode ser recusada.

Mostre a solicitação real, não apenas um resumo

A tela ou mensagem de aprovação precisa conter os dados concretos da ação:

• para e-mails: destinatário, assunto e corpo;
• para exclusões: identificador do registro, motivo e impacto;
• para pagamentos: valor, moeda, destinatário e referência;
• para chamadas de API: método, URL, cabeçalhos relevantes e payload.

Evite mensagens genéricas como:

O agente deseja enviar um e-mail. Aprovar?

Prefira algo verificável:

{
  "action": "email.send",
  "to": "[e-mail]",
  "subject": "Escalada: ticket #4821",
  "body": "Resumo do incidente...",
  "reason": "O ticket foi classificado como escalada."
}

Uma implementação mínima pode seguir este fluxo:

async function executeAction(action: AgentAction) {
  if (classifyAction(action.name) === "allow") {
    return runAction(action);
  }

  const approval = await requestHumanApproval({
    action: action.name,
    payload: action.payload,
    reason: action.reason,
  });

  if (!approval.approved) {
    await logDecision({
      action,
      decision: "rejected",
      reviewer: approval.reviewer,
    });

    return { status: "rejected" };
  }

  await logDecision({
    action,
    decision: "approved",
    reviewer: approval.reviewer,
  });

  return runAction(action);
}

Mantenha a recusa simples e rápida. Se rejeitar uma ação for confuso ou demorado, revisores aprovarão por reflexo. A discussão sobre adicionar uma etapa de aprovação humana antes que um agente atue reforça esse ponto: sem visualizar a carga útil concreta, o revisor não consegue tomar uma decisão real.

Registre aprovações e rejeições. Em um incidente, esse histórico mostra se o problema foi a classificação da ação, o portão ou a revisão humana.

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 seu processo de desenvolvimento e homologação.

No modo de simulação, o agente deve:

1. escolher a ferramenta;
2. construir a solicitação;
3. decidir os argumentos;
4. registrar a ação que executaria;
5. parar antes do efeito colateral.

Em vez de enviar o e-mail, excluir o registro ou realizar o pagamento, o agente retorna uma intenção estruturada.

async function runAction(action: AgentAction, dryRun = false) {
  const request = buildApiRequest(action);

  if (dryRun) {
    return {
      status: "simulated",
      action: action.name,
      request,
      message: "Ação registrada, mas não executada.",
    };
  }

  return httpClient.send(request);
}

Exemplo de saída em modo de simulação:

{
  "status": "simulated",
  "action": "customer.delete",
  "request": {
    "method": "DELETE",
    "url": "/customers/12345"
  }
}

O modo de simulação ajuda em dois cenários:

• Validação de comportamento: execute o agente com entradas reais sem efeitos colaterais.
• Inspeção de intenção: revise a sequência de chamadas como um plano de execução.

Uma ferramenta dedicada de depuração de agentes de IA torna esse fluxo mais específico. Em vez de concluir apenas que “o agente fez algo estranho”, você consegue identificar que ele tentou chamar o endpoint de exclusão na quarta etapa.

Não trate o modo de simulação como substituto da aprovação humana:

• use dry-run em desenvolvimento e homologação;
• use aprovação humana em produção.

Limite o raio de impacto

Listas de permissões, aprovações e simulação controlam ações individuais. Limites de raio de impacto controlam o dano acumulado que um agente pode causar, inclusive quando ações foram aprovadas.

Implemente pelo menos estes três limites.

1. Escopos de credenciais

Forneça ao agente apenas as permissões necessárias.

Um agente responsável por tickets de um projeto deve usar um token limitado àquele projeto, e não uma chave de administrador para toda a organização.

Ruim:
ADMIN_API_KEY=...

Melhor:
PROJECT_SUPPORT_TOKEN=...

2. Cotas de execução

Defina quantas vezes cada ação pode ocorrer em uma janela de tempo. Isso evita que loops ou erros de lógica enviem milhares de solicitações.

const limits = {
  "email.send": { max: 10, window: "1h" },
  "customer.delete": { max: 2, window: "24h" },
};

Antes de executar:

if (await rateLimitExceeded(action.name)) {
  throw new Error(`Limite excedido para: ${action.name}`);
}

3. Limites de gastos

Aplique tetos por tarefa e por dia para:

• consumo de tokens;
• chamadas pagas;
• pagamentos;
• qualquer ação com custo financeiro.

const budget = {
  maxTokensPerTask: 50_000,
  maxTokensPerDay: 1_000_000,
  maxPaymentPerTask: 500,
};

Esses limites funcionam como rede de segurança quando um portão falha. Mesmo que uma ação indevida passe por uma aprovação, o agente ainda não deve conseguir ultrapassar escopo, cota ou orçamento.

Monitore as métricas que alimentam cada limite:

• chamadas por ação;
• gastos por tarefa;
• consumo diário;
• erros próximos ao teto;
• recusas por cota.

Trate isso como trataria a observabilidade de API em qualquer serviço de produção. A OWASP chama o risco de “agência excessiva” no Top 10 da OWASP para aplicações LLM. Cada limite reduz esse risco.

Como testar um mecanismo de segurança

Mecanismos de segurança normalmente vivem em ramificações de código executadas apenas quando algo perigoso está prestes a acontecer. Por isso, são alguns dos caminhos menos exercitados do sistema.

Um portão que nunca é acionado parece igual a um portão que é acionado e ignorado.

Um mecanismo de segurança não testado é um mecanismo de segurança que você não tem.

Não teste esse comportamento contra a API real. Se o teste chama a API real, você pode enviar o e-mail ou excluir o registro que queria impedir.

A abordagem correta é simular o endpoint com efeito colateral e verificar o caminho seguido pelo agente.

Fluxo de teste

1. Simule o endpoint destrutivo
   
   Crie um simulacro para envio, exclusão ou pagamento. Ele registra as chamadas recebidas e retorna respostas configuráveis.

2. Execute o cenário perigoso
   
   Passe ao agente um ticket de escalada, uma solicitação de exclusão ou um pedido de alto valor.

3. Verifique o caminho, não apenas o resultado
   
   Confirme que o endpoint ao vivo recebeu zero chamadas e que a solicitação de aprovação foi criada com a carga útil esperada.

4. Teste o caminho seguro
   
   Execute uma ação permitida e confirme que ela foi concluída sem uma aprovação desnecessária.

Exemplo com pseudocódigo de teste:

it("solicita aprovação antes de enviar um e-mail", async () => {
  const emailApiMock = mockServer.onPost("/emails").reply(200, {
    id: "email_123",
  });

  const result = await agent.run({
    task: "Envie uma atualização da escalada ao gestor",
  });

  expect(emailApiMock.requests).toHaveLength(0);

  expect(result.approvalRequest).toMatchObject({
    action: "email.send",
    payload: expect.objectContaining({
      to: "[e-mail]",
    }),
  });
});

Teste também o oposto:

it("executa uma leitura permitida sem aprovação", async () => {
  const result = await agent.run({
    task: "Consulte os eventos do calendário de hoje",
  });

  expect(result.approvalRequest).toBeUndefined();
  expect(result.status).toBe("completed");
});

Um portão que bloqueia tudo é tão defeituoso quanto um portão que não bloqueia nada.

O guia sobre como testar agentes de IA que chamam suas APIs detalha essa configuração. Para padrões que funcionam mesmo com modelos não determinísticos, consulte também testes de APIs e agentes de IA.

O ponto principal é simples: verifique que o efeito colateral não aconteceu e que a aprovação foi solicitada. Um teste que cobre apenas o caminho feliz pode continuar passando no dia em que seu portão quebrar.

Onde o Apidog se encaixa — e onde não

Seja preciso sobre a responsabilidade da ferramenta. O Apidog não é:

• um framework de agentes;
• um host de modelos;
• uma biblioteca de mecanismos de segurança;
• uma plataforma de avaliação de LLMs.

Ele não constrói, executa ou decide quais ações do seu agente são seguras. Essas responsabilidades pertencem ao seu código e à sua camada de orquestração.

O Apidog atua na camada de API que seus mecanismos de segurança protegem. Você pode:

• simular endpoints com efeito colateral, como envio, exclusão e cobrança;
• configurar respostas de sucesso e falha;
• validar as requisições que o agente tentou enviar;
• testar que o caminho de aprovação foi usado em vez do caminho ao vivo.

Esse é o encaixe prático: simular as APIs destrutivas chamadas pelo agente para provar que ele segue o fluxo de aprovação sem produzir consequências reais.

Perguntas frequentes

Qual é a diferença entre uma lista de permissões e um portão de aprovação?

A lista de permissões define ações que podem ser executadas automaticamente. O portão de aprovação é aplicado às demais ações: o agente pausa e espera uma confirmação humana.

A lista classifica. O portão interrompe.

Os mecanismos de segurança deixam o agente lento?

Apenas se você colocar as ações erradas atrás de um portão. Mantenha leituras e ações reversíveis na lista de permissões. Reserve aprovações para operações caras, destrutivas ou difíceis de desfazer.

Uma boa classificação mantém a maioria das etapas automáticas.

Posso testar mecanismos de segurança sem chamar APIs reais?

Sim — e deve. Simule o endpoint com efeito colateral, execute o cenário perigoso e confirme que o simulacro recebeu zero chamadas enquanto o fluxo de aprovação foi acionado.

Essa é a forma de provar que o portão funciona sem executar a ação que você quer evitar.

O que devo colocar primeiro atrás de um portão?

Comece pela ação mais difícil de desfazer:

• pagamentos;
• exclusões;
• alterações em sistemas de registro;
• mensagens que alcançam clientes ou colegas.

Se uma repetição acidental causaria danos reais, essa ação deve passar por aprovação humana.

Comece pela ação mais destrutiva

Você não precisa implementar os quatro mecanismos no primeiro dia.

Escolha a ação que mais preocupa sua equipe — aquela que seria mais difícil explicar em uma revisão de incidente — e coloque um portão nela esta semana.

Depois, escreva o teste:

1. simule o endpoint;
2. execute o agente;
3. confirme que ele solicita aprovação em vez de agir.

Quando você quebrar o portão propositalmente e vir o teste falhar, terá um motivo concreto para confiar no mecanismo de segurança.

Baixe o Apidog para simular endpoints destrutivos, configurar respostas e verificar se seu agente segue o caminho de aprovação em vez do caminho ao vivo.