Um agente de IA é tão confiável quanto as APIs que ele chama. O modelo escolhe uma ferramenta, preenche argumentos e dispara uma requisição; se essa requisição falhar, retornar o formato errado ou travar, o agente pode tomar uma decisão confiante com dados ruins. Em produção, a confiabilidade do agente depende diretamente da confiabilidade da camada de ferramentas.
Este guia mostra como construir um agente que chama ferramentas reais e como usar o Apidog como camada de API e ambiente de teste. Você vai definir endpoints para ferramentas, criar mocks para desenvolver offline e adicionar asserções para detectar chamadas quebradas antes que elas cheguem ao usuário.
O que um agente realmente faz na camada de API
Um loop de agente normalmente segue este fluxo:
- O modelo recebe um objetivo do usuário e uma lista de ferramentas.
- Ele retorna uma chamada de ferramenta: nome da ferramenta + argumentos JSON.
- Seu código executa a chamada, geralmente via HTTP.
- O resultado volta para o modelo.
- O modelo chama outra ferramenta ou responde ao usuário.
Os problemas aparecem principalmente nas etapas 3 e 4:
- o modelo alucina um argumento;
- a API retorna
400,422,429ou500; - o esquema de resposta muda;
- a chamada excede o tempo limite;
- o agente continua tentando a mesma ferramenta com falha.
Se você já leu sobre agentes de IA como os novos consumidores de API, esta é a aplicação prática: seu agente é um cliente de API e precisa ser testado como qualquer outro cliente.
O trabalho se divide em duas partes:
- Definir ferramentas como operações de API reais e testáveis.
- Verificar se o agente chama essas ferramentas corretamente em cenários bons e ruins.
Passo 1: Projete as ferramentas como operações de API reais
Antes de escrever o loop do agente, defina cada ferramenta como um endpoint de API no Apidog.
Exemplo:
| Ferramenta | Endpoint |
|---|---|
get_weather |
GET /weather |
create_ticket |
POST /tickets |
search_customer |
GET /customers/search |
A ferramenta get_weather e o endpoint GET /weather devem compartilhar o mesmo contrato:
- mesmos parâmetros;
- mesmos tipos;
- mesmos campos obrigatórios;
- mesmo formato de resposta.
No Apidog, crie um endpoint para cada ferramenta com:
- parâmetros de path, query ou body;
- schema de request;
- schema de response;
- exemplos de resposta;
- códigos de erro esperados.
Isso oferece três vantagens práticas:
- uma única fonte da verdade para o contrato da ferramenta;
- documentação que pode ser usada como base para a definição enviada ao modelo;
- validação automática para detectar respostas fora do schema.
Esse fluxo schema-first é o mesmo usado em um bom processo de design de API. Para agentes, o benefício é direto: o modelo só deve chamar ferramentas que sua API realmente suporta.
Passo 2: Faça mock das ferramentas para desenvolver offline
Você não precisa chamar APIs reais em cada execução local. Isso evita:
- custo desnecessário;
- rate limits;
- dependência de serviços instáveis;
- bloqueio enquanto o backend ainda não está pronto.
Depois de definir os endpoints no Apidog, gere um servidor mock a partir do schema. Cada ferramenta passa a retornar dados válidos sem exigir backend real.
Com mocks, você pode:
- desenvolver o loop completo do agente antes da API existir;
- executar testes de integração em CI sem acessar endpoints pagos;
- simular respostas específicas, como resultado vazio, erro
500ou campo malformado; - validar como o agente reage a falhas.
Durante o desenvolvimento, aponte o executor de ferramentas para a URL base do mock:
TOOL_BASE_URL=https://mock.apidog.local
Em produção, troque apenas a variável:
TOOL_BASE_URL=https://api.suaempresa.com
O mocking torna o desenvolvimento de agentes mais rápido e determinístico. Essa mesma abordagem é útil em qualquer fluxo 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 pode ficar simples. O exemplo abaixo usa a API de Mensagens do Claude. A definição da ferramenta espelha o contrato criado no Apidog.
import os
import requests
import anthropic
client = anthropic.Anthropic()
# Mock do Apidog em desenvolvimento.
# API real em produção.
TOOL_BASE = os.environ["TOOL_BASE_URL"]
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":
response = requests.get(
f"{TOOL_BASE}/weather",
params={"city": args["city"]},
timeout=10,
)
response.raise_for_status()
return response.json()
raise ValueError(f"Unknown tool: {name}")
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 partes mais importantes não são a chamada ao modelo, mas estas linhas:
timeout=10
response.raise_for_status()
Elas impedem que o agente continue raciocinando sobre uma requisição travada ou uma resposta HTTP com erro.
Para fluxos mais amplos envolvendo agentes e APIs, veja também 5 agentes de IA para seu fluxo de trabalho de API.
Passo 4: Teste as chamadas das ferramentas, não apenas a resposta final
Não teste apenas se o agente "parece responder bem". Teste cada ferramenta isoladamente.
No Apidog, salve cada endpoint de ferramenta como uma requisição testável e adicione asserções.
Para entrada válida, verifique:
- status
200; - resposta compatível com o schema OpenAPI;
- campos obrigatórios presentes;
- tipos corretos;
- tempo de resposta dentro do limite usado pelo agente.
Exemplo de contrato esperado para GET /weather:
{
"city": "Tokyo",
"temperature": 24,
"condition": "cloudy",
"unit": "celsius"
}
Valide campos que o modelo realmente usará:
{
"required": ["city", "temperature", "condition", "unit"]
}
Depois, teste os caminhos de falha:
-
cityvazia; - número no lugar de string;
- parâmetro ausente;
- resposta
500; - resultado vazio;
- payload fora do schema.
Exemplo de entrada inválida:
GET /weather?city=
Resultado esperado:
HTTP/1.1 422 Unprocessable Entity
Com corpo previsível:
{
"error": "city is required"
}
O objetivo é garantir que a API retorne um erro limpo, e não um 500 genérico.
Isso é teste de contrato aplicado a ferramentas de agente. A mesma disciplina usada em teste de contrato de API vale para qualquer endpoint que o modelo possa chamar.
Passo 5: Trate retentativas, timeouts e rate limits
Agentes podem amplificar problemas de API. Uma falha transitória pode virar várias chamadas repetidas dentro do loop.
Implemente controles explícitos.
Timeout
Toda chamada de ferramenta deve ter timeout:
requests.get(url, timeout=10)
Depois, simule um endpoint lento no Apidog e confirme que o agente falha de forma controlada.
Retentativas com backoff
Tente novamente apenas falhas transitórias, como 502, 503 ou timeout.
Exemplo simples:
import time
import requests
def get_with_retry(url, params, retries=3):
for attempt in range(retries):
try:
response = requests.get(url, params=params, timeout=10)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException:
if attempt == retries - 1:
raise
sleep_seconds = 2 ** attempt
time.sleep(sleep_seconds)
Teste contra um mock que:
- falha na primeira chamada;
- falha na segunda;
- retorna sucesso na terceira.
O teste deve confirmar que o agente se recupera sem entrar em loop infinito.
Rate limits
Espere respostas 429 em cenários de carga.
Faça mock de uma resposta como:
HTTP/1.1 429 Too Many Requests
Retry-After: 10
E confirme que o agente respeita a espera antes de tentar novamente.
Se você já lidou com limites em APIs de modelo, veja limites de taxa da API GPT. Em agentes, o impacto é maior porque o loop pode multiplicar chamadas.
Circuit breaker
Depois de N falhas consecutivas, pare de chamar a ferramenta.
Exemplo de comportamento esperado:
get_weather falhou 3 vezes.
Circuit breaker aberto.
Responder ao usuário informando indisponibilidade temporária.
Teste esse cenário com um mock que sempre retorna 500.
Passo 6: Execute testes ponta a ponta contra mocks em CI
Depois de testar cada ferramenta isoladamente, teste o loop completo do agente.
Em CI:
- configure
TOOL_BASE_URLpara o servidor mock do Apidog; - envie objetivos fixos ao agente;
- registre quais ferramentas foram chamadas;
- valide a resposta final;
- valide a sequência de chamadas.
Exemplo de caso de teste:
Entrada:
"What should I wear in Tokyo today?"
Sequência esperada:
1. get_weather({ "city": "Tokyo" })
Resposta esperada:
Recomendação baseada no clima retornado pelo mock.
Como os mocks são determinísticos, a mesma entrada deve produzir o mesmo comportamento.
Depois, mantenha um teste de fumaça menor contra APIs reais:
- poucos casos;
- baixa frequência;
- foco em validar integração real;
- sem substituir os testes determinísticos com mocks.
Essa separação — mocks para a maior parte dos testes e smoke tests reais para validação final — torna o teste de IA agêntica prático.
Checklist para um agente confiável
Use este checklist antes de colocar o agente em produção:
- [ ] Cada ferramenta é uma operação de API real com schema OpenAPI.
- [ ] Cada ferramenta tem mock configurado.
- [ ] O agente usa variável de ambiente para alternar entre mock e produção.
- [ ] Cada endpoint tem testes de status, schema e tempo de resposta.
- [ ] Entradas inválidas retornam
400ou422, não500. - [ ] Resultados vazios são tratados explicitamente.
- [ ] Timeouts estão configurados em todas as chamadas.
- [ ] Retentativas têm limite e backoff.
- [ ] Rate limits
429são tratados. - [ ] Circuit breaker impede loops infinitos.
- [ ] O CI executa testes ponta a ponta contra mocks determinísticos.
- [ ] Um conjunto pequeno de smoke tests valida APIs reais.
Se todos esses itens estiverem cobertos, você consegue discutir confiabilidade com evidências, não com suposições.
FAQ
Por que usar um cliente de API para testar um agente em vez de apenas executar o agente?
Porque executar o agente testa modelo e ferramentas ao mesmo tempo. Quando algo falha, a causa fica ambígua. Testar cada endpoint no Apidog isola a camada de API e mostra se o problema está na ferramenta ou no raciocínio do modelo.
Preciso construir as APIs reais antes de construir o agente?
Não. Defina os contratos das ferramentas no Apidog, gere mocks e desenvolva o loop do agente contra esses mocks. Depois, troque para os endpoints reais via variável de ambiente.
Como evito que o agente entre em loop infinito em uma ferramenta com falha?
Use timeout, limite de retentativas, backoff e circuit breaker. Depois, teste esses controles contra mocks que retornam erro ou demoram para responder.
Posso testar o agente sem gastar com chamadas de modelo e API?
Em grande parte, sim. Faça mock das APIs das ferramentas no Apidog para testes de integração determinísticos. Mantenha chamadas reais de modelo e API apenas em um conjunto pequeno de smoke tests.
Isso funciona com LangChain ou SDKs de agentes?
Sim. A camada de ferramentas é apenas HTTP. O framework pode ser LangChain, SDK do Claude ou outro loop próprio. Aponte as chamadas para mocks do Apidog em testes e para endpoints reais em produção. Veja o guia do SDK de Código do Claude para um exemplo relacionado.
Concluindo
Um agente confiável não depende apenas de um prompt melhor. Ele depende de uma camada de ferramentas testada.
Defina cada ferramenta como uma operação de API real, gere mocks, valide respostas com schema, teste falhas intencionalmente e execute o loop completo em CI. O Apidog centraliza o design, o mock e os testes dessas APIs, permitindo que você comprove o comportamento do agente antes de colocá-lo em produção.
Top comments (0)