Meus agentes tinham 157 ferramentas e não chamavam nenhuma

O objetivo era simples: fazer os agentes citarem dados reais de forma nativa, em vez de apelar pro shell ou chutar. Todos os backends estavam conectados. Os agentes tinham 157 ferramentas à disposição. Usaram zero, e me disseram por quê: “a ferramenta não existe”, “o upstream não conectou”. Confiantes, detalhados e completamente errados.

Passei uma hora depurando uma ficção

1. Acreditei no agente. Por uma hora depurei o mundo que o agente descrevia. O agente é um narrador não confiável. Ele conta uma história, não um stack trace. A verdade estava no log de execução o tempo todo.
2. Culpei a quantidade de ferramentas. Assumi que 157 era demais e que a camada de busca estava se confundindo. As duas hipóteses pareciam certas até o log matar as duas. Cada “a ferramenta não existe” tinha uma causa real por baixo: uma race na descoberta, uma sessão que ainda não estava pronta, um schema incompatível.
3. Suspeitei do overhead de agregação. Errado também. Um backend quente responde um tools/list em uns dez milissegundos. A medição matou a teoria.

O cold spawn estourou a janela de descoberta

A latência era cold spawn. Cada sessão subia sete backends a frio, e isso custava entre quatro e vinte e sete segundos. A descoberta tinha uma janela curta, menos de um segundo, e o cold spawn passava direto por ela. O agente pedia as ferramentas antes que os backends pudessem responder, não recebia nada e narrava uma ficção sobre ferramentas ausentes.

A correção saiu de uma mudança de enquadramento: o que fica quente é a camada de dados, não o cliente efêmero. O cliente CLI é one-shot, não dá pra fazer pool do processo. Então coloquei um proxy persistente com cache na frente dos dados: uma sessão upstream quente, a listagem de ferramentas em cache, a descoberta de volta a uns cinquenta milissegundos, bem dentro da janela. O catálogo de admin continua como control plane, mas o tráfego quente parou de passar por ele. Control plane e data plane pedem velocidades diferentes, então separe os dois em vez de sacrificar um pelo outro. Esse proxy virou open-source: mcp-pooler, MIT.

Um hábito deixou a noite inteira limpa: reverter cedo e medir. Cada patch de teste entrava com backup e checksum, e saía antes do próximo, então produção continuou íntegra enquanto eu provava e matava hipóteses.

Lição

Quando um agente reporta uma falha, não depure o agente: leia o log de execução. O agente é o narrador; o log é a verdade. E a latência costuma se esconder uma camada abaixo de onde aparece: o sintoma era “sem ferramentas”, a causa era um cold start.