Como Testar Agentes de IA que Usam Suas APIs Sem Perder Dados

Um agente de codificação de IA executou um script, viu o script funcionar e, logo depois, uma tabela de banco de dados em produção desapareceu. A post-mortem no Hacker News viralizou com o título: “A IA não apagou seu banco de dados, você apagou.” O ponto é simples: o agente seguiu uma definição de ferramenta, a ferramenta chamou um endpoint real, o endpoint não tinha salvaguardas e um humano entregou credenciais de produção a um processo que não para para perguntar se DELETE FROM users parece suspeito. Outro caso, no r/ClaudeAI, mostrou um agente preso em um loop de cobrança que consumiu centenas de dólares em tokens. Superfície diferente, mesma falha: o problema não é só o modelo. É a API não testada.

Experimente o Apidog hoje

💡 Se você está criando agentes autônomos que chamam APIs, este guia mostra como testar essas integrações antes da produção: mocks para endpoints externos, isolamento de operações destrutivas, testes de contrato para esquemas de ferramentas, limites de orçamento por agente e cenários de falha na CI. Usaremos o Apidog porque ele trabalha nativamente com OpenAPI, executa servidores mock sem código de cola e permite montar cenários alinhados às sequências de chamadas de ferramentas do agente.

TL;DR

Agentes falham em produção quando suas ferramentas chamam APIs sem salvaguardas: sem rate limit, sem idempotência, com exclusões diretas e esquemas divergentes. A correção prática envolve quatro camadas:

1. Testar contratos entre definições de ferramentas e OpenAPI.
2. Usar servidor mock para endpoints destrutivos.
3. Exigir idempotência e limites por agente.
4. Reproduzir cenários de falha na CI.

O Apidog ajuda nesse fluxo com importação OpenAPI, mocks e executor de cenários em um único projeto.

Introdução

Há pouco tempo, “testar um agente de IA” significava testar prompts no Claude ou GPT e avaliar a resposta. Isso já não basta. Agentes modernos chamam funções, essas funções acessam APIs, e essas APIs conversam com bancos de dados, gateways de pagamento e serviços externos.

Uma definição de ferramenta errada ou um limite de taxa ausente não é um detalhe de implementação. É um incidente de produção esperando acontecer.

A camada do modelo importa, mas a camada da API é onde você impõe controles reais. Neste guia, vamos implementar salvaguardas para integrações agente-API:

• contrato entre ferramenta e OpenAPI;
• mocks para endpoints destrutivos;
• idempotência para operações de escrita;
• orçamento por agente;
• cenários reproduzíveis na CI;
• validação de mudanças de modelo antes do deploy.

Por que falhas de agente se parecem com falhas de API

Em muitos incidentes, o modelo não é o componente mais perigoso. A API é.

Injeção de prompt

Um usuário envia um PDF com instruções escondidas. O agente lê o arquivo e, em seguida, chama /admin/users com delete_all=true.

A mitigação principal não é “melhorar o prompt”. É impedir, no lado da API, que um token originado de uma sessão de usuário consiga chamar uma operação administrativa destrutiva.

A OWASP trata isso no LLM Top 10: autorização precisa ser aplicada pela API, não pelo prompt.

Divergência de esquema

Sua especificação OpenAPI define amount como inteiro em centavos. A definição de ferramenta do agente define amount como float em dólares.

Resultado possível: uma cobrança de 19 centavos vira 19 dólares.

O modelo não “errou”. Ele seguiu o esquema que recebeu. O contrato entre ferramenta e API estava quebrado.

Rate limit ausente

Um agente entra em loop e chama um endpoint de e-mail transacional mil vezes em dois minutos. Cada tentativa custa dinheiro e envia um e-mail real.

Isso não é malícia do modelo. É ausência de teto operacional.

Idempotência ausente

O agente chama POST /payments, recebe timeout e tenta novamente. A primeira chamada foi processada, mas o agente não sabe. Sem chave de idempotência, o cliente pode ser cobrado duas vezes.

A API precisa dar ao agente uma forma segura de repetir uma operação lógica sem duplicar efeitos colaterais.

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

1. Testes de contrato para esquemas de ferramentas

Sua especificação OpenAPI deve ser a fonte da verdade. As definições de ferramentas do agente precisam ser verificadas contra ela.

Um teste mínimo em Python pode detectar campos ausentes, campos extras e tipos incompatíveis:

import json
from jsonschema import Draft202012Validator

def validate_tool_against_openapi(tool_def: dict, openapi_spec: dict) -> list[str]:
    """Retorna uma lista de erros. Lista vazia = contrato válido."""
    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 não define campo obrigatório: {missing}")

    for extra in tool_props - api_props:
        errors.append(f"Ferramenta define campo inexistente 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"Tipo incompatível em {prop}: "
                    f"API={api_def.get('type')} "
                    f"tool={tool_def_prop.get('type')}"
                )

    return errors

Use esse teste em todo PR que altere:

• especificação OpenAPI;
• definições de ferramentas;
• payloads de endpoints usados por agentes.

Se houver divergência, falhe a build.

2. Ambientes mock e sandbox para endpoints destrutivos

Agentes precisam praticar. Eles não devem praticar em produção.

Padrão recomendado:

• desenvolvimento: servidor mock;
• staging: banco sandbox;
• produção: somente após aprovação e com credenciais restritas.

Endpoints de escrita, como POST, PUT, PATCH e DELETE, devem ter equivalentes mock que retornam a mesma forma de resposta sem alterar dados reais.

O Apidog gera mocks a partir da especificação OpenAPI, incluindo dados realistas. Durante o desenvolvimento, a URL base do agente aponta para o servidor mock. Se o agente insistir em chamar um endpoint destrutivo por engano, o mock captura o comportamento sem tocar na produção.

Veja também o guia de desenvolvimento contract-first.

3. Idempotência e soft deletes

Todo endpoint de escrita que um agente pode chamar deve aceitar uma chave de idempotência. Toda exclusão deve ser soft delete por padrão.

Exemplo de middleware em Express:

const idempotencyCache = new Map();

function idempotency(req, res, next) {
  const key = req.headers["idempotency-key"];

  if (!key) {
    return res.status(400).json({
      error: "Missing Idempotency-Key header",
    });
  }

  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 deve gerar um UUID por operação lógica e reutilizar a mesma chave em retentativas.

Isso evita:

• cobranças duplicadas;
• e-mails duplicados;
• criação duplicada de registros;
• reprocessamento acidental após timeout.

4. Orçamentos por agente

Todo agente precisa de limites explícitos:

• tokens por sessão;
• chamadas de API por minuto;
• custo acumulado;
• tempo máximo de execução;
• profundidade máxima de chamadas de ferramenta.

Exemplo de política inicial:

tokens_por_sessao: 50000
chamadas_api_por_minuto: 30
custo_maximo_centavos: 500
profundidade_chamadas: 10

Quando um limite for atingido, retorne 429 Too Many Requests com metadados claros:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-Budget-Exceeded: chamadas_api_por_minuto
Content-Type: application/json

{
  "error": "Budget exceeded",
  "limit": "chamadas_api_por_minuto",
  "retry_after_seconds": 60
}

O agente deve parar, registrar o problema e escalar para um humano.

Testando chamadas de API de agentes com Apidog

Agora o fluxo prático usando Apidog.

Você precisa de:

• uma especificação OpenAPI da API chamada pelo agente;
• as definições de ferramentas do agente;
• uma lista de endpoints destrutivos ou sensíveis.

Passo 1: importar a especificação OpenAPI

No Apidog:

1. Crie um novo projeto.
2. Importe seu arquivo OpenAPI 3.x.
3. Verifique os caminhos, schemas, exemplos e respostas.
4. Corrija endpoints sem schema de request ou response.

Se sua API ainda não usa OpenAPI, comece por aí. O agente e os testes precisam de uma fonte única de verdade.

O guia de fluxo de trabalho de API design-first explica esse processo.

Passo 2: criar mocks para endpoints destrutivos

Liste todos os endpoints que alteram estado:

• POST /payments
• POST /refunds
• PATCH /users/{id}
• DELETE /users/{id}
• POST /notifications
• PUT /subscriptions/{id}

Para cada endpoint:

1. Abra o endpoint no Apidog.
2. Adicione uma resposta mock.
3. Use dados claramente falsos.
4. Padronize prefixos como mock_user_, mock_payment_ e timestamps antigos.
5. Evite payloads parecidos com produção.

Exemplo de resposta mock para exclusão:

{
  "id": "mock_user_123",
  "deleted": true,
  "deleted_at": "1970-01-01T00:00:00Z",
  "mode": "mock"
}

Depois, inicie o servidor mock. O Apidog fornece uma URL semelhante a:

https://mock.apidog.com/m1/seu-id-de-projeto/

No ambiente do agente:

API_BASE_URL="https://mock.apidog.com/m1/seu-id-de-projeto/"

A partir daí, chamadas como DELETE /users/{id} retornam respostas válidas sem afetar o banco real.

Passo 3: escrever um cenário com a sequência do agente

Cenários do Apidog permitem encadear chamadas com asserções.

Para um agente que tria tíquetes de suporte, o cenário pode ser:

1. POST /auth/token

   • usa credenciais de teste;
   • captura access_token.

2. GET /tickets?status=open

   • usa o token;
   • captura o ID do primeiro tíquete.

3. POST /tickets/{id}/triage

   • envia categoria;
   • espera 200;
   • captura assigned_to.

4. POST /notifications

   • envia mensagem;
   • valida o corpo com regex.

Exemplo de asserções:

status == 200
body.assigned_to != null
body.category in ["billing", "technical", "account"]

Esse cenário simula o caminho que o agente executaria, mas em ambiente controlado.

Se alguém mudar o schema de ticket e o agente começar a enviar um campo inválido, o cenário falha antes da produção.

Veja também o guia de teste de API para engenheiros de QA.

Passo 4: executar cenários na CI

Execute os cenários em cada PR que altera API ou ferramentas do agente.

Exemplo conceitual:

apidog run -t scenario-id --env test

Em uma GitHub Action, o fluxo fica assim:

name: agent-api-tests

on:
  pull_request:
    paths:
      - "openapi/**"
      - "agents/tools/**"
      - "src/api/**"

jobs:
  api-scenarios:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Apidog scenarios
        run: apidog run -t scenario-id --env test

A regra é simples: se a API ou a definição de ferramenta mudou, os cenários precisam rodar.

Passo 5: comparar modelos lado a lado

Ao trocar de modelo, não valide apenas a qualidade da resposta textual. Compare as chamadas de ferramenta.

Processo:

1. Execute o agente com o modelo A contra o mesmo cenário.
2. Capture o rastro de chamadas.
3. Execute o agente com o modelo B.
4. Compare:
   • endpoints chamados;
   • ordem das chamadas;
   • payloads;
   • campos omitidos;
   • formatos de data;
   • enums escolhidos.

Diferenças aparecem rápido. O modelo B pode enviar priority: "high" onde o modelo A enviava priority: "normal", ou pode omitir um campo obrigatório.

Esse padrão também aparece em integrações com novos modelos, como no guia de integração da API GPT-5.5.

Técnicas avançadas

Fixe a temperatura em zero nos testes

Testes de chamadas de ferramenta precisam ser reproduzíveis.

Use:

temperature: 0
seed: valor_fixo_se_disponivel

Você está testando a integração, não criatividade.

Registre rastros de chamadas de ferramenta

Para cada execução, registre:

{
  "agent_id": "support_triage_agent",
  "model": "modelo-x",
  "tool_calls": [
    {
      "method": "GET",
      "path": "/tickets",
      "args": {
        "status": "open"
      }
    },
    {
      "method": "POST",
      "path": "/tickets/123/triage",
      "args": {
        "category": "billing"
      }
    }
  ]
}

Compare o rastro atual com a linha de base. Se o agente começa a chamar /users duas vezes em vez de uma, isso deve aparecer no PR, não na fatura.

Nunca dê credenciais de produção diretamente ao agente

Use:

• contas de serviço com escopo mínimo;
• tokens de curta duração;
• proxy de assinatura;
• cofres de segredo;
• separação entre leitura e escrita.

Evite:

PROD_DATABASE_URL=...
ADMIN_API_KEY=...

em qualquer ambiente acessível ao agente.

Separe chaves de leitura e escrita

A maioria das tarefas de agentes é majoritariamente leitura.

Crie chaves separadas:

agent_readonly_key
agent_write_key
admin_human_approval_key

Use chaves de escrita apenas para tarefas com aprovação explícita.

Use HTTP 423 para aprovação humana

Quando uma operação exigir confirmação humana, retorne 423 Locked:

HTTP/1.1 423 Locked
Content-Type: application/json

{
  "error": "human_approval_required",
  "confirmation_url": "https://app.example.com/approve/abc123"
}

Isso é mais claro que 403 Forbidden. 403 significa “não permitido”. 423 comunica “bloqueado até aprovação”.

Falhe a build em divergência de schema

Não envie apenas warning. Se a definição da ferramenta divergir do OpenAPI, a CI deve falhar.

O custo de builds quebradas é menor que o custo de um agente chamando produção com payload incorreto.

Erros comuns

Evite estes padrões:

• Hardcode de URL mock no prompt do agente.
• Falta de idempotência em endpoints “pequenos”.
• Logs com payloads completos contendo PII.
• Agentes com acesso direto ao banco de dados.
• Credenciais de produção em .env.
• Confiar em “confidence score” do agente como controle de segurança.
• Testar apenas resposta textual e ignorar chamadas de ferramenta.
• Fazer mock manual que diverge do OpenAPI.

Se seu agente chama vários serviços internos, veja os padrões de teste em arquitetura de microsserviços.

Alternativas e ferramentas

Abordagem	Tempo de configuração	Força	Fraqueza	Melhor para
Testes unitários artesanais	Baixo	Controle total, sem dependência de fornecedor	Alta manutenção, fácil divergir da API real	Projetos pequenos
LangSmith / LangGraph eval harness	Médio	Reprodução de rastreamento e métricas focadas no modelo	Forte no agente, fraco no lado da API	Equipes focadas em avaliação de IA
Postman + Postbot	Médio	UI familiar e grande ecossistema	Mock e cenários podem ficar limitados ou caros	Equipes já investidas no Postman
Cenários + mocks do Apidog	Médio	OpenAPI nativo, mocks e cenários em um projeto	Menos reconhecimento de marca que Postman	Equipes que querem design, mock e teste integrados

Resumo prático: se você já usa LangSmith, mantenha-o para avaliação de prompts e adicione uma camada de teste de API. Se o modelo de preço ou mock do Postman não atende, o Apidog é uma alternativa forte.

Casos de uso

Agente atualiza dados de clientes

Uma equipe de sucesso do cliente criou um agente que atualiza campos de conta com base em tíquetes de suporte.

Antes do lançamento, eles:

• exigiram idempotência em endpoints de escrita;
• executaram cenários no Apidog contra sandbox;
• validaram enums no schema;
• bloquearam hard delete.

Os testes capturaram dois casos em que o agente enviava subscription_status com valor fora do enum. A validação foi corrigida antes do deploy.

Agente chama API de pagamentos

Uma equipe fintech criou um agente para reembolsos automatizados.

Controles aplicados:

• no máximo 5 reembolsos por sessão;
• no máximo 50 dólares por reembolso;
• idempotência obrigatória;
• testes de contrato em cada PR.

Eles também executaram o conjunto de testes de contrato contra a API usada. O resultado: milhares de reembolsos processados sem duplicação.

Agente tria issues do GitHub

Uma equipe de plataforma criou um agente inspirado no Clawsweeper.

Eles simularam a API do GitHub no Apidog e executaram cenários cobrindo:

• issues excluídas;
• labels ausentes;
• entradas malformadas;
• permissões insuficientes;
• respostas inesperadas.

Três falhas foram encontradas antes do lançamento.

Checklist de implementação

Use este checklist no seu repositório:

[ ] OpenAPI é a fonte da verdade da API
[ ] Definições de ferramentas são versionadas
[ ] CI compara ferramentas contra OpenAPI
[ ] Endpoints destrutivos têm mocks
[ ] Agente usa mock em desenvolvimento
[ ] Staging usa banco sandbox
[ ] Produção exige credenciais restritas
[ ] Todo endpoint de escrita exige Idempotency-Key
[ ] Deletes são soft delete por padrão
[ ] Agentes têm orçamento de tokens
[ ] Agentes têm limite de chamadas por minuto
[ ] Agentes têm limite de custo
[ ] Cenários rodam na CI
[ ] Rastros de chamadas são armazenados
[ ] Mudanças de modelo são comparadas lado a lado
[ ] Logs removem PII e segredos

Conclusão

O agente não é o único problema. A API pode ser o ponto de falha ou a camada de proteção.

Cinco práticas fazem diferença imediata:

• trate definições de ferramentas como contratos;
• rode testes de contrato na CI;
• use mocks para endpoints destrutivos;
• exija idempotência em escritas;
• imponha orçamento por agente.

Os incidentes virais envolvendo agentes não serão os últimos. Equipes que se recuperam bem são as que já tinham salvaguardas antes do incidente.

Baixe o Apidog e comece pelo servidor mock. Depois, adicione testes de contrato e cenários na CI.

Para aprofundar, veja também:

• ferramentas de teste de API para engenheiros de QA;
• como escrever arquivos AGENTS.md.

FAQ

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

Use um servidor mock durante o desenvolvimento. Aponte a URL base do agente para o mock do Apidog e execute prompts fixos com temperatura 0. Assim, você valida payloads e sequências de chamadas sem atingir APIs reais. Veja a lista de verificação de testes para QA.

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

Teste de agente valida se o modelo escolhe a ferramenta correta e preenche argumentos adequados. Teste de API valida se o endpoint se comporta corretamente quando chamado. Você precisa dos dois.

Preciso de idempotência em todos os endpoints?

Em todos os endpoints de escrita, sim. Leituras já são idempotentes por natureza. Escritas precisam de Idempotency-Key porque agentes fazem retentativas.

Como evitar que prompt injection acione chamadas ruins?

Não dependa apenas do prompt. A API deve aplicar autorização com base no usuário original, escopo do token e política de acesso. Se um usuário não pode chamar /admin/delete-all-users, o agente atuando por ele também não pode.

Posso usar Apidog com Claude ou GPT?

Sim. Durante os testes, aponte as definições de ferramenta do agente para a URL mock do Apidog. Ao mudar de ambiente, altere a variável de URL base para mock, staging ou produção.

Qual é um bom limite de orçamento para um agente?

Comece restrito e ajuste com métricas. Um ponto de partida razoável:

50000 tokens por sessão
30 chamadas de API por minuto
5 dólares por tarefa
10 chamadas de ferramenta aninhadas

Monitore por duas semanas e ajuste.

Como detectar divergência entre ferramentas do agente e OpenAPI?

Compare o JSON Schema da ferramenta com o schema OpenAPI do endpoint correspondente em cada PR. Se houver campo ausente, campo extra ou tipo incompatível, falhe a build. O exemplo em Python deste artigo é suficiente para começar.