Como Testar Chamadas de Ferramentas de Agentes de IA com Apidog para Evitar Falhas em Produção

Um agente de IA é tão confiável quanto as APIs que ele chama. O modelo escolhe uma ferramenta, preenche os argumentos e dispara uma requisição; se essa requisição falhar, retornar o formato errado ou travar, seu agente toma uma decisão confiante com base em dados ruins. A maioria das demonstrações de agentes ignora essa parte. Agentes em produção vivem ou morrem por causa disso.

Este guia mostra como construir um agente que chama ferramentas reais e, mais importante, como usar o Apidog tanto como a camada de API quanto como o ambiente de teste por trás dele. Você projetará os endpoints das ferramentas, fará mock deles para poder desenvolver offline e escreverá asserções que capturam uma chamada de ferramenta quebrada antes que ela chegue a um usuário. O objetivo é um agente em que você possa confiar porque você o testou, e não porque o caminho feliz funcionou uma vez.

O que um agente realmente faz na camada de API

Remova o enquadramento e um loop de agente é simples:

1. O modelo recebe um objetivo do usuário e uma lista de ferramentas.
2. Ele retorna uma chamada de ferramenta: um nome de ferramenta mais argumentos JSON.
3. Seu código executa essa chamada; geralmente uma requisição HTTP para alguma API.
4. O resultado volta para o modelo.
5. O modelo chama outra ferramenta ou responde.

Todo erro interessante acontece na etapa 3 e na etapa 4. O modelo alucina um argumento, a API retorna um 422, o esquema de resposta mudou, a chamada excede o tempo limite ou um limite de taxa é acionado no meio do loop. Se você já leu sobre agentes de IA como os novos consumidores de API, esta é a versão concreta dessa ideia: seu agente é um cliente acessando suas APIs, e ele merece o mesmo rigor de teste que qualquer outro cliente.

Então o trabalho se divide em dois: defina as ferramentas como operações de API reais e testáveis, e então verifique se o agente as chama corretamente em condições boas e ruins.

Passo 1: Projete as ferramentas como operações de API reais

Antes de escrever uma única linha de código do agente, defina cada ferramenta como um endpoint de API no Apidog. Trate o esquema da ferramenta e o esquema da API como a mesma coisa, porque eles são. Uma ferramenta get_weather e o endpoint GET /weather compartilham um contrato: os mesmos parâmetros, o mesmo formato de resposta.

No Apidog, crie um endpoint para cada ferramenta com seu esquema OpenAPI; parâmetros de caminho, consulta e corpo, e uma resposta tipada. Isso lhe dá três coisas gratuitamente:

• Uma única fonte da verdade para o contrato da ferramenta que tanto o prompt do seu agente quanto seus testes leem.
• Documentação gerada automaticamente que você pode entregar ao modelo como a definição da ferramenta.
• Um esquema para validar posteriormente, para que você detecte desvios no momento em que uma resposta deixar de corresponder.

Esse hábito de "schema-first" é o mesmo por trás de um trabalho sólido de design de API em geral. A recompensa para os agentes é específica: quando a definição da sua ferramenta e o seu endpoint real vêm de um único esquema, o modelo não pode chamar uma ferramenta que sua API não suporta.

Passo 2: Faça mock das ferramentas para que você possa desenvolver offline

Você não quer que cada execução de desenvolvimento acesse APIs em produção que custam dinheiro, impõem limites de taxa ou simplesmente ainda não foram construídas. O Apidog gera um servidor mock diretamente do esquema que você acabou de definir. Cada endpoint de ferramenta retorna dados de amostra realistas e válidos de acordo com o esquema, sem nenhum backend.

Isso muda a forma como você constrói agentes. Você pode:

• Desenvolver o loop completo do agente antes que as APIs reais existam, usando mocks que correspondem ao contrato acordado.
• Executar testes de integração em CI que nunca acessam um endpoint pago.
• Forçar respostas específicas; um resultado vazio, um 500, um campo malformado; para ver como seu agente reage.

Aponte o executor de ferramentas do seu agente para a URL base do mock durante o desenvolvimento. O modelo chama get_weather, seu código acessa o mock do Apidog, e uma resposta válida retorna instantaneamente. Quando estiver pronto para a coisa real, troque a URL base através de uma variável de ambiente. O mocking é o que torna o desenvolvimento de agentes rápido e determinístico; a mesma abordagem alimenta qualquer fluxo de trabalho sério de teste de agente de IA.

Passo 3: Conecte o agente para chamar as ferramentas

Com endpoints e mocks prontos, o código do agente permanece enxuto. Aqui está a estrutura de um loop de chamada de ferramenta usando a API de Mensagens do Claude; as definições das ferramentas espelham os esquemas que você construiu no Apidog.

import anthropic, requests, os

client = anthropic.Anthropic()
TOOL_BASE = os.environ["TOOL_BASE_URL"]  # Mock do Apidog durante o desenvolvimento, API real em produção

tools = [{
    "name": "get_weather",
    "description": "Get current weather for a city",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

def run_tool(name, args):
    if name == "get_weather":
        r = requests.get(f"{TOOL_BASE}/weather", params={"city": args["city"]}, timeout=10)
        r.raise_for_status()
        return r.json()

messages = [{"role": "user", "content": "What should I wear in Tokyo today?"}]
while True:
    resp = client.messages.create(
        model="claude-fable-5", max_tokens=1024, tools=tools, messages=messages
    )
    if resp.stop_reason == "tool_use":
        block = next(b for b in resp.content if b.type == "tool_use")
        result = run_tool(block.name, block.input)
        messages.append({"role": "assistant", "content": resp.content})
        messages.append({"role": "user", "content": [{
            "type": "tool_result", "tool_use_id": block.id,
            "content": str(result),
        }]})
    else:
        print(resp.content[0].text)
        break

As linhas timeout=10 e raise_for_status() importam mais do que a chamada do modelo. Elas são a diferença entre um agente que falha ruidosamente e um que alimenta silenciosamente uma requisição travada ou com erro de volta ao loop. Para uma visão mais ampla de como os agentes se encaixam nos fluxos de trabalho de API, os padrões em 5 agentes de IA para seu fluxo de trabalho de API são um companheiro útil.

Passo 4: Teste as chamadas das ferramentas, não apenas as "vibrações"

Esta é a parte que a maioria das equipes pula. Execute cada endpoint de ferramenta como uma requisição salva no Apidog com asserções, independentemente do modelo. A confiabilidade do agente é limitada pela confiabilidade de suas ferramentas, então teste as ferramentas primeiro.

Para cada endpoint de ferramenta, afirme:

• O status é 200 para entrada válida.
• O corpo da resposta corresponde ao esquema; o Apidog valida a resposta automaticamente contra sua definição OpenAPI.
• Os campos obrigatórios que o modelo lerá estão presentes e corretamente tipados.
• O tempo de resposta está dentro do limite de tempo que seu agente impõe.

Então teste os caminhos infelizes, porque é aí que os agentes se comportam mal:

• Envie os argumentos malformados que um modelo pode alucinar; uma city vazia, um número onde uma string deveria estar; e afirme que você recebe um 400/422 limpo, e não um 500.
• Force uma resposta de erro do mock e confirme que o run_tool do seu agente levanta uma exceção em vez de retornar lixo.
• Teste um resultado vazio e verifique se o agente lida com "sem dados" em vez de inventar uma resposta.

Isso é teste de contrato aplicado a ferramentas de agente; a mesma disciplina coberta em teste de contrato de API, apontada para os endpoints que seu modelo chama. Quando o formato de resposta de uma ferramenta muda, a asserção falha no CI e você a corrige antes que o agente comece a raciocinar sobre uma carga útil quebrada.

Passo 5: Lide com retentativas, tempos limite e limites de taxa

Agentes amplificam APIs instáveis. Uma única retentativa em um aplicativo normal é uma retentativa; em um loop de agente, um modelo que continua re-chamando uma ferramenta com falha pode esgotar seu limite de taxa e seu orçamento rapidamente. Construa os controles e teste-os:

• Tempos limite. Defina um tempo limite explícito em cada requisição de ferramenta, como no exemplo acima. Em seguida, use o Apidog para simular um endpoint lento e confirme que seu cliente desiste de forma limpa em vez de travar todo o loop.
• Retentativas com backoff. Tente novamente falhas transitórias, mas limite a contagem e faça backoff. Teste-o contra um mock que falha duas vezes e depois tem sucesso, e afirme que seu agente se recupera em vez de entrar em um loop infinito.
• Limites de taxa. Espere 429s sob carga. Faça mock de uma resposta com limite de taxa e verifique se seu agente espera e tenta novamente em vez de "martelar". Se você já lidou com isso em APIs de modelo brutas; veja limites de taxa da API GPT para a mesma classe de problema; a versão do agente é mais rigorosa porque o loop multiplica cada chamada.
• Disjuntor (Circuit breaking). Após N falhas em uma ferramenta, pare de chamá-la e deixe o agente relatar a falha em vez de ficar girando. Teste se o disjuntor dispara.

Execute isso como cenários repetíveis no Apidog para que uma regressão em seu tratamento de erros apareça como um teste falho, e não como um incidente de produção.

Passo 6: Execute-o de ponta a ponta contra mocks em CI

Junte tudo. Em CI, inicie seu agente apontado para o servidor mock do Apidog, alimente-o com um conjunto fixo de objetivos do usuário e faça asserções sobre o resultado final e a sequência de chamadas de ferramentas. Como os mocks são determinísticos, a mesma entrada produz as mesmas chamadas de ferramentas em cada execução, então seus testes de agente deixam de ser instáveis. Quando estiver confiante, mude a URL base para as APIs reais para um teste de fumaça (smoke test) ao vivo menor. Essa divisão; mocks determinísticos para a maior parte dos testes, uma verificação ao vivo mínima para a realidade; é o que torna o teste de IA agêntica prático em vez de aspiracional.

Um checklist para um agente confiável

• [ ] Cada ferramenta é definida como uma operação de API real com um esquema OpenAPI.
• [ ] Mocks existem para cada ferramenta para que você possa construir e testar offline.
• [ ] Cada endpoint de ferramenta possui asserções sobre status, esquema e tempo.
• [ ] Caminhos infelizes; argumentos ruins, erros, resultados vazios; são testados explicitamente.
• [ ] Tempos limite, retentativas com backoff e tratamento de limite de taxa estão no código e são testados.
• [ ] Uma execução de CI de ponta a ponta exercita o loop completo contra mocks determinísticos.

Acerte todos os seis e você terá um agente cuja confiabilidade pode ser descrita com evidências, não com esperança.

FAQ

Por que usar um cliente de API para testar um agente em vez de apenas executar o agente? Executar o agente testa o modelo e as ferramentas juntos, então uma falha é ambígua. Testar cada endpoint de ferramenta no Apidog isola a camada de API, para que você saiba se um problema é o raciocínio do modelo ou uma ferramenta quebrada.

Preciso construir as APIs reais antes de construir o agente? Não. Defina os contratos das ferramentas como esquemas no Apidog, gere mocks e construa todo o loop do agente contra esses mocks. Troque para endpoints reais mais tarde via uma variável de ambiente.

Como faço para evitar que meu agente entre em um loop infinito em uma ferramenta com falha? Limite as retentativas, adicione backoff e acione um disjuntor após falhas repetidas para que o agente relate o problema em vez de ficar girando. Teste cada controle contra um mock que retorna erros.

Posso testar o agente sem gastar dinheiro com chamadas de modelo e API? Em grande parte, sim. Faça mock das APIs da ferramenta no Apidog para testes de integração determinísticos e gratuitos, e mantenha as chamadas de modelo ao vivo em um pequeno conjunto de testes de fumaça (smoke test).

Isso funciona com frameworks como LangChain ou o SDK do Agente Claude? Sim. A camada de ferramentas é apenas HTTP. Qualquer que seja o framework que impulsiona o loop, aponte suas chamadas de ferramenta para os mocks do Apidog para testes e para os endpoints reais para produção. Veja o guia do SDK de Código do Claude para um exemplo desse loop.

Concluindo

Um agente confiável não é um prompt mais inteligente; é uma camada de ferramenta testada. Defina suas ferramentas como operações de API reais, faça mock delas para que o desenvolvimento seja rápido e determinístico, faça asserções sobre cada formato de resposta e teste as falhas intencionalmente. O Apidog oferece um único lugar para você projetar esses endpoints, fazer mock deles e executá-los como um ambiente de teste, para que o comportamento do seu agente seja algo que você possa comprovar. Baixe o Apidog e construa o agente em que você pode realmente confiar em produção.