Observabilidade da API quando os agentes de IA são seus chamadores mais frequentes

O painel da API mostra um pico de tráfego de 4x às 3h. Nenhuma campanha de marketing. Nenhum lançamento de produto. Nenhuma notícia sobre hackers postar. Um agente de IA descobriu seus endpoints por meio do servidor MCP e começou a executar a segurança em várias etapas auditorias; Pesquisas de DNS, verificações de SSL, análise de cabeçalho, 15 endpoints em rajadas de 2 segundos, a cada 10 minutos.

Isso é normal agora. O Gartner projeta que 30% ou mais do crescimento da demanda de API virá de agentes com tecnologia LLM, 2026. Uma pesquisa da Cisco descobriu que 89% das organizações já monitoram o comportamento dos agentes na produção. O o trânsito está aqui. A questão é se a sua pilha de observabilidade pode dizer a diferença entre um humano desenvolvedor testando um endpoint e um agente executando um fluxo de trabalho de 12 etapas às 3 da manhã.

As ferramentas tradicionais de APM agregam métricas por endpoint. Eles te mostram isso /v1/dns/lookup tenho 500 solicitações na última hora, mas eles não dirão que 480 delas vieram de 40 execuções de agentes, cada uma ligando Pesquisa de DNS, verificação de SSL e análise de cabeçalho em uma sequência previsível. Esse ponto cego custa caro; você não pode definir limites de taxa apropriados, você não poderá depurar falhas de agente e não poderá prever custos de infraestrutura.

Cinco padrões corrigem isso. Cada um aborda uma lacuna específica entre o que o APM padrão oferece e o que você precisa quando os agentes são seus clientes mais frequentes.

Por que o APM tradicional perde o tráfego do agente

Um desenvolvedor humano chama um endpoint, lê a resposta e talvez liga para outro alguns minutos depois. Um agente de IA chama de 5 a 15 endpoints em rápida sucessão, analisa cada resposta programaticamente e tenta novamente em caso de falha e passa para o próximo fluxo de trabalho. Essas duas formas de tráfego parecem idênticas por endpoint nível, mas se comportam de maneira diferente em todos os aspectos que são importantes para as operações.

Datadog, New Relic e Grafana mostram percentis de latência e taxas de erro por endpoint. Eles não mostre a você "a execução do agente #a3f7 chamou 8 ferramentas em sequência, falhou na ferramenta 6, tentou novamente 4 vezes e queimou através de 35 chamadas de API para concluir uma tarefa que deveria levar 8." Você precisa de rastreamento específico para isso.

Padrão 1: detectar chamadores de agentes

Antes de poder observar o tráfego do agente, você precisa identificá-lo. Três sinais funcionam juntos: Strings de agente de usuário, cadência de solicitação e cabeçalhos explícitos.

Correspondência usuário-agente

As estruturas de agente definem strings User-Agent identificáveis. LangChain, CrewAI, AutoGen e o Anthropic SDK todos incluem nomes de estruturas em seus cabeçalhos padrão. Solicitações geradas pelo SDK de bibliotecas como axios, node-fetch, e python-requests também sinaliza não-navegador tráfego.

Solicitar detecção de cadência

Os humanos não ligam para 4 endpoints diferentes em 5 segundos. Um detector de cadência do lado do servidor sinaliza clientes que atingiram vários endpoints exclusivos em uma janela curta:

Middleware de detecção completa

Combine os dois sinais em um middleware que marque cada solicitação como agente ou humano. Essa tag flui para suas camadas de registro, métricas e limitação de taxa:

O X-Agent-Detected cabeçalho de resposta permite que os desenvolvedores de agentes confirmem que suas solicitações são sendo classificado corretamente. Os níveis de confiança influenciam suas regras de alerta; uma confiança "alta" a detecção (cabeçalho explícito) é definitiva, enquanto "médio" (correspondência UA) pode precisar de confirmação de cadência.

Padrão 2: rastrear cadeias de múltiplas ferramentas com OpenTelemetry

Um agente ligando para o servidor MCP do botoi para auditar um domínio atingirá /v1/dns/lookup, então /v1/ssl-cert/certificate, então /v1/headers em segundos. Em padrão APM, estas são três solicitações separadas e não relacionadas. Com um compartilhado X-Agent-Run-ID cabeçalho e extensões OpenTelemetry, eles se tornam um fluxo de trabalho rastreável.

Cada fluxo de trabalho do agente obtém um intervalo pai. Cada chamada de ferramenta se torna um intervalo filho aninhado abaixo dela. Em Jaeger, Grafana Tempo ou qualquer back-end compatível com OTEL, você vê a cadeia completa: a pesquisa de DNS levou 45 ms, A verificação SSL levou 120 ms, os cabeçalhos levaram 30 ms e o tempo total do fluxo de trabalho foi de 210 ms. Quando a ferramenta 6 de 8 falha e o Se o agente tentar novamente 4 vezes, você o verá no rastreamento em vez de procurar em logs de endpoint separados.

Padrão 3: limite de taxa para cargas de trabalho intermitentes

A limitação de taxa de janela fixa pune os agentes. Um agente envia 15 solicitações em 2 segundos para concluir uma fluxo de trabalho e fica em silêncio por 58 segundos. Uma janela fixa de “60 solicitações por minuto” tem bastante de sala, mas uma janela fixa de "5 solicitações por 5 segundos" bloqueia o agente na solicitação 6, mesmo embora a taxa sustentada esteja bem abaixo do limite.

O balde de token resolve isso. A capacidade do bucket controla o tamanho do burst (quantas solicitações um agente pode dispara em uma rajada) e a taxa de recarga controla o rendimento sustentado (a rapidez com que o balde se recupera). Dois parâmetros que mapeiam como os agentes funcionam.

O principal insight: os agentes precisam de uma capacidade de intermitência maior e de uma taxa sustentada comparável. Um usuário humano com um balde de 5 tokens e taxa de recarga de 0,5 tokens/segundo pode fazer 5 solicitações rápidas e depois uma a cada 2 segundos. Um agente com um bucket de 20 tokens e recarga de 2 tokens/segundo pode disparar um fluxo de trabalho de 15 endpoints de uma só vez e recarregue o balde para a próxima execução 10 segundos depois.

É assim que a API do botoi lida com o tráfego misto. Solicitações anônimas (sem chave de API) obtêm uma explosão de 5 req/min com limite de 100 req/dia, rastreado por IP. Solicitações autenticadas em planos pagos usam o token bucket da Unkey na borda com maior explosão e limites sustentados por camada.

Padrão 4: contexto de uso da ferramenta de log com cabeçalhos de correlação

Um pedido para /v1/dns/lookup isoladamente não diz nada sobre a intenção. O mesmo pedido que a etapa 1 de uma auditoria de segurança em 8 etapas conta tudo. Os cabeçalhos de correlação preenchem essa lacuna.

Dois cabeçalhos carregam todo o contexto que você precisa:

• X-Agent-Run-ID: um UUID que agrupa todas as solicitações em um único fluxo de trabalho
• X-Agent-Tool-Index: a posição desta chamada na cadeia de ferramentas (1, 2, 3...)

No lado do cliente, o agente anexa ambos os cabeçalhos a cada solicitação em um fluxo de trabalho:

No lado do servidor, você registra os dois cabeçalhos em cada solicitação. Reconstruir o que um agente fez torna-se uma única consulta: "mostre-me todas as solicitações com X-Agent-Run-ID = abc-123 ordenado por X-Agent-Tool-Index." Sem correlação de carimbo de data/hora, sem correspondência de IP, sem suposições.

Se seus agentes usam o servidor MCP do botoi, o protocolo MCP já agrupa chamadas de ferramenta em sessões. O Servidor MCP em api.botoi.com/mcp encaminha a chave de API por meio de cabeçalhos e você pode estender para passar um ID de execução que persista em todas as 49 ferramentas disponíveis.

Padrão 5: alerta sobre anomalias específicas do agente

Alertas padrão são acionados com base em taxas de erro HTTP e percentis de latência. Alertas específicos do agente são acionados padrões comportamentais que indicam que algo está errado com o próprio agente, não com sua API.

Três tipos de alerta detectam as falhas mais comuns do agente:

• Ordem inesperada da ferramenta: um agente chamado verificação de SSL antes da pesquisa de DNS, sugerindo um bug lógico na etapa de planejamento do agente
• Loop de nova tentativa detectado: o mesmo endpoint foi atingido 5 ou mais vezes em 10 segundos na execução de um agente, indicando que o agente não está lendo respostas de erro
• Aumento de custo: a execução de um agente excedeu 50 chamadas de API, o que significa que um loop ou alucinação está gerando um consumo descontrolado

O alerta de loop de nova tentativa é o sinal de valor mais alto. Um agente que recebe um erro 400 (entrada incorreta) e tenta novamente a mesma solicitação 20 vezes, ultrapassa os limites de taxa e não produz nenhuma saída útil. Pegando isso em segundos, em vez de minutos, economiza seu orçamento de infraestrutura e o orçamento do operador do agente Cota de API.

Juntando tudo: uma pilha de observabilidade para tráfego misto

Aqui está a pilha que cobre todos os cinco padrões:

Se você já executa o Datadog ou Grafana para sua API, não precisa substituí-los. Adicione o Camada de instrumentação OTEL na parte superior, canaliza rastreamentos marcados pelo agente para um painel dedicado e crie regras de alerta nos atributos específicos do agente. As métricas existentes por endpoint permanecem útil para monitoramento de infraestrutura. Os novos rastreamentos com reconhecimento de agente respondem às perguntas que você o engenheiro de plantão pergunta às 3 da manhã: "o que esse agente está fazendo, por que está tentando novamente e devo bloqueá-lo?"

Principais conclusões

• Detecte primeiro, observe depois. Marque cada solicitação como agente ou humano usando Padrões User-Agent, detecção de cadência e cabeçalhos explícitos. Tudo a jusante depende nesta classificação.
• Rastreie fluxos de trabalho, não endpoints. A unidade de trabalho de um agente é uma ferramenta multifuncional cadeia, nem uma única chamada de API. Os intervalos pai/filho do OpenTelemetry criam fluxos de trabalho de agentes objetos de primeira classe em seu back-end de rastreamento.
• Balde de token em janela fixa. Os agentes explodiram. O bucket de token acomoda rajadas ao mesmo tempo em que impõe limites sustentados. Combine a capacidade da caçamba com a cadeia de ferramentas mais longa esperada.
• Os cabeçalhos de correlação são baratos e poderosos. X-Agent-Run-ID e X-Agent-Tool-Index transforme logs de solicitação opacos em fluxos de trabalho de agente legíveis com uma única consulta ao banco de dados.
• Alerta sobre comportamento, não sobre volume. Loops de repetição, pedidos inesperados de ferramentas e a contagem de chamadas descontroladas detecta problemas reais antes que se tornem incidentes.

A API do Botoi lida com tráfego humano e de agente em mais de 150 endpoints e um servidor MCP de 49 ferramentas. Cada resposta inclui X-RateLimit cabeçalhos. Se você estiver criando um agente que ligue APIs externas, passe um X-Agent-Run-ID cabeçalho, respeite os cabeçalhos de limite de taxa e forneça ao seu provedor de API os sinais necessários para manter seu agente funcionando perfeitamente. Experimente o documentos de API interativos ou conecte seu assistente de IA através do Servidor MCP ver esses padrões na prática.