Como Testar Agentes de IA que Chamam suas APIs Sem Perder Dados

Um agente de codificação de IA executou um script, viu-o ser bem-sucedido e, em seguida, viu uma tabela de banco de dados de produção desaparecer. O post-mortem no Hacker News viralizou com um título incisivo: “A IA não apagou seu banco de dados, você o fez.” O ponto foi bem colocado porque é verdade. O agente seguiu uma definição de ferramenta, a ferramenta atingiu um endpoint real, o endpoint não tinha salvaguardas, e um humano entregou as chaves a um processo que não pausa para perguntar se DELETE FROM users parece suspeito. Uma thread separada no r/ClaudeAI contou uma história semelhante de um ângulo diferente: um agente em um loop de cobrança consumiu centenas de dólares em tokens antes que alguém percebesse. Superfície diferente, mesma classe de falha. O problema não é que o modelo seja burro. O problema é que ninguém testou a API.

TL;DR

Agentes falham em produção quando suas ferramentas não possuem salvaguardas no lado da API: limites de taxa ausentes, nenhuma idempotência, exclusões "quentes", esquemas quebrados. Você corrige isso com quatro movimentos: teste de contrato das definições de ferramentas do agente em relação à sua especificação OpenAPI, execute um servidor de simulação para endpoints destrutivos, imponha limites de orçamento por agente e chaves de idempotência, e repita cenários de falha na CI. O Apidog oferece a importação OpenAPI, simulações e o executor de cenários para fazer tudo isso a partir de um único projeto.

Introdução

Há um ano, “testar o agente de IA” significava solicitar ao Claude ou GPT e avaliar a resposta. Isso não é mais o padrão. Os agentes de hoje chamam funções, essas funções atingem suas APIs, e suas APIs se comunicam com bancos de dados reais, processadores de pagamento e serviços de terceiros. Uma definição de ferramenta ruim ou um limite de taxa ausente não é um problema estilístico. É um incidente de produção com o seu nome.

A história viral do Hacker News deste mês capturou a mudança. O autor argumentou que a IA não apagou o banco de dados; o humano o fez, ao dar ao agente acesso de gravação sem colocar nenhum controle entre o modelo e os dados. A thread explodiu porque todo desenvolvedor que a leu pensou: “Eu quase enviei isso.” Algumas semanas antes, uma postagem no Reddit descreveu um loop de cobrança onde um agente tentou novamente uma chamada falha tantas vezes que a conta ultrapassou 800 euros antes que alguém percebesse. A mesma causa raiz: confiança depositada na camada errada.

Você pode consertar isso. A camada do modelo importa, mas a camada da API é onde você estanca o sangramento. Este artigo mostra como testar as integrações de API de agentes de IA de ponta a ponta. Abordaremos as quatro salvaguardas que toda configuração agente-API precisa, percorreremos um fluxo de trabalho passo a passo do Apidog para simular endpoints destrutivos e finalizaremos com técnicas avançadas como detecção de deriva de esquema e separação de chave dupla. Você sairá com padrões concretos que pode copiar para seu repositório hoje. Baixe o Apidog antes de começar para poder seguir as etapas do servidor de simulação.

Por que as falhas de agente parecem falhas de API

Leia post-mortems de agentes suficientes e um padrão aparece: o modelo não é o protagonista. A API é.

Pegue a injeção de prompt. Um usuário carrega um PDF com instruções ocultas, o agente o lê e a próxima chamada de ferramenta vai para seu endpoint /admin/users com delete_all=true. O modelo não escolheu isso; ele seguiu instruções nas quais não tinha motivos para desconfiar. A solução não é endurecer o prompt. A solução é construir uma API que não exponha delete_all=true a um token que veio de uma sessão de contexto de usuário. O OWASP chama isso de LLM01 em seu LLM Top 10, e a mitigação é autorização do lado da API, não engenharia de prompt.

Pegue esquemas de ferramentas defeituosos. Sua especificação OpenAPI diz que amount é um inteiro em centavos. A definição da ferramenta do agente diz que amount é um float em dólares. Três meses depois, alguém reembolsa uma cobrança de 19 centavos como 19 dólares e você descobre a incompatibilidade pela contabilidade. O modelo não estava errado; o modelo usou o esquema que você lhe deu. O esquema se desviou da API. Ninguém testou o contrato.

Pegue limites de taxa ausentes. Um agente em um loop de repetição martela seu endpoint de e-mail transacional mil vezes em dois minutos porque o planejador do agente continuava marcando a etapa como "ainda não bem-sucedida". Cada tentativa custa dinheiro. Cada tentativa enfileira um e-mail real. Quando você acorda, seu provedor sinalizou sua conta e seus clientes estão recebendo spam. O modelo não foi malicioso. O modelo estava trabalhando a partir de uma ferramenta que não tinha teto.

Pegue a idempotência ausente. O agente chama POST /payments para cobrar um cliente, obtém um tempo limite de rede, tenta novamente porque o planejador acha que a chamada falhou, e agora o cliente é cobrado duas vezes. A camada do agente não consegue dizer se a chamada original foi bem-sucedida; a API não lhe deu uma maneira de perguntar. As chaves de idempotência resolvem isso em cinco linhas de código do servidor, mas você precisa escrevê-las.

O fio condutor comum: em todos esses incidentes, o agente está fazendo exatamente o que suas ferramentas lhe dizem para fazer. As ferramentas são a API. Portanto, ao auditar onde a confiabilidade do agente falha, olhe primeiro para o contrato da API, em segundo para o harness do agente e quase nunca para o próprio modelo. Essa reestruturação importa porque informa onde investir. Você não precisa de um modelo mais inteligente. Você precisa de APIs testáveis com as salvaguardas ativadas.

As quatro salvaguardas que toda integração agente-API precisa

Quatro controles separam as configurações de agente que falham com segurança daquelas que falham de forma dispendiosa. Se você tiver tempo para adicionar apenas um neste trimestre, comece pelo topo. Se você conseguir fazer os quatro, terá coberto mais de 90% dos cenários de incidentes que verá em 2026.

1. Testes de contrato de esquema de ferramenta

Sua especificação OpenAPI é a fonte da verdade para sua API. Seu agente tem uma definição de ferramenta separada, muitas vezes escrita à mão ou copiada e colada da documentação. Esses dois artefatos divergem constantemente. Testes de contrato falham sua construção de CI no momento em que divergem.

Aqui está uma verificação mínima em Python que valida uma definição de ferramenta estilo Claude contra a especificação OpenAPI ao vivo:

import json
from jsonschema import Draft202012Validator

def validate_tool_against_openapi(tool_def: dict, openapi_spec: dict) -> list[str]:
    """Retorna uma lista de erros de incompatibilidade, lista vazia = passa."""
    errors = []
    op = openapi_spec["paths"][tool_def["path"]][tool_def["method"].lower()]
    api_schema = op["requestBody"]["content"]["application/json"]["schema"]
    tool_schema = tool_def["input_schema"]

    api_props = set(api_schema.get("properties", {}).keys())
    tool_props = set(tool_schema.get("properties", {}).keys())

    for missing in api_props - tool_props:
        if missing in api_schema.get("required", []):
            errors.append(f"Ferramenta com campo obrigatório ausente: {missing}")
    for extra in tool_props - api_props:
        errors.append(f"Ferramenta define campo não presente na API: {extra}")

    for prop, api_def in api_schema.get("properties", {}).items():
        if prop in tool_schema.get("properties", {}):
            tool_def_prop = tool_schema["properties"][prop]
            if api_def.get("type") != tool_def_prop.get("type"):
                errors.append(
                    f"Incompatibilidade de tipo em {prop}: API={api_def.get('type')} "
                    f"ferramenta={tool_def_prop.get('type')}"
                )
    return errors

Execute isso em cada PR que afete a especificação OpenAPI ou as definições das ferramentas. Falhe a compilação se a lista não estiver vazia. Essa única verificação teria detectado o erro de float versus centavos na seção anterior meses antes de qualquer reembolso ser processado.

2. Ambientes de sandbox e de simulação para endpoints destrutivos

Os agentes precisam de um lugar para praticar. Eles nunca devem praticar em produção. O padrão é direto: todo endpoint que altera o estado tem um equivalente de simulação que retorna a mesma forma de resposta sem fazer o trabalho. Seu ciclo de desenvolvimento de agente usa as simulações. Seus testes de estágio usam um banco de dados de sandbox. A produção permanece intocada até que um humano aprove a implantação.

O Apidog gera simulações diretamente da especificação OpenAPI, incluindo valores de campo realistas impulsionados por padrões Faker. Você aponta a URL base da API do seu agente para o servidor de simulação, executa cem iterações do seu prompt e observa como ele se comporta. Se o agente continuar tentando PUT para /users/{id}/delete porque entendeu mal a documentação, a simulação o intercepta. A tabela de usuários em produção nunca vê o erro. Veja desenvolvimento contract-first para o padrão mais amplo em que isso se encaixa.

3. Chaves de idempotência e exclusões "soft" para operações irreversíveis

Todo endpoint de escrita que seu agente pode chamar deve aceitar uma chave de idempotência. Toda exclusão deve ser uma exclusão "soft" por padrão, com um caminho de exclusão "hard" separado que os humanos autorizam.

O middleware se parece com isso no Express:

const idempotencyCache = new Map();

function idempotency(req, res, next) {
  const key = req.headers['idempotency-key'];
  if (!key) {
    return res.status(400).json({ error: 'Cabeçalho Idempotency-Key ausente' });
  }
  if (idempotencyCache.has(key)) {
    const cached = idempotencyCache.get(key);
    return res.status(cached.status).json(cached.body);
  }
  const originalJson = res.json.bind(res);
  res.json = function (body) {
    idempotencyCache.set(key, { status: res.statusCode, body });
    setTimeout(() => idempotencyCache.delete(key), 24 * 60 * 60 * 1000);
    return originalJson(body);
  };
  next();
}

app.post('/payments', idempotency, createPayment);

O agente gera um UUID por operação lógica e o reutiliza em novas tentativas. Sua API retorna a resposta em cache na segunda chamada em vez de cobrar duas vezes. Esse mesmo padrão protege contra envios duplos em APIs de mensagens, criação de linhas duplicadas em CRMs e a maioria dos outros cenários de "o agente tentou novamente e agora temos uma bagunça".

4. Limites de orçamento por agente

Cada agente recebe um orçamento. Orçamento de tokens, orçamento de solicitações, orçamento em dólares, orçamento de tempo. Quando o orçamento acaba, o agente para. Sem exceções. O incidente de 800 euros no Reddit aconteceu porque ninguém estabeleceu um teto para um loop descontrolado, e quando o humano verificou, o dano já estava feito.

Um middleware de orçamento que encapsula seu gateway de API pode rastrear:

• Tokens por sessão, limitado a 50.000
• Chamadas de API por minuto, limitado a 30
• Gasto cumulativo em centavos, limitado a 500
• Profundidade de chamada de ferramenta, limitado a 10 chamadas aninhadas

Quando qualquer limite é atingido, retorne HTTP 429 com um Retry-After estruturado e um cabeçalho X-Budget-Exceeded nomeando o limite. O planejador do agente pode então escalar para um humano ou desfazer a tarefa. Combine isso com o registro para que você possa ver quais agentes estão se aproximando dos limites e ajustar de acordo.

Esses quatro controles se somam. Testes de contrato pegam os erros óbvios de esquema. Mocks pegam os destrutivos. Idempotência pega as tempestades de retentativas. Orçamentos pegam os loops descontrolados. Juntos, eles transformam "o agente fez algo terrível" em "o agente atingiu um 429, registrou o problema e pediu ajuda." Esse é o padrão.

Teste chamadas de API de agente com Apidog

Agora a parte prática. Veja como configurar um fluxo de trabalho completo de teste de agente-API no Apidog. Você precisará da especificação OpenAPI para a API que seu agente chama, além de uma lista das definições de ferramentas do agente.

Etapa 1: Importar a especificação OpenAPI

Abra o Apidog, crie um novo projeto e importe seu arquivo OpenAPI 3.x. O Apidog analisa cada caminho, esquema e exemplo e cria os endpoints correspondentes no projeto. Se sua API ainda não estiver documentada em OpenAPI, este é o momento de fazê-lo; a confiabilidade do agente depende de ter uma única fonte de verdade que tanto seus humanos quanto seus agentes de IA leiam. O guia de fluxo de trabalho de API design-first explica isso se você estiver começando do zero.

Etapa 2: Definir respostas simuladas para endpoints destrutivos

Encontre cada endpoint que altera dados: POST, PUT, PATCH, DELETE. Para cada um, clique no endpoint e adicione uma resposta simulada. O Apidog pode gerar simulações realistas automaticamente a partir do seu esquema, mas você deve sobrescrever os valores dos campos para que pareçam dados de teste, não dados de produção. Use prefixos como mock_user_ e timestamps em 1970 para que qualquer vazamento seja óbvio nos logs.

Inicie o servidor de simulação. O Apidog fornece uma URL estável como https://mock.apidog.com/m1/your-project-id/. Aponte a URL base da API do seu agente para o servidor de simulação durante o desenvolvimento. Agora seu DELETE /users/{id} retorna um 200 com uma carga de usuário falsa, e seu banco de dados real está seguro.

Etapa 3: Escrever um cenário que simule a sequência de chamadas do agente

Os cenários do Apidog permitem encadear chamadas de API com asserções, da mesma forma que um conjunto de testes. Para um agente que prioriza tickets de suporte, o cenário pode ser:

1. POST /auth/token com credenciais de teste, capture o token de portador
2. GET /tickets?status=open com o token, capture o ID do primeiro ticket
3. POST /tickets/{id}/triage com uma categoria, afirme 200 e capture o campo 'atribuído a'
4. POST /notifications com uma mensagem de modelo, afirme que o corpo da mensagem corresponde a uma expressão regular

Você está efetivamente ensaiando o que o agente fará, no servidor de simulação, com asserções em cada passo. Se um desenvolvedor alterar o esquema do ticket e a expressão regular parar de corresponder, o cenário falha e você saberá antes que o agente chegue à produção. Veja testes de API para engenheiros de QA para o playbook mais amplo de testes de cenário.

Etapa 4: Executar a partir da CI

O Apidog fornece uma CLI que executa cenários a partir de um GitHub Action, pipeline GitLab ou qualquer executor de CI. O comando se parece com apidog run -t scenario-id --env test. Conecte-o ao seu pipeline de PR para que cada mudança na especificação OpenAPI ou nas definições de ferramentas do agente acione uma repetição completa do cenário.

Etapa 5: Comparar duas versões de modelo lado a lado

Ao avaliar se deve atualizar de um modelo para outro, você quer saber se as chamadas de ferramentas do novo modelo se comportam da mesma forma nos mesmos cenários. Execute o agente contra o mesmo cenário do Apidog com o modelo A, capture o rastro. Execute novamente com o modelo B, capture o rastro. Compare os corpos das requisições. Surpresas aparecem imediatamente: o modelo B passa um valor de priority diferente, ou omite um campo, ou usa um formato diferente para datas. Você detecta o desvio de comportamento antes que ele seja lançado. Este é um dos padrões abordados em integração de API GPT-5.5, onde a avaliação de novos comportamentos de modelo é uma necessidade recorrente.

Todo o fluxo de trabalho leva cerca de uma hora para ser configurado pela primeira vez e minutos por execução depois. A recompensa é que cada mudança em sua API ou em suas ferramentas de agente é exercitada contra a mesma linha de base de expectativas.

Técnicas avançadas e dicas profissionais

Alguns padrões que equipes experientes utilizam depois que os fundamentos estão estabelecidos.

Defina a temperatura para zero nos testes. Agentes não determinísticos produzem falhas de teste não determinísticas. Ao testar o comportamento da camada de ferramentas, defina a temperatura como 0 e semeie quaisquer fontes de aleatoriedade. Você está testando a camada de ferramentas, não a camada de criatividade.

Tire "snapshots" dos rastreamentos de chamadas de ferramenta. Cada execução de teste registra a sequência exata de chamadas de ferramenta feitas pelo agente, com argumentos. Compare com a linha de base anterior. Se o agente de repente começar a chamar /users duas vezes em vez de uma, você quer saber isso imediatamente, não três semanas depois, quando a conta chegar.

Nunca dê credenciais de produção a um agente. Agentes obtêm contas de serviço com escopo limitado. Credenciais de produção vivem em cofres, não em arquivos .env que um agente pode ler. Se um agente precisar chamar um endpoint de produção, ele passa por um proxy que assina solicitações com tokens de curta duração.

Separe as chaves de API de leitura e escrita. A maioria das tarefas de agente são majoritariamente de leitura. Emita chaves somente leitura para essas. Chaves de escrita são reservadas para tarefas que exigem aprovação humana. Essa única mudança reduz pela metade o raio de explosão de um agente comprometido.

Use HTTP 423 Locked para endpoints de aprovação humana. Quando um agente tenta chamar um endpoint que requer confirmação humana, retorne 423 com um campo confirmation_url. O planejador do agente vê o estado bloqueado, exibe a URL para um humano e espera. Isso é mais limpo do que um 403, porque 403 implica “você não pode fazer isso” enquanto 423 implica “você não pode fazer isso ainda.”

Feche em caso de desvio de esquema. Se a definição da ferramenta do agente não corresponder à sua especificação OpenAPI, a compilação falha. Não emita um aviso. Emita um erro. O custo de algumas falhas adicionais na compilação é muito menor do que um incidente de produção.

Erros comuns a evitar:

• Codificar a URL de simulação diretamente nos prompts do agente. Use variáveis de ambiente para que o mesmo prompt seja executado contra simulação, staging e produção.
• Ignorar a idempotência em endpoints "pequenos". Toda escrita precisa dela. O envio de e-mail não é exceção.
• Registrar corpos de requisição completos em produção. Informações pessoais vazam para sua pilha de observabilidade. Redija tokens, e-mails e identificadores antes que cheguem aos logs.
• Permitir que agentes tenham acesso direto ao banco de dados. Sempre passe pela API. A API é onde seus testes vivem.
• Confiar na pontuação de confiança do agente. A pontuação reflete a certeza do modelo sobre a resposta, não a segurança da API. Um agente 99% confiante ainda pode chamar o endpoint errado.

Se seu agente se comunica com serviços internos que não estão atrás de um único gateway de API, padrões de teste de microsserviços abordam como distribuir testes de cenário entre serviços.

Alternativas e ferramentas

Você tem opções. Aqui está uma comparação justa das quatro abordagens comuns.

O resumo honesto: se você vive no LangSmith, continue fazendo o que funciona no lado do agente e adicione uma camada de teste de API separada. Se você superou o preço do Postman ou seu modelo de simulação, o Apidog é um forte substituto. Se você está começando do zero, escolha a ferramenta que lida com OpenAPI, simulações e cenários em um único projeto, porque é aí que 80% do seu tempo de teste de agente-API será gasto.

Algumas equipes combinam esses. Elas mantêm o LangSmith para avaliações de nível de prompt e usam o Apidog para os testes de contrato do lado da API e repetições de cenário. Isso funciona bem; as ferramentas servem a camadas diferentes.

Casos de uso no mundo real

Agente atualiza linhas de banco de dados de produção. Uma equipe de sucesso do cliente construiu um agente que atualiza campos de conta a partir de tickets de suporte. Antes do lançamento, eles configuraram todos os endpoints de escrita para exigir uma chave de idempotência e executaram 200 repetições de cenário no Apidog contra um banco de dados sandbox. As repetições capturaram dois casos em que o agente tentou definir subscription_status para uma string que não estava no enum. Eles adicionaram validação de esquema e lançaram sem incidentes.

Agente chama uma API de pagamentos. Uma equipe fintech construindo um agente de reembolso automatizado estabeleceu limites rígidos: máximo de 5 reembolsos por sessão, máximo de 50 dólares por reembolso, idempotência exigida em cada chamada. Eles executaram a suíte de testes de contrato contra a OpenAPI do Stripe em cada PR. Seis meses depois, eles processaram 12.000 reembolsos com zero cobranças duplicadas.

Agente tria problemas do GitHub. Uma equipe de plataforma construiu um agente de triagem de problemas inspirado no Clawsweeper. Eles simularam a API do GitHub no Apidog, executaram o agente através de 50 testes de cenário cobrindo casos extremos (problemas excluídos, rótulos ausentes, entrada de usuário malformada) e encontraram três falhas antes do lançamento. O agente agora lida com a triagem em um repositório público com 5.000 problemas abertos.

Conclusão

Se você tirar uma coisa deste guia, leve esta: o agente não é o problema. A API é o problema, ou é a solução, dependendo se você a testou.

Cinco pontos a serem levados em consideração:

• Trate os esquemas de ferramentas como contratos e execute testes de contrato na CI.
• Simule endpoints destrutivos para cada ciclo de desenvolvimento de agente.
• Exija chaves de idempotência em cada escrita que seu agente possa chamar.
• Defina limites de orçamento por agente que falham em "closed" quando atingidos.
• Repita cenários em cada PR que toque na API ou nas definições das ferramentas.

Os incidentes virais deste ano não serão os últimos. Toda equipe que lança agentes enfrentará um desses modos de falha pelo menos uma vez. As equipes que se recuperam rapidamente são aquelas que já tinham as salvaguardas implementadas. Baixe o Apidog e comece com a etapa do servidor de simulação; isso por si só o salvará de uma noite sem sono neste trimestre. Para a perspectiva da equipe de QA sobre este mesmo problema, consulte ferramentas de teste de API para engenheiros de QA. Para um contexto mais amplo sobre como escrever definições de ferramentas que os agentes podem usar com segurança, consulte como escrever arquivos AGENTS.md.

FAQ

Como testar chamadas de API de agentes de IA sem gastar dinheiro em tokens?

Execute seu agente contra um servidor de simulação durante o desenvolvimento. As URLs de simulação do Apidog retornam respostas realistas gratuitamente, para que seus ciclos de teste não queimem créditos reais da API. Defina a temperatura para 0 e use um pequeno conjunto de prompts fixos. Você pode executar milhares de iterações de teste pelo custo do servidor de simulação, que é zero. Veja a lista de verificação de testes do engenheiro de QA para a configuração completa.

Qual a diferença entre testar o agente e testar a API?

O teste de agente verifica se o modelo escolhe a ferramenta certa e preenche os argumentos corretamente. O teste de API verifica se o endpoint se comporta corretamente quando chamado. Ambos importam. Um agente perfeito chamando uma API quebrada ainda produz resultados quebrados, e um agente quebrado chamando uma API perfeita ainda entrega bugs. Você precisa que ambas as camadas sejam testadas separadamente.

Preciso de chaves de idempotência em todos os endpoints?

Sim, em todos os endpoints de escrita. As leituras são idempotentes por definição. As escritas não são, e os agentes tentam novamente. As cinco linhas de middleware para suportar um cabeçalho de idempotência se pagam na primeira vez que o agente tenta novamente um erro 500 e você não obtém uma linha duplicada.

Como prevenir que a injeção de prompt acione chamadas de API incorretas?

Não confie apenas na camada de prompt. A API deve impor a autorização com base no contexto original do usuário, não na solicitação do agente. Se uma sessão de contexto de usuário normalmente não pode acessar /admin/delete-all-users, então o agente agindo em nome desse usuário também não deveria ser capaz, independentemente do que o prompt diz. O OWASP LLM Top 10 aborda isso em detalhes.

Posso usar Apidog com Claude ou GPT diretamente, sem escrever minha própria camada de ferramentas?

Você aponta as definições de ferramenta do seu agente para a URL de simulação do Apidog durante o teste. Tanto Claude quanto GPT suportam URLs base HTTP arbitrárias em suas definições de ferramenta, então a troca é uma variável de ambiente. Quando estiver pronto para testar contra o ambiente de estágio ou produção, mude a variável.

Qual é o limite de orçamento ideal para um agente?

Comece restrito e flexibilize com os dados. Comece com 50.000 tokens por sessão, 30 chamadas de API por minuto, 5 dólares por tarefa. Observe as métricas por duas semanas. Aumente os limites que você legitimamente atinge. Reduza os limites que você nunca alcança. Revise mensalmente. O objetivo não é um número fixo; é um número apertado o suficiente para capturar loops descontrolados e solto o suficiente para permitir que o trabalho real aconteça.

Como detectar o desvio de esquema entre as ferramentas do meu agente e minha API?

Execute uma comparação de esquema na CI em cada PR. Compare a definição da ferramenta do agente (esquema JSON) com o esquema do corpo da solicitação OpenAPI para o mesmo endpoint. Faça a compilação falhar se eles divergirem. O trecho de código Python de 30 linhas na seção de salvaguardas acima faz isso; copie-o para o seu repositório e conecte-o ao GitHub Actions.