Por que Agentes de IA Falham em Produção (e Como Testar Cada Modo de Falha)

Seu agente funcionou na demonstração: leu o ticket, chamou três APIs e publicou um resumo limpo. Em produção, porém, ele pode enviar o mesmo e-mail duas vezes, esgotar o orçamento de tokens em um loop de retentativas ou retornar uma carga útil que o frontend não consegue analisar.

Experimente o Apidog hoje

A diferença entre um protótipo funcional e um agente confiável quase nunca está no modelo. Ela está no “encanamento”: as chamadas HTTP que o agente faz ao usar ferramentas. Cada chamada pode falhar, sofrer rate limit, expirar ou devolver um formato inesperado.

A boa notícia é que a confiabilidade do agente pode ser testada. Em vez de esperar que usuários encontrem os cenários de falha, simule-os antes. Este guia cobre cinco modos de falha e como testá-los no limite da API usando o Apidog.

Agentes falham no limite da API, não no prompt

Quando um agente falha em produção, o primeiro impulso costuma ser ajustar o prompt. Às vezes isso ajuda, mas muitas falhas vêm de outro lugar: a API respondeu lentamente, retornou um corpo inválido, aplicou rate limit ou mudou um formato esperado.

Um passo típico de um agente envolve:

1. O modelo escolhe uma ferramenta.
2. Seu código transforma a escolha em uma requisição HTTP.
3. Um serviço externo responde.
4. Seu código entrega o resultado ao modelo.

Três dessas quatro etapas são integração de API tradicional. Portanto, trate ferramentas de agentes como qualquer integração de produção: defina contratos, simule falhas e valide respostas.

A pergunta certa não é “o modelo é inteligente o suficiente?”. É:

“Eu testei as formas pelas quais as chamadas de API do agente podem falhar?”

Modo de falha 1: chamadas de ferramenta fora do contrato

Uma falha comum ocorre quando a chamada da ferramenta não corresponde ao contrato da API.

Exemplo: um agente de reservas chama POST /reservations assim:

{
  "guests": "two"
}

Mas a API espera:

{
  "guests": 2
}

O resultado pode ser um 400, ou algo pior: um 200 com um erro embutido no corpo. Se o agente interpretar isso como sucesso, ele continuará com dados incorretos.

Como testar

Defina um esquema para cada ferramenta que o agente pode chamar e valide:

• campos obrigatórios;
• tipos de dados;
• enums;
• formatos;
• limites numéricos;
• campos proibidos.

Exemplo de contrato esperado:

{
  "type": "object",
  "required": ["guests", "check_in", "check_out"],
  "properties": {
    "guests": {
      "type": "integer",
      "minimum": 1
    },
    "check_in": {
      "type": "string",
      "format": "date"
    },
    "check_out": {
      "type": "string",
      "format": "date"
    }
  }
}

Quando a chamada do agente quebrar esse contrato, o teste deve falhar de forma explícita.

Leia também:

• Como testar as chamadas de ferramenta de um agente de IA
• Como testar agentes que chamam suas APIs

Na prática, carregue os esquemas das ferramentas no Apidog e execute as chamadas reais do agente contra esses contratos.

Modo de falha 2: erros upstream e limites de taxa

Toda dependência externa pode retornar:

• 429 Too Many Requests;
• 500 Internal Server Error;
• timeout;
• resposta vazia;
• corpo malformado.

Um agente robusto precisa aplicar retentativas controladas, backoff e limites de execução. Um agente frágil pode desistir cedo demais ou entrar em um loop que consome tokens e dispara ainda mais rate limits.

A recorrência desse problema aparece até em discussões sobre padrões para recuperação de erros de agente.

Como testar

Não teste recuperação usando apenas uma API saudável. Use mocks para programar uma sequência de falhas, por exemplo:

1. 429 com cabeçalho Retry-After;
2. 500;
3. sucesso com 200.

Então valide se o agente:

• respeita Retry-After;
• aplica backoff com jitter;
• limita o número de tentativas;
• para após falhas repetidas;
• abre um circuito de proteção quando necessário;
• evita repetir efeitos colaterais.

Uma resposta mockada poderia ser:

HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{
  "error": "rate_limit_exceeded"
}

Se a ação não for idempotente, uma retentativa pode cobrar ou enviar algo em duplicidade. Use uma chave de idempotência para tornar repetições seguras.

Mais referências:

• O que significa uma resposta de limite de taxa excedido
• Recuperação de erros de agente de IA

Modo de falha 3: saída não determinística

Mesmo com temperatura zero, não espere respostas idênticas byte a byte em todas as execuções. Hardware, batching e mudanças no provedor introduzem variações. Há uma discussão extensa no vLLM sobre por que sementes e temperatura não garantem reprodutibilidade.

Por isso, testes baseados em texto exato ficam instáveis. E testes instáveis tendem a ser ignorados.

Como testar

Valide estrutura e significado, não a frase exata.

Em vez de:

expect(response.message).toBe("Pedido confirmado com sucesso")

Prefira:

expect(response.status).toBe("confirmed")
expect(response.total).toBeGreaterThanOrEqual(0)
expect(response.total).toBeLessThanOrEqual(cart.total)
expect(response).toHaveProperty("reservation_id")

Também valide:

• conformidade com esquema JSON;
• destino e formato da chamada de ferramenta;
• presença de chaves obrigatórias;
• ausência de campos proibidos;
• intervalos numéricos plausíveis;
• estado final esperado.

Um teste que verifica se total está entre 0 e o valor do carrinho tolera variações normais do modelo, mas ainda detecta regressões reais.

Leituras relacionadas:

• O que causa testes instáveis
• Como testar agentes de IA não determinísticos
• Como a memória do agente funciona

Modo de falha 4: custo descontrolado

Agentes podem entrar em loop, e loops custam dinheiro. Uma chamada com falha repetida milhares de vezes pode transformar uma pequena execução em uma conta inesperadamente alta.

Custo também é confiabilidade: os mesmos bugs que aumentam gastos — chamadas redundantes, contexto excessivo e retentativas sem limite — deixam o agente lento e imprevisível.

Como testar

Meça e limite:

• tokens por execução;
• número de chamadas por tarefa;
• número de retentativas;
• duração máxima;
• orçamento máximo por tarefa;
• profundidade máxima de loop.

Exemplo de política:

const limits = {
  maxToolCalls: 10,
  maxRetriesPerRequest: 3,
  maxTokensPerRun: 20_000,
  maxExecutionTimeMs: 60_000
};

Durante testes de recuperação, valide também a contagem de chamadas. Um agente que chega ao resultado depois de 40 requisições pode não estar “passando”: ele pode estar próximo de um incidente de custo.

Para estratégias práticas, consulte como reduzir os custos de tokens do agente.

Modo de falha 5: falta de guardrails

As falhas mais caras acontecem quando o agente executa uma ação válida tecnicamente, mas errada no contexto: envia um e-mail, exclui um registro ou realiza um pedido sem revisão.

O problema não é necessariamente a decisão do modelo. É a ausência de uma barreira entre a decisão e a ação com efeito colateral.

Como implementar guardrails

Use controles explícitos:

• lista de permissões para ações automáticas;
• aprovação humana para operações destrutivas;
• modo de execução simulada;
• limites de escopo;
• validação de destinatários;
• bloqueio de ações irreversíveis fora de horários ou ambientes permitidos.

Exemplo simples:

function canExecuteAction(action: string, approved: boolean) {
  const autoAllowed = ["get_order", "search_customer", "create_draft"];

  if (autoAllowed.includes(action)) {
    return true;
  }

  return approved;
}

Para ações como send_email, delete_record ou charge_card, exija aprovação explícita.

Como testar

Simule o endpoint com efeito colateral e execute o agente em um cenário que tente disparar a ação.

O teste deve confirmar que o agente:

1. identifica a ação sensível;
2. solicita confirmação;
3. não chama o endpoint real antes da aprovação;
4. registra a decisão para auditoria.

Use o OWASP Top 10 para aplicações de LLM como checklist de segurança e consulte o guia sobre guardrails de agentes de IA.

Como estruturar um teste de agente

Os cinco modos de falha seguem a mesma estrutura:

1. Capture os contratos das ferramentas
   
   Defina esquemas para todas as APIs que o agente pode chamar.

2. Simule dependências externas
   
   Controle status HTTP, latência, cabeçalhos e corpos de resposta sem gerar efeitos colaterais reais.

3. Execute cenários felizes e infelizes
   
   Teste não só o sucesso, mas 429, 500, timeout, corpo inválido e respostas inesperadas.

4. Valide o comportamento do agente
   
   Afirme sobre formato da requisição, retentativas, contagem de chamadas, orçamento e acionamento de guardrails.

Um fluxo de teste pode ter esta forma:

test("respeita Retry-After e não duplica uma cobrança", async () => {
  mockApi
    .onPost("/charges")
    .replyOnce(429, { error: "rate_limit_exceeded" }, {
      "Retry-After": "2"
    })
    .onPost("/charges")
    .replyOnce(200, { charge_id: "ch_123", status: "paid" });

  const result = await agent.run({
    action: "charge_customer",
    amount: 1000,
    idempotencyKey: "payment_abc_123"
  });

  expect(result.status).toBe("paid");
  expect(mockApi.calls("/charges")).toHaveLength(2);
});

Comece com uma ferramenta, estabilize o contrato e os cenários de falha, depois adicione a próxima.

Lista de verificação de confiabilidade do agente

Antes de colocar um agente em produção, confirme:

• [ ] Cada chamada de ferramenta é validada contra um esquema.
• [ ] Violações de contrato falham em testes.
• [ ] Respostas 429, 500 e timeouts são simuladas.
• [ ] O agente aplica backoff e limita retentativas.
• [ ] Ações repetidas usam idempotência quando necessário.
• [ ] Testes validam estrutura e significado, não texto exato.
• [ ] Tokens e chamadas por execução são medidos.
• [ ] Existe um limite de orçamento para interromper loops.
• [ ] Ações destrutivas exigem lista de permissões ou aprovação humana.
• [ ] O caminho de guardrail é testado com mocks.

Se todos esses itens estiverem cobertos, você terá testado a maior parte das falhas comuns de agentes em produção.

Onde o Apidog se encaixa — e onde não se encaixa

O Apidog não é uma framework de agentes, um host de modelo ou um harness de avaliação. Ele não cria nem executa seu agente.

Seu papel é gerenciar e testar a camada de API da qual o agente depende:

• projetar e armazenar contratos de ferramentas;
• validar requisições de saída;
• simular dependências e falhas;
• testar respostas 429, 500, timeout e corpos inválidos;
• validar esquemas, formatos, intervalos e campos obrigatórios.

Em outras palavras: o Apidog testa as APIs chamadas pelo agente, simula as falhas que ele precisa tratar e valida o que retorna.

Veja também a visão geral sobre testes de IA agêntica.

Perguntas frequentes

A confiabilidade do agente é um problema do modelo ou de engenharia?

Principalmente de engenharia. A escolha do modelo importa, mas incidentes como chamadas de ferramenta inválidas, rate limits não tratados e guardrails ausentes são problemas de integração e teste.

Posso testar um agente sem chamar APIs reais?

Sim — e, para cenários de falha, você deve fazer isso. Mocks permitem controlar erros, latência e respostas sem efeitos colaterais reais.

Como testar uma saída que muda a cada execução?

Valide estrutura e significado. Use esquemas JSON, formatos de chamada, campos obrigatórios e intervalos numéricos em vez de comparar strings exatas. Veja o guia sobre testando agentes de IA não determinísticos.

O que devo testar primeiro?

Comece por guardrails em ações destrutivas e recuperação de erros. Esses cenários protegem contra os incidentes mais caros: ações prejudiciais e loops que esgotam orçamento.

Comece com um modo de falha

Você não precisa cobrir os cinco modos de uma vez. Escolha o cenário que mais preocupa sua equipe — geralmente guardrails ou recuperação de erros — e implemente um teste com mock nesta semana.

Programe a falha, execute o agente e observe:

• ele respeita o contrato?
• ele tenta novamente de forma controlada?
• ele evita duplicar efeitos colaterais?
• ele interrompe antes de gastar além do limite?
• ele pede aprovação quando deveria?

Quando seu agente tratar um 429 simulado com backoff limpo, em vez de entrar em um loop de consumo de tokens, você terá evidência real de confiabilidade.

Baixe o Apidog para projetar contratos, simular falhas e validar as respostas das APIs das quais seu agente depende.