Agente de IA: Rastreamento de Chamadas de Ferramentas

Um usuário relata que o agente “fez algo estranho” ontem à tarde. Você abre os logs e encontra isto:

INFO  agent run started
INFO  calling tool: updateOrder
INFO  tool returned 200
INFO  agent run completed

O agente chamou updateOrder. Você não sabe com quais argumentos, para qual pedido, por que ele escolheu essa ferramenta, ou o que retornou. A execução foi bem-sucedida por todas as medidas que você registrou, e você não consegue reconstruir uma única decisão que ele tomou.

Sistemas de agentes falham de maneiras que só fazem sentido em retrospectiva, o que significa que o log é o produto. Este guia aborda o que registrar em cada chamada de ferramenta, como correlacionar uma decisão do modelo com a requisição HTTP que ele produziu, o que redigir e como transformar rastreamentos em testes. Nosso post sobre observabilidade de API cobre o lado do serviço; este cobre a camada do agente que fica por cima.

Apidog é útil quando você tem um rastreamento, porque a maneira mais rápida de entender uma chamada ruim é reproduzi-la contra o mesmo endpoint e observar o que acontece.

Três camadas, um rastreamento

Um agente produz eventos em três níveis, e a maioria das equipes registra apenas o do meio.

A **camada de raciocínio** é onde o modelo decide. O que estava em contexto, quais ferramentas foram oferecidas, qual ele escolheu e com quais argumentos.

A **camada de ferramenta** é o seu executor. Ele valida argumentos, aplica políticas, mapeia a chamada para uma requisição HTTP e lida com o resultado.

A **camada HTTP** é a rede. Método, URL, cabeçalhos, corpo, status, latência.

A depuração quase sempre cruza camadas. “O agente enviou o ID do cliente errado” é um problema de raciocínio visível apenas na camada HTTP. “A API retornou um 200 com um corpo vazio” é um problema HTTP que aparece como um raciocínio estranho três passos depois. Se as três camadas não estiverem interligadas por um identificador compartilhado, você ficará preso correlacionando por timestamp, o que para de funcionar no momento em que duas execuções se sobrepõem.

Então a primeira regra: um ID de rastreamento por execução do agente, um ID de span por chamada de ferramenta, e ambos carimbados em cada registro em cada camada. Os rastreamentos do OpenTelemetry já modelam exatamente este formato, e há um conjunto crescente de convenções semânticas de GenAI para nomear os atributos, de modo que seus dados sejam portáteis.

O que registrar em cada chamada de ferramenta

Um registro que responde a perguntas reais tem aproximadamente este formato:

{
  "trace_id": "run_01J8ZK3M2Q",
  "span_id": "call_004",
  "parent_span_id": "call_003",
  "timestamp": "2026-08-26T14:03:11.482Z",
  "agent": "billing",
  "step": 4,

  "tool_name": "refundOrder",
  "tool_args": { "orderId": "ord_92", "amount": 1200, "reason": "duplicate" },
  "tools_available": ["getOrder", "listOrders", "refundOrder", "voidInvoice"],

  "http": {
    "method": "POST",
    "url": "/v1/orders/ord_92/refund",
    "request_body_hash": "sha256:1f4c...",
    "status": 200,
    "duration_ms": 412,
    "retry_count": 1,
    "idempotency_key": "9f2b7c14-6d3a-4b18"
  },

  "outcome": "success",
  "tokens": { "prompt": 8420, "completion": 96 },
  "policy": { "approval_required": true, "approved_by": "user_31", "dry_run": false }
}

Cinco campos realizam um trabalho desproporcional.

tool_args é o que mais frequentemente falta, e é o que você sempre quer. Registre os argumentos produzidos pelo modelo, antes que seu executor os normalize. Quando um agente envia o ID errado, é aqui que isso é visível.

tools_available explica a seleção. Se o modelo escolheu uma ferramenta estranha, a primeira pergunta é o que mais ele tinha para escolher. Este campo custa alguns bytes e responde instantaneamente.

retry_count separa “a API estava lenta” de “a API falhou duas vezes e depois funcionou”. Sem ele, três tentativas parecem uma única chamada.

outcome deve ser um enum explícito, não algo inferido de um código de status. success (sucesso), failed (falha), timed_out (tempo esgotado), blocked_by_policy (bloqueado por política), rejected_by_human (rejeitado por humano). Os dois últimos são importantes porque uma chamada bloqueada é um mecanismo de segurança funcionando, não um erro, e misturá-los corrompe sua taxa de falha.

policy é sua trilha de auditoria. Quando alguém pergunta se uma ação destrutiva foi aprovada, esta é a resposta. Ele se associa à aplicação descrita em nosso post sobre mecanismos de segurança para agentes de IA.

Registre a decisão, não apenas a ação

Os bugs de agente mais difíceis são escolhas, então registre o suficiente para reconstruí-las.

Mantenha as definições de ferramenta usadas para a execução, ou um hash delas. Quando a precisão da seleção muda, o primeiro suspeito é uma descrição que alguém editou, e um hash informa imediatamente se o conjunto de ferramentas mudou entre uma execução boa e uma ruim. Nosso post sobre design de esquemas de ferramentas cobre por que esse texto altera tanto o comportamento.

Registre o modelo e suas configurações. ID do modelo, temperatura e versão do prompt pertencem ao registro da execução. O comportamento muda entre as versões do modelo, e sem este campo você passará um dia investigando seu próprio código.

Registre o que o modelo viu, ou pelo menos seu tamanho. Um despejo completo do prompt é caro para armazenar e muitas vezes sensível. Uma contagem de tokens mais um hash oferece a maior parte do valor de diagnóstico: uma execução cujo prompt é o dobro do tamanho usual é uma execução onde algo foi anexado que não deveria ter sido.

Registre o resultado bruto da ferramenta antes de aparar. Se o seu executor projeta respostas para baixo antes de entregá-las ao modelo, como em nosso post sobre manter as respostas da ferramenta fora da janela de contexto, armazene a carga útil completa no rastreamento. Caso contrário, você não poderá dizer se os dados estavam faltando ou se você os descartou.

Redija antes de armazenar

Rastreamentos de agentes são incomumente perigosos porque contêm tanto a requisição quanto o raciocínio em torno dela, e os prompts têm o hábito de coletar dados pessoais.

Quatro regras tornam isso gerenciável.

Nunca armazene credenciais. Remova Authorization, chaves de API, cookies e qualquer URL assinado. Registre o identificador da credencial, como um ID de chave, e não o valor. Nosso post sobre chaves de API de privilégio mínimo para agentes aborda por que você quer esse identificador: ele informa qual agente agiu.

Redija na fronteira, não na consulta. Filtrar no momento da leitura significa que o segredo foi gravado em disco, replicado e copiado. Redija no middleware de logging antes que o registro saia do processo.

Faça hash de corpos que você não pode armazenar. Um hash do corpo da requisição ainda permite provar que duas chamadas foram idênticas, o que é a maior parte do que você precisa para investigações de duplicatas, sem manter a carga útil.

Defina a retenção por sensibilidade. Rastreamentos completos por uma semana, resumos redigidos por um ano. A maioria das depurações acontece em dias; a maioria das perguntas de auditoria chega em meses.

Transforme rastreamentos em testes

A recompensa de um bom rastreamento não é apenas uma depuração mais rápida. É um suprimento de casos de teste realistas.

Cada execução falha é um cenário. Pegue as chamadas de ferramenta de um rastreamento ruim, reproduza-as contra sua API, e você terá uma reprodução. Quando a correção for implementada, mantenha a reprodução como um teste de regressão. No Apidog você pode recriar a requisição falha como um caso salvo, afirmar o comportamento corrigido e executá-lo na CI, que é como um incidente pontual se transforma em cobertura permanente.

Rastreamentos também informam o que simular. Os endpoints que seu agente mais chama, e os status de falha que ele realmente encontra, vêm diretamente dos dados em vez de suposições. Construa os mocks em torno deles, seguindo nosso post sobre executar agentes contra mocks em vez de produção.

E eles revelam a lenta deriva que você de outra forma perderia. Acompanhe alguns números por semana: distribuição de seleção de ferramentas, taxa de repetição por endpoint, chamadas por tarefa concluída e a porcentagem de execuções bloqueadas por política. Uma mudança em qualquer um deles é um sinal antes que se torne um incidente. Verificações em nível de contrato, como em nosso guia de teste de contrato de API, capturam a mudança upstream que geralmente a causou.

Três investigações que o rastreamento precisa suportar

**“O agente cobrou o cliente errado.”** Você precisa dos argumentos que o modelo produziu, da URL resolvida e do passo anterior. Nove de dez vezes o ID veio de um resultado de ferramenta anterior que retornou mais de uma correspondência e o modelo escolheu a primeira. O rastreamento mostra o resultado anterior, a ambiguidade e a escolha. Sem tool_args você tem um 200 e um cliente muito insatisfeito.

**“Parou de funcionar na terça-feira.”** Compare uma execução boa e uma execução ruim campo por campo. ID do modelo, hash do conjunto de ferramentas, versão do prompt, tamanho médio da resposta. Algo mudou, e um desses quatro geralmente o nomeia. É por isso que o registro da execução carrega a configuração e não apenas eventos: uma diferença só é possível quando ambos os lados registraram os mesmos campos.

**“Alguém aprovou isso?”** O bloco de política é a resposta completa, e precisa ser escrito no momento da decisão, não reconstruído depois. approval_required (aprovação_requerida), approved_by (aprovado_por) e um timestamp transformam uma conversa tensa em uma consulta.

Observe o que eles têm em comum. Nenhum deles é respondido por “a ferramenta retornou 200”. Todos os três são respondidos por campos que custam quase nada para escrever e são impossíveis de recuperar depois do fato.

Amostragem, e o que nunca amostrar

Rastreamento de fidelidade total em cada execução se torna caro em volume, então as equipes fazem amostragem. Amostre com cuidado, porque o tráfego do agente não é uniforme.

Sempre mantenha cada execução falha, cada execução que atingiu um bloqueio de política e cada execução que contém uma escrita. Essas são as execuções sobre as quais qualquer um perguntará. Amostre as execuções bem-sucedidas somente leitura, pois elas são a maior parte do volume e as menos interessantes individualmente, embora você ainda queira o suficiente delas para calcular seus baselines.

O capítulo do livro de SRE do Google sobre monitoramento de sistemas distribuídos ainda é a declaração mais clara de por que você amostra por sinal em vez de por volume, e o raciocínio se aplica diretamente.

Mantenha o registro da execução mesmo quando você descarta as cargas úteis. Um rastreamento esqueleto com nomes de ferramentas, resultados e durações é pequeno e ainda suporta as quatro métricas acima. As partes caras são os corpos e os prompts, e essas são as partes que você pode descartar primeiro.

Um aviso sobre amostragem de cauda: se você decidir o que manter depois que uma execução termina, certifique-se de que a decisão ocorra depois que o resultado for conhecido. Uma execução que parece boa na etapa três e falha na etapa nove precisa ser retida na íntegra, o que significa armazenar em buffer em vez de descartar à medida que avança.

Onde o rastreamento deve residir

Tudo acima assume que você é o proprietário do armazenamento. Essa é a suposição correta quando o agente é seu próprio serviço chamando suas próprias APIs. É uma má adequação quando os agentes são tempos de execução de codificação em máquinas de desenvolvedores, porque o rastreamento então reside em qualquer terminal que o executou.

Sharkly adota a outra abordagem: o rastreamento de execução é anexado à Tarefa atribuída ao agente. O histórico de execução, o log de execução e o resultado ficam ao lado do objetivo, do status e do thread de comentários onde um humano revisou o trabalho. A diferença prática é a recuperação. “Por que o agente fez isso” se torna uma pergunta que você responde abrindo a tarefa, em vez de encontrar a máquina, a sessão e o histórico.

Isso não substitui o rastreamento descrito aqui, e também não substitui o tempo de execução; Claude Code e Codex ainda fazem o trabalho. O que muda é onde o registro vai parar quando o agente não é um serviço que você implantou.

Monitore quatro números

Rastreamentos só são úteis se alguém os examinar. Estes quatro merecem seu lugar em um painel.

**Chamadas por tarefa concluída.** A medida de eficiência mais clara. Se ela aumentar, o agente está explorando mais, geralmente porque uma descrição piorou ou um endpoint começou a falhar.
**Taxa de repetição por endpoint.** Classifica suas dependências menos confiáveis e mostra quando uma delas se degrada. Nosso post sobre recuperação de erros do agente aborda o que fazer em relação ao topo dessa lista.
**Taxa de bloqueio por política.** Deve ser baixa e estável. Um pico significa que o agente está tentando coisas que não deveria, ou que uma política é muito rígida e agora é o gargalo.
**Tempo até a primeira chamada de ferramenta.** Um início lento geralmente significa um prompt inchado, e o tamanho do prompt é algo que cresce sem que ninguém decida aumentá-lo.

Uma lista de verificação

Um ID de rastreamento por execução, um ID de span por chamada de ferramenta, carimbado em todas as três camadas.
Argumentos do modelo registrados antes da normalização.
A lista de ferramentas disponíveis registrada em cada chamada.
Resultado registrado como um enum explícito, incluindo bloqueios de política.
Contagem de repetições separada da contagem de chamadas.
Modelo, temperatura, versão do prompt e hash do conjunto de ferramentas no registro da execução.
Resultados brutos da ferramenta armazenados, não apenas a versão aparada entregue ao modelo.
Credenciais removidas no middleware, corpos com hash onde não podem ser armazenados.
Retenção escalonada por sensibilidade.
Rastreamentos falhos convertíveis em casos de teste reproduzíveis.

O objetivo é simples de declarar: quando alguém pergunta por que o agente fez isso, você pode responder a partir do registro em vez de um palpite. Baixe o Apidog para reproduzir as chamadas em um rastreamento e manter as reproduções como testes.

Perguntas frequentes

**Devo usar OpenTelemetry ou uma ferramenta de observabilidade de agente específica?** Use OpenTelemetry para o transporte e o modelo de rastreamento, já que ele já lida com a correlação e sua infraestrutura provavelmente o "fala". Ferramentas específicas de agente adicionam visualizações úteis por cima; os dados subjacentes ainda devem ser portáteis.
**Quanto custa armazenar o rastreamento completo?** Menos do que as pessoas esperam, se você o escalonar. Cargas úteis completas por alguns dias e registros estruturados sem corpos por mais tempo mantêm a maior parte do volume baixo. Despejos de prompt são a parte cara, então faça hash e dimensione-os em vez de armazená-los por padrão.
**Preciso registrar o texto de raciocínio do modelo?** Geralmente não. A ferramenta que ele escolheu, os argumentos que produziu e as opções que tinha explicam a maioria das decisões. Onde um provedor expõe conteúdo de raciocínio, armazene-o apenas para execuções falhas e trate-o como sensível.
**Como faço para rastrear vários agentes?** Mantenha um ID de rastreamento para toda a tarefa e dê a cada agente seu próprio span, com a passagem registrada como um evento. Nosso post sobre passagem de contexto entre múltiplos agentes aborda o que pertence a esse registro de passagem.
**E se o agente rodar na máquina de um cliente?** Registre localmente, redija agressivamente e envie apenas métricas agregadas, a menos que o usuário opte por isso. Nomes de ferramentas, resultados e durações geralmente são suficientes para monitoramento em nível de frota sem que nenhuma carga útil saia do dispositivo.
**Um hash do corpo da requisição é realmente útil?** Sim, para as perguntas mais comuns. Ele prova que duas chamadas foram idênticas, o que resolve a maioria das investigações de escrita duplicada, sem manter o próprio payload. Combine-o com as chaves de idempotência que deveriam ter evitado a duplicata.