Seu agente funcionou na demonstração. Ele leu o ticket, chamou três APIs e publicou um resumo limpo. Então você o colocou em produção. Uma semana depois, ele enviou um e-mail para o mesmo cliente duas vezes, esgotou o orçamento de tokens de um dia em um loop de tentativas e entregou ao seu frontend uma carga útil que ele não conseguiu analisar.
Essa lacuna entre um protótipo funcional e um agente confiável é onde a maioria das equipes fica presa. O modelo raramente é o culpado. O problema reside na parte que é tratada como "encanamento": as chamadas de API que o agente faz a caminho de uma resposta. Um agente é um loop de chamadas de ferramenta, e cada chamada de ferramenta é uma requisição HTTP que pode falhar, ser limitada, expirar ou retornar algo que você não esperava. Ignore o teste dessas chamadas da mesma forma que você testa qualquer API de produção, e seu agente estará a uma resposta ruim de um incidente.
Aqui está a parte reconfortante: a confiabilidade do agente é testável. Você não precisa confiar que o modelo se comportará. Você exercita os caminhos de falha propositalmente, antes que seus usuários os encontrem para você. Este guia classifica as falhas do agente em cinco modos e mostra como identificar cada um. O trabalho acontece no limite da API, então você precisa de uma plataforma que possa apontar para as dependências do agente para projetar o contrato, simular as falhas e verificar o que retorna. O Apidog cumpre essa função e é usado nos exemplos abaixo.
Agentes falham no limite da API, não no prompt
Quando um agente se comporta mal em produção, o instinto é editar o prompt. Às vezes isso ajuda. Mais frequentemente, a falha não tem nada a ver com a redação. O agente solicitou algo a uma API real, e a resposta foi lenta, malformada, com limite de taxa excedido ou de um formato diferente do que o agente esperava. O modelo então raciocinou sobre uma entrada ruim e fez algo confiante e errado.
Veja o que um único passo do agente envolve. O modelo escolhe uma ferramenta. Seu código transforma essa escolha em uma requisição HTTP. Um serviço externo responde. Seu código alimenta o resultado de volta ao modelo. Quatro transferências, e três delas são integração de API comum, não aprendizado de máquina. Essa é uma boa notícia, porque a integração de API é um problema de teste resolvido. Você já sabe como simular um endpoint lento ou afirmar sobre um esquema JSON. Os agentes aumentam as apostas, porque o modelo age sobre o que quer que receba, em vez de lançar uma exceção limpa.
Então, a questão da confiabilidade não é "o modelo é inteligente o suficiente?". É "eu testei todas as maneiras pelas quais as chamadas de API do agente podem dar errado?". Cinco modos cobrem a maior parte.
Modo de falha 1: chamadas de ferramenta que se desviam do contrato
A falha mais comum do agente é uma chamada de ferramenta que não corresponde à API que está sendo chamada. O modelo inventa um parâmetro, omite um campo obrigatório, envia uma string onde o esquema espera um número inteiro, ou chama o endpoint correto com argumentos que não fazem sentido. Digamos que um agente de reservas chame POST /reservations com guests: "two" em vez de guests: 2. A API retorna um 400, ou pior, um 200 com um erro oculto no corpo, e o agente continua como se tivesse tido sucesso.
Você detecta isso testando a chamada da ferramenta como um contrato. Defina o esquema para cada ferramenta que o agente pode invocar e, em seguida, afirme que a requisição de saída corresponde: campos obrigatórios presentes, tipos corretos, enums válidos. Quando o agente produz uma chamada que quebra o contrato, você quer que isso falhe ruidosamente em um teste, não silenciosamente em produção. Nosso guia sobre como testar as chamadas de ferramenta de um agente de IA aprofunda este tema, e o método mais amplo para testar agentes que chamam suas APIs cobre a configuração de ponta a ponta.
A atitude prática: capture os esquemas das ferramentas que seu agente usa, carregue-os no Apidog e execute as chamadas de ferramenta reais do agente contra essas definições. As incompatibilidades aparecem como falhas de validação nomeando o campo exato que quebrou.
Modo de falha 2: erros upstream e limites de taxa
Cada chamada externa que o agente faz pode retornar um 429, um 500, ou nada antes de um timeout. Um agente bem construído lida com isso com retentativas e backoff. Um agente frágil desiste no primeiro erro ou, mais perigosamente, tenta novamente com tanta força que aciona mais limitação e entra em um loop que esgota seu orçamento. A pergunta mais frequente no fórum de discussão do SDK da Anthropic é literalmente sobre padrões para recuperação de erros de agente, o que demonstra o quão comum essa dor é.
Você não pode testar a recuperação contra uma API saudável, porque uma API saudável nunca retorna os erros que você precisa lidar. É aqui que o mocking prova seu valor. Crie um mock da dependência do agente e programe uma sequência: um 429 com um cabeçalho Retry-After, depois um 500, depois um sucesso. Agora observe o que seu agente faz. Ele recua com jitter? Ele respeita o cabeçalho? Ele desiste graciosamente após um número razoável de tentativas, ou abre um disjuntor para parar de sobrecarregar um serviço que está claramente inativo? E se uma ação retentada não for idempotente, uma repetição cobra ou envia em dobro? Uma chave de idempotência é o que torna uma retentativa segura de repetir.
Os limites de taxa merecem seu próprio ensaio. Se você não viu como seu agente se comporta quando um provedor o limita, leia nosso guia sobre o que significa uma resposta de limite de taxa excedido e simule-o. O guia dedicado sobre recuperação de erros de agente de IA cobre os padrões de retentativa, timeout, backoff e disjuntor na íntegra.
Modo de falha 3: saída não determinística
Defina a temperatura para zero e você ainda não obterá uma saída idêntica byte a byte em várias execuções. Os desenvolvedores redescobrem isso constantemente; há um longo tópico no vLLM sobre sementes e temperatura não serem suficientes para a reprodutibilidade. Hardware, batching e mudanças no lado do provedor introduzem variações. Se seus testes afirmarem sobre strings exatas, eles se tornam instáveis, e testes instáveis são ignorados, o que é pior do que não ter testes. Nossa análise sobre o que causa testes instáveis se aplica diretamente aqui.
A solução é afirmar sobre estrutura e significado, não sobre texto exato. Verifique se a resposta valida contra um esquema JSON. Verifique se a chamada da ferramenta tem o formato e o destino corretos. Verifique se uma resposta numérica se encaixa em um intervalo sensato. Verifique se as chaves obrigatórias existem e se os campos proibidos estão ausentes. Um teste que diz “a resposta contém um total entre 0 e o valor do carrinho” sobrevive à variação natural do modelo, ao mesmo tempo em que ainda detecta uma regressão real. O guia sobre como testar agentes de IA não determinísticos apresenta o conjunto completo de estratégias, e o artigo sobre como a memória do agente funciona mostra por que o estado torna isso mais difícil.
Modo de falha 4: custo descontrolado
Agentes entram em loop, e loops custam dinheiro. Um único agente preso que tenta novamente uma chamada com falha algumas milhares de vezes pode transformar uma pequena conta em uma grande da noite para o dia. Um relatório de campo nas discussões do SDK descreveu a redução do custo de um agente de 500 dólares por mês para 80 sem perder qualidade, o que mostra o quão rápido o custo aumenta e quanta folga geralmente se esconde no design.
O custo é um problema de confiabilidade, não apenas financeiro, porque os bugs que desperdiçam dinheiro (loops, chamadas redundantes, contexto superdimensionado) também tornam o agente lento e imprevisível. Rastreie os tokens por execução, limite o orçamento por tarefa e armazene em cache o que puder. Para o lado da linha de comando, nosso guia sobre como reduzir os custos de tokens do agente tem alavancas concretas. Ao testar os caminhos de recuperação contra um mock, observe também a contagem de chamadas. Um agente que tem sucesso, mas faz quarenta chamadas para chegar lá, é um incidente de custo prestes a acontecer.
Modo de falha 5: falta de guardrails
As falhas que mais doem são aquelas em que o agente faz exatamente o que lhe foi dito e o resultado ainda é ruim. Ele envia o e-mail, exclui o registro ou faz o pedido, porque nada se interpôs entre a decisão do modelo e a ação ao vivo. Os fóruns do SDK têm um tópico memorável construído em torno de um agente que disparou um e-mail às três da manhã para o chefe de alguém. Engraçado uma vez, caro duas vezes.
Guardrails são o cinto de segurança. Coloque uma lista de permissões nas ações que um agente pode realizar sem aprovação. Proteja chamadas destrutivas ou irreversíveis por trás de uma confirmação humana. Dê ao agente um modo de execução simulada que descreve o que ele faria sem fazê-lo. Em seguida, teste se o guardrail se mantém: simule o endpoint com efeito colateral, execute o agente e afirme que ele atinge o caminho de confirmação em vez da ação ao vivo. Orientações de segurança como o OWASP Top 10 para aplicações de LLM são uma lista de verificação sólida para o que proteger. O guia sobre guardrails de agentes de IA cobre portões de aprovação e controle de raio de explosão em profundidade.
Como estruturar um teste de agente
Os cinco modos compartilham uma forma de teste, e você pode reutilizá-la:
- Capture os esquemas das ferramentas que seu agente pode chamar, para que você tenha um contrato para afirmar.
- Simule cada dependência para que você controle o tempo, os códigos de status e os corpos, e assim evite efeitos colaterais reais.
- Conduza o agente pelo cenário, incluindo os caminhos infelizes que uma API real não produzirá sob demanda.
- Afirme sobre o que o agente enviou e como ele reagiu: formato da requisição, comportamento de recuperação, contagem de chamadas e se os guardrails foram acionados.
Execute esse loop para uma ferramenta, depois adicione a próxima. A configuração se paga na primeira vez que detecta uma chamada de ferramenta quebrada antes que um usuário o faça.
A lista de verificação de confiabilidade do agente
Antes que um agente vá para produção, siga esta lista:
- Cada chamada de ferramenta é validada contra um esquema, e violações de contrato falham em um teste.
- Respostas 429, 500 e timeout de upstream são simuladas, e o agente se recupera com backoff.
- Ações repetidas são idempotentes, para que uma repetição não possa cobrar ou enviar em dobro.
- Os testes afirmam sobre estrutura e significado, não sobre strings exatas, para que a variação normal não cause instabilidade.
- O uso de tokens por execução é medido, e um limite de orçamento interrompe loops descontrolados.
- Ações destrutivas estão por trás de uma lista de permissões ou de um portão de aprovação humano.
- O caminho do guardrail é testado com um mock, não presumido.
Marque todos os sete e você terá testado as maneiras pelas quais os agentes falham em produção.
Onde o Apidog se encaixa (e onde não se encaixa)
Seja claro sobre o trabalho da ferramenta. O Apidog não é uma estrutura de agente, um host de modelo ou um harness de avaliação. Ele não constrói nem executa seu agente. O que ele faz é gerenciar a camada de API da qual seu agente depende, que é exatamente onde essas falhas residem.
Na prática, isso significa três coisas. Você projeta e armazena os contratos para as ferramentas que seu agente chama, para que possa validar as solicitações de saída contra eles. Você simula essas dependências e programa as respostas de falha (429, 500, timeout, corpo malformado) que uma API real não produzirá sob demanda, para que você possa ensaiar a recuperação. E você escreve afirmações nas respostas (esquema, formato, intervalos, chaves necessárias) que sobrevivem à saída não determinística. Esse é o ajuste honesto: o Apidog testa as APIs que seu agente chama, simula as falhas que você precisa lidar e verifica o que retorna. Nossa visão geral sobre testes de IA agêntica situa isso no panorama mais amplo de QA.
Perguntas frequentes
A confiabilidade do agente é um problema do modelo ou um problema de engenharia? Principalmente de engenharia. A escolha do modelo importa, mas as falhas que causam incidentes (chamadas de ferramenta ruins, limites de taxa não tratados, guardrails ausentes) são problemas de integração e teste que você pode resolver sem alterar o modelo.
Posso testar um agente sem atingir as APIs reais que ele chama? Sim, e você deveria. Simule as dependências para que você possa forçar respostas de erro, controlar o tempo e evitar efeitos colaterais. Essa é a única maneira confiável de testar os caminhos de recuperação e guardrail.
Como escrevo testes quando a saída muda a cada execução? Afirme sobre a estrutura e o significado em vez de texto exato. Valide a resposta em relação a um esquema, verifique o formato da chamada da ferramenta e use intervalos para números. O guia testando agentes de IA não determinísticos aborda isso em detalhes.
O que devo testar primeiro? Guardrails em ações destrutivas, depois a recuperação de erros. Esses dois protegem você das falhas mais caras: um agente realizando uma ação prejudicial, ou um agente entrando em loop e esgotando seu orçamento.
Comece com um modo de falha
Você não precisa testar todos os cinco modos de uma vez. Escolha o que mais te assusta, geralmente guardrails ou recuperação de erros, e ensaie-o contra um mock esta semana. Programe a falha, execute o agente e observe o que ele faz. Na primeira vez que você vir seu agente lidar com um 429 simulado com um backoff limpo em vez de um loop que esgota o orçamento, você confiará mais nele, e por uma razão melhor do que uma demonstração verde.
Baixe o Apidog para projetar os contratos, simular as falhas e afirmar sobre as respostas das quais seu agente depende.