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

Um agente de codificação de IA executou um script, viu sucesso e, em seguida, uma tabela de banco de dados de produção desapareceu. O post-mortem no Hacker News viralizou com o título: “A IA não apagou seu banco de dados, você o fez.” O ponto é correto: o agente seguiu uma definição de ferramenta, a ferramenta chamou 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. Em outra thread no r/ClaudeAI, um agente em loop de cobrança consumiu centenas de dólares em tokens antes que alguém percebesse. Superfície diferente, mesma classe de falha: ninguém testou a API.

Experimente o Apidog hoje

💡 Se você está lançando agentes autônomos que chamam suas APIs, este guia é para você. Você verá como simular endpoints externos durante o desenvolvimento, isolar operações destrutivas, escrever testes de contrato para esquemas de ferramentas, definir limites de orçamento por agente e ensaiar modos de falha antes da produção. Usaremos o Apidog porque ele fala OpenAPI nativamente, executa servidores de simulação sem código de “cola” e oferece testes de cenário que mapeiam bem sequências de chamadas de ferramentas.

TL;DR

Agentes falham em produção quando suas ferramentas não têm salvaguardas no lado da API: limites de taxa ausentes, falta de idempotência, exclusões “quentes” e esquemas quebrados. Corrija isso com quatro práticas:

1. Teste contratos entre definições de ferramentas e sua especificação OpenAPI.
2. Use servidores de simulação para endpoints destrutivos.
3. Imponha limites de orçamento por agente e chaves de idempotência.
4. Reproduza cenários de falha na CI.

O Apidog oferece importação OpenAPI, simulações e executor de cenários em um único projeto.

Introdução

Há um ano, “testar um agente de IA” significava enviar prompts para Claude ou GPT e avaliar a resposta. Isso não é mais suficiente.

Agentes atuais chamam funções. Essas funções atingem APIs. Essas APIs conversam 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 de estilo: é um incidente de produção.

A história viral do Hacker News capturou essa mudança. A IA não apagou o banco de dados; o humano permitiu que ela chamasse uma operação de escrita sem controles entre o modelo e os dados. A thread explodiu porque muitos desenvolvedores reconheceram o risco: “eu quase enviei isso”.

A solução não é apenas “melhorar o prompt”. A camada do modelo importa, mas a camada da API é onde você impede o dano.

Neste guia, você vai implementar quatro salvaguardas para integrações agente-API:

• contrato entre ferramenta e OpenAPI;
• simulações para operações destrutivas;
• idempotência para escritas;
• orçamento por agente;
• cenários de falha executados na CI.

Por que falhas de agente parecem falhas de API

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

Injeção de prompt

Um usuário carrega um PDF com instruções ocultas. O agente lê o arquivo e a próxima chamada de ferramenta vai para /admin/users com delete_all=true.

O modelo seguiu instruções. O problema real é que um token associado a uma sessão de usuário conseguiu chamar um endpoint administrativo.

Mitigação correta:

• não exponha operações destrutivas a tokens de usuário;
• valide autorização no backend;
• limite escopo por conta de serviço;
• registre e bloqueie chamadas de alto risco.

O OWASP classifica esse tipo de risco no LLM Top 10. A mitigação principal é autorização do lado da API, não engenharia de prompt.

Esquema de ferramenta divergente

Sua OpenAPI diz que amount é um inteiro em centavos.

{
  "amount": {
    "type": "integer",
    "description": "Valor em centavos"
  }
}

A ferramenta do agente diz que amount é um float em dólares.

{
  "amount": {
    "type": "number",
    "description": "Valor em dólares"
  }
}

Três meses depois, alguém reembolsa 19 centavos como 19 dólares.

O modelo não estava “errado”. Ele usou o esquema que você entregou. O contrato desviou.

Limite de taxa ausente

Um agente em loop de repetição chama seu endpoint de e-mail transacional mil vezes em dois minutos porque o planejador continua marcando a etapa como “ainda não concluída”.

Resultado:

• custo aumentado;
• fila de e-mails real;
• risco de bloqueio pelo provedor;
• usuários recebendo spam.

O modelo não foi malicioso. A ferramenta não tinha teto.

Idempotência ausente

O agente chama POST /payments, recebe timeout e tenta novamente. A chamada original talvez tenha sido processada. A segunda chamada cobra o cliente de novo.

A camada do agente não sabe o estado final da primeira chamada. A API precisa oferecer um mecanismo seguro para repetição.

Use chaves de idempotência.

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

1. Testes de contrato de esquema de ferramenta

A especificação OpenAPI deve ser a fonte da verdade. A definição de ferramenta do agente deve ser derivada ou validada contra ela.

Execute uma validação em cada PR que altere:

• a especificação OpenAPI;
• as definições das ferramentas;
• endpoints chamados por agentes.

Exemplo mínimo em Python:

import json
from jsonschema import Draft202012Validator

def validate_tool_against_openapi(tool_def: dict, openapi_spec: dict) -> list[str]:
    """Retorna erros de incompatibilidade. 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 sem 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"Incompatibilidade de tipo em {prop}: "
                    f"API={api_def.get('type')} "
                    f"ferramenta={tool_def_prop.get('type')}"
                )

    return errors

Exemplo de uso em CI:

import json
import sys

with open("openapi.json") as f:
    openapi_spec = json.load(f)

with open("agent-tools.json") as f:
    tools = json.load(f)

all_errors = []

for tool in tools:
    all_errors.extend(validate_tool_against_openapi(tool, openapi_spec))

if all_errors:
    for error in all_errors:
        print(f"ERROR: {error}")
    sys.exit(1)

print("Contratos válidos.")

Regra prática: se a ferramenta divergir da OpenAPI, falhe o build. Não emita apenas warning.

2. Sandbox e simulação para endpoints destrutivos

Agentes precisam de um lugar para praticar. Esse lugar não deve ser produção.

Crie simulações para todos os endpoints que alteram estado:

• POST;
• PUT;
• PATCH;
• DELETE.

O fluxo recomendado:

1. importe sua OpenAPI;
2. gere respostas simuladas;
3. aponte a URL base do agente para o mock server;
4. execute prompts de teste;
5. revise as chamadas de ferramenta;
6. só depois teste em staging.

O Apidog gera simulações diretamente da especificação OpenAPI, incluindo valores de campo realistas com padrões Faker. Você aponta a URL base da API do agente para o servidor de simulação e executa iterações do prompt.

Se o agente insistir em chamar PUT /users/{id}/delete por erro de interpretação, o mock intercepta. A tabela de produção não é tocada.

Veja também o padrão de desenvolvimento contract-first.

3. Chaves de idempotência e exclusões soft

Todo endpoint de escrita chamado por agente deve aceitar uma chave de idempotência.

Toda exclusão deve ser soft delete por padrão. Hard delete deve exigir fluxo separado, idealmente com aprovação humana.

Exemplo 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: "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);

No agente, gere um UUID por operação lógica:

import { randomUUID } from "crypto";

const idempotencyKey = randomUUID();

await fetch("https://api.example.com/payments", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey
  },
  body: JSON.stringify({
    customer_id: "cus_123",
    amount: 1999
  })
});

Se houver timeout e o agente tentar novamente com a mesma chave, sua API retorna a resposta em cache em vez de executar a cobrança outra vez.

Esse padrão também protege:

• envio duplicado de e-mail;
• criação duplicada de registros em CRM;
• múltiplos comentários em issues;
• geração repetida de tickets;
• webhooks reenviados.

4. Limites de orçamento por agente

Cada agente precisa de orçamento explícito:

• tokens;
• chamadas de API;
• gasto em dinheiro;
• tempo de execução;
• profundidade de chamadas de ferramenta.

Exemplo de limites iniciais:

Recurso	Limite inicial
Tokens por sessão	50.000
Chamadas de API por minuto	30
Gasto por tarefa	US$ 5
Profundidade de ferramenta	10 chamadas aninhadas
Tempo máximo de execução	5 minutos

Quando um limite for atingido, retorne 429 com headers estruturados:

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

{
  "error": "budget_exceeded",
  "limit": "api_calls_per_minute",
  "retry_after_seconds": 60
}

O planejador do agente pode então:

• pausar;
• escalar para humano;
• resumir o estado;
• abortar com segurança.

Esses quatro controles se complementam:

• testes de contrato capturam erro de esquema;
• mocks capturam operações destrutivas;
• idempotência captura tempestades de retry;
• orçamento captura loops descontrolados.

O objetivo é transformar “o agente fez algo terrível” em “o agente recebeu 429, registrou o problema e pediu ajuda”.

Teste chamadas de API de agente com Apidog

Agora o fluxo prático no Apidog.

Você vai precisar de:

• especificação OpenAPI da API chamada pelo agente;
• definições de ferramentas do agente;
• ambiente de teste ou mock;
• prompts ou tarefas representativas.

Etapa 1: Importar a especificação OpenAPI

No Apidog:

1. crie um novo projeto;
2. importe seu arquivo OpenAPI 3.x;
3. revise paths, schemas e exemplos gerados;
4. confirme se cada endpoint usado pelo agente está documentado.

Se sua API ainda não estiver em OpenAPI, comece por aí. A confiabilidade do agente depende de uma fonte única de verdade que humanos e agentes possam usar.

Veja o guia de fluxo de trabalho de API design-first se estiver começando do zero.

Etapa 2: Definir respostas simuladas para endpoints destrutivos

Liste endpoints que alteram dados:

POST   /payments
POST   /refunds
PATCH  /users/{id}
DELETE /users/{id}
POST   /notifications

Para cada endpoint no Apidog:

1. abra o endpoint;
2. adicione uma resposta simulada;
3. gere dados a partir do schema;
4. substitua valores para ficarem claramente falsos;
5. use IDs e prefixos de teste.

Exemplos de valores seguros:

{
  "id": "mock_user_1970_001",
  "email": "[e-mail]",
  "created_at": "1970-01-01T00:00:00Z",
  "status": "mocked"
}

Depois, inicie o servidor de simulação.

O Apidog fornece uma URL estável como:

https://mock.apidog.com/m1/your-project-id/

Durante o desenvolvimento, configure o agente assim:

AGENT_API_BASE_URL=https://mock.apidog.com/m1/your-project-id/

Em staging:

AGENT_API_BASE_URL=https://staging-api.example.com

Em produção:

AGENT_API_BASE_URL=https://api.example.com

Não coloque URLs de mock diretamente no prompt. Use variáveis de ambiente.

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

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

Para um agente que tria tickets de suporte, o cenário pode ser:

1. POST /auth/token com credenciais de teste e captura do bearer token.
2. GET /tickets?status=open com o token e captura do primeiro ID.
3. POST /tickets/{id}/triage com categoria e asserção de 200.
4. POST /notifications com mensagem e validação do corpo.

Exemplo de asserções úteis:

status == 200
response.assigned_to != null
response.category in ["billing", "bug", "account", "feature_request"]
response.message matches /ticket #[0-9]+/i

Você está ensaiando a sequência que o agente faria, mas contra um servidor seguro.

Se um desenvolvedor mudar o schema do ticket e a regex parar de bater, o cenário falha antes do agente chegar à produção.

Veja o playbook de testes de API para engenheiros de QA.

Etapa 4: Executar a partir da CI

Execute cenários no pipeline para cada PR que altere:

• OpenAPI;
• código de endpoint;
• definições de ferramentas;
• prompts que mudam comportamento de chamada.

Com a CLI do Apidog, o comando se parece com:

apidog run -t scenario-id --env test

Exemplo conceitual em GitHub Actions:

name: Agent API Contract Tests

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

jobs:
  test-agent-api:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run Apidog scenario
        run: apidog run -t ${{ secrets.APIDOG_SCENARIO_ID }} --env test

Ajuste o comando conforme sua configuração real de CLI e autenticação.

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

Ao trocar de modelo, você precisa verificar se as chamadas de ferramentas continuam compatíveis.

Fluxo:

1. execute o agente com o modelo A;
2. capture o rastro de chamadas;
3. execute o mesmo cenário com o modelo B;
4. compare endpoints, métodos e bodies;
5. bloqueie rollout se houver mudança inesperada.

Exemplo de diferença que deve acender alerta:

{
- "priority": "high",
+ "priority": "urgent",
  "category": "billing"
}

Ou:

{
- "due_date": "2026-01-15",
+ "due_date": "15/01/2026"
}

Esse tipo de desvio aparece antes do deploy quando você roda os dois modelos contra o mesmo cenário.

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

Técnicas avançadas e dicas profissionais

Defina temperatura zero nos testes

Agentes não determinísticos geram falhas não determinísticas.

Para testes da camada de ferramenta:

{
  "temperature": 0
}

Você está testando chamadas de API, não criatividade.

Tire snapshots dos rastreamentos de ferramenta

Registre cada execução:

[
  {
    "tool": "list_tickets",
    "arguments": {
      "status": "open"
    }
  },
  {
    "tool": "triage_ticket",
    "arguments": {
      "id": "ticket_123",
      "category": "billing"
    }
  }
]

Compare com a baseline anterior. Se o agente começar a chamar /users duas vezes em vez de uma, você quer saber 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 curtos;
• proxy de assinatura;
• cofres para segredos;
• rotação regular.

Evite:

PROD_DATABASE_URL=postgres://...

em qualquer ambiente que o agente possa ler.

Separe chaves de leitura e escrita

Muitas tarefas de agente são majoritariamente leitura.

Crie chaves separadas:

agent_readonly_key
agent_write_key

A chave de escrita deve exigir:

• aprovação humana;
• escopo menor;
• orçamento menor;
• auditoria mais detalhada.

Use HTTP 423 Locked para aprovação humana

Quando o agente tentar chamar uma operação que exige confirmação, retorne 423.

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

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

403 significa “você não pode fazer isso”.

423 comunica melhor: “você ainda não pode fazer isso”.

Feche em caso de desvio de esquema

Se ferramenta e OpenAPI divergirem:

• falhe o build;
• bloqueie merge;
• exija correção do contrato.

O custo de uma falha extra de CI é menor que um incidente de produção.

Erros comuns a evitar

• Codificar a URL de simulação diretamente no prompt.
• Ignorar idempotência em endpoints “pequenos”.
• Registrar bodies completos de requisição em produção.
• Permitir acesso direto ao banco de dados.
• Confiar em pontuação de confiança do agente como sinal de segurança.
• Usar a mesma chave para leitura, escrita e operações administrativas.
• Testar apenas respostas do modelo e não as chamadas de ferramenta.

Se seu agente conversa com serviços internos fora de um gateway único, veja padrões de teste 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, equipes de um desenvolvedor
LangSmith / LangGraph eval harness	Médio	Replay de rastro integrado, métricas cientes do modelo	Forte no lado do agente, leve no lado da API	Equipes de IA focadas em avaliação
Postman + Postbot	Médio	UI familiar, grande biblioteca de templates	Servidor de simulação é complemento pago, sintaxe de cenário datada	Equipes já investidas no Postman
Cenários + simulações do Apidog	Médio	OpenAPI nativo, simulações gratuitas, CLI de cenário para CI	Menos reconhecimento de marca que Postman	Equipes que querem design, mocks e testes em um projeto

Resumo prático:

• se você já usa LangSmith, mantenha avaliações de prompt lá e adicione teste de API separado;
• se você superou o preço ou o modelo de simulação do Postman, o Apidog é um forte substituto;
• se está começando do zero, escolha uma ferramenta que cubra OpenAPI, simulações e cenários no mesmo projeto.

Algumas equipes combinam ferramentas: LangSmith para avaliação de prompts e Apidog para contrato, mocks e cenários de API. Isso funciona bem porque são camadas diferentes.

Casos de uso no mundo real

Agente atualiza linhas de banco de dados de produção

Uma equipe de sucesso do cliente criou um agente que atualiza campos de conta a partir de tickets de suporte.

Antes do lançamento, eles:

• exigiram chave de idempotência em endpoints de escrita;
• executaram 200 repetições de cenário no Apidog;
• usaram banco de dados sandbox;
• validaram enums e schemas.

As repetições capturaram dois casos em que o agente tentou definir subscription_status com uma string fora do enum. A equipe adicionou validação e lançou sem incidente.

Agente chama API de pagamentos

Uma equipe fintech criou um agente de reembolso automatizado.

Controles aplicados:

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

Eles executaram a suíte de testes de contrato contra a OpenAPI do Stripe. Seis meses depois, processaram 12.000 reembolsos sem cobranças duplicadas.

Agente tria issues do GitHub

Uma equipe de plataforma criou um agente de triagem inspirado no Clawsweeper.

Eles:

• simularam a API do GitHub no Apidog;
• executaram 50 cenários;
• cobriram issues excluídas, labels ausentes e entradas malformadas;
• corrigiram três falhas antes do lançamento.

O agente agora lida com triagem em um repositório público com 5.000 issues abertas.

Conclusão

O agente não é o problema principal. A API é o problema ou a solução, dependendo de como você a testou.

Checklist final:

• trate esquemas de ferramentas como contratos;
• execute testes de contrato na CI;
• simule endpoints destrutivos;
• exija idempotência em toda escrita;
• defina orçamento por agente;
• bloqueie desvio de schema;
• reproduza cenários em cada PR relevante.

Os incidentes virais deste ano não serão os últimos. Toda equipe que lança agentes vai encontrar algum desses modos de falha. As equipes que se recuperam rápido são as que já tinham salvaguardas.

Baixe o Apidog e comece pelo servidor de simulação. Para a perspectiva de QA, veja ferramentas de teste de API para engenheiros de QA. Para escrever definições de ferramentas mais seguras, veja como escrever arquivos AGENTS.md.

FAQ

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

Execute o agente contra um servidor de simulação durante o desenvolvimento. As URLs de simulação do Apidog retornam respostas realistas, então seus ciclos de teste não queimam créditos reais da API. Defina temperatura como 0 e use um conjunto pequeno de prompts fixos. Veja a lista de verificação de testes do engenheiro de QA.

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

Teste de agente verifica se o modelo escolhe a ferramenta certa e preenche argumentos corretamente.

Teste de API verifica se o endpoint se comporta corretamente quando chamado.

Você precisa dos dois. Um agente correto chamando uma API quebrada ainda gera resultado quebrado. Um agente quebrado chamando uma API correta ainda entrega bug.

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

Em todos os endpoints de escrita, sim.

Leituras são idempotentes por definição. Escritas não são, e agentes tentam novamente. O middleware de idempotência se paga na primeira vez que um retry de erro 500 não cria uma linha duplicada.

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

Não confie apenas no prompt.

A API deve impor autorização com base no contexto original do usuário, não na solicitação do agente. Se um usuário não pode acessar /admin/delete-all-users, o agente atuando em nome desse usuário também não deve conseguir.

Posso usar Apidog com Claude ou GPT diretamente?

Durante o teste, aponte as definições de ferramenta do agente para a URL de simulação do Apidog.

Use variável de ambiente para trocar entre:

AGENT_API_BASE_URL=https://mock.apidog.com/m1/project
AGENT_API_BASE_URL=https://staging-api.example.com
AGENT_API_BASE_URL=https://api.example.com

Quando estiver pronto para staging ou produção, altere a variável.

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

Comece restrito e ajuste com dados.

Valores iniciais úteis:

• 50.000 tokens por sessão;
• 30 chamadas de API por minuto;
• 5 dólares por tarefa;
• 10 chamadas de ferramenta aninhadas.

Observe métricas por duas semanas. Aumente limites legitimamente atingidos. Reduza limites que nunca são usados. Revise mensalmente.

Como detectar desvio de esquema entre ferramentas do agente e API?

Execute comparação de schema na CI em cada PR.

Compare:

• definição da ferramenta do agente;
• schema OpenAPI do request body;
• campos obrigatórios;
• tipos;
• enums;
• formatos.

Faça o build falhar se houver divergência. O snippet Python da seção de salvaguardas é suficiente para começar.