Subagentes invisíveis do Claude Code: o que roda por trás

O problema

Durante semanas eu usei o Claude Code achando que era uma simples conversa de um-para-um: eu digito no chat, ele me responde e pronto. A própria tela do programa reforça essa ideia — é um espaço limpo onde você faz uma pergunta e recebe uma resposta. Então por que a minha cota de uso da Zhipu (o limite do meu plano) acabava tão rápido? Por que às vezes ele travava em tarefas que pareciam pequenas e simples?

A resposta veio quando fui investigar o motivo de um erro de excesso de pedidos (o chamado RateLimit persistente). Percebi que a quantidade de chamadas que saíam do meu computador não batia com o que eu achava que estava pedindo. Eu pedia uma única coisa na tela; a API (o serviço que processa a IA nas nuvens) recebia cinco pedidos de uma vez. A diferença eram os subagentes — que funcionam como “ajudantes” ou instâncias secundárias da IA que o Claude Code dispara em segundo plano, sem te avisar.

Este artigo é o mapa do que descobri. Não é teoria; é o comportamento real que medi observando os logs (os registros de atividade) do LiteLLM (uma ferramenta que intercepta e organiza essa comunicação). E entender isso mudou completamente como eu configuro esse meu servidor intermediário (o proxy).

O que são subagentes e quando disparam

O Claude Code age como o gerente de uma equipe. Quando você pede algo complexo — como “analisa o projeto e vê onde dá pra otimizar a conexão de banco” — ele não tenta fazer tudo em uma única requisição. Ele organiza e divide a tarefa:

Pede a um subagente (um ajudante) para mapear os arquivos dentro da pasta src/db/.
Esse subagente lê os arquivos, extrai os dados de conexão e os métodos do ORM (a ferramenta que fala com o banco), e devolve apenas um resumo curto.
O agente principal (o gerente) recebe esse resumo (e não os arquivos inteiros) e elabora o plano final.

A IA que executa o passo 2 é uma requisição totalmente nova enviada para a API. Você não enxerga isso na tela — vê apenas o resultado final. Mas a API sabe disso. E a sua cota de uso também sente a diferença.

Isso não é um defeito. É o design do sistema: ele preserva a “janela de contexto” do agente principal (a memória de trabalho do gerente, para ele não precisar carregar 20 arquivos inteiros de uma vez) e faz o trabalho braçal em paralelo para ganhar tempo. O problema é que, se você não sabe que esses ajudantes existem, não consegue prever o consumo do seu plano nem descobrir o motivo de um travamento.

O modelo padrão: Haiku

A Anthropic (empresa criadora do Claude) projetou o Claude Code assumindo que você paga a assinatura diretamente a eles. Por padrão, o agente principal usa a IA mais avançada e cara (Sonnet/Opus), mas delega as tarefas braçais e mecânicas dos subagentes para um modelo menor e bem mais em conta: o Haiku.

O Haiku é rápido e barato na plataforma da Anthropic. É perfeito para tarefas simples como “lê esse arquivo e devolve o conteúdo sem formatação”. Todo o sistema foi desenhado pensado nessa divisão: gerente caro e inteligente, operário barato e rápido.

Onde isso quebra para quem usa o LiteLLM com o serviço da Zhipu: você não tem um modelo Haiku de verdade disponível lá. Você precisa escolher qual modelo da Zhipu vai fazer esse papel de operário. E aí a tentação é mandar tudo para o modelo mais caro e poderoso (o GLM-4-Plus, com raciocínio profundo / Deep Thinking) — o que dispara várias processamentos pesados em paralelo, esgota a sua cota rapidamente e derruba a conexão pelo limite de requisições. É exatamente a causa 2 dos crashes.

O risco que ninguém fala: contaminação de pipeline

Tem um problema ainda mais sutil do que o custo no bolso. Ele acontece quando o subagente não faz apenas uma tarefa mecânica (ler um arquivo e devolver o texto), mas precisa fazer uma análise.

Imagine a cena: o agente principal pede “lê o arquivo de rotas e me dá um resumo das vulnerabilidades de segurança”. Se esse subagente estiver rodando em uma IA mais fraca, o resumo de segurança pode voltar incompleto ou “alucinado” (quando a IA inventa uma resposta errada com convicção). O agente principal recebe essa informação já corrompida. E como a arquitetura confia cegamente no que o subagente respondeu, a solução final que chega para você é baseada em premissas falsas.

Isso é a contaminação de pipeline (ou contaminação da linha de montagem): um ajudante ruim no meio do processo estraga o produto final, por mais inteligente que seja o gerente no topo. Você nunca vê o erro acontecendo diretamente — só vê o resultado final que “parece certo”, mas traz uma falha grave escondida.

Eu só percebi isso quando um relatório de segurança do Claude Code listou “sem vulnerabilidades relevantes” em um arquivo no qual eu sabia que existia uma falha clássica de injeção de SQL óbvia. O subagente tinha resumido o arquivo e acabou perdendo o trecho crítico no meio do caminho.

Como configurar no LiteLLM

Quando você usa o LiteLLM para interceptar o tráfego do Claude Code, precisa associar os nomes internos (os apelidos ou aliases) da Anthropic com os modelos reais da API que você está contratando. A tentação é ignorar o Haiku e mapear tudo para o modelo mais forte. Não faça isso — você vai pagar caro com estouro de cota e travamentos do sistema.

O ponto de equilíbrio seguro no seu arquivo config.yaml:

model_list:
  # Agente principal — o "gerente". Pode ser o mais caro.
  - model_name: claude-sonnet-4-5
    litellm_params:
      model: openai/glm-4-plus
      api_base: https://open.bigmodel.cn/api/coding/paas/v4
      api_key: os.environ/ZHIPU_API_KEY

  # Subagentes (Haiku) — os "operários". Precisa ser leve.
  - model_name: claude-haiku-4-5
    litellm_params:
      model: openai/glm-4-airx   # rápido, sem Deep Thinking, limite paralelo alto
      api_base: https://open.bigmodel.cn/api/coding/paas/v4
      api_key: os.environ/ZHIPU_API_KEY

Com isso, os subagentes ficam leves o suficiente para não esgotar a cota nem estourar o limite de chamadas simultâneas — mas continuam competentes o bastante para tarefas mecânicas e resumos simples.

Exceção importante: quando a tarefa envolver auditoria de segurança ou uma análise crítica que vai orientar uma decisão séria, não terceirize para o subagente. Instrua explicitamente o Claude Code a ler os arquivos usando o agente principal: “Leia estes arquivos e analise você mesmo, não resuma.” O processo será mais lento e mais caro, mas o resumo não passará por um filtro intermediário.

Como eu detectei quantos subagentes rodavam

O LiteLLM gera um registro (log) de cada requisição que passa por ele. Rodando esse proxy com a saída gravada em um arquivo (litellm --config config.yaml --port 4001 > /tmp/litellm.log 2>&1), dá para acompanhar em tempo real quantas chamadas saem para cada pergunta enviada. Foi assim que descobri que um simples pedido para “analisar uma pasta” virava 8 requisições à API, e não apenas 1. Sem esse log, eu estaria tentando resolver o problema totalmente no escuro.

Se você usa o monitor de cota no terminal, a relação fica clara imediatamente: a cota cai em blocos de uma vez só, e não aos poucos — cada bloco desses representa um subagente terminando a tarefa dele.

O que aprendi

A lição principal que serve para qualquer projeto técnico é: toda facilidade que esconde o trabalho feito em paralelo também esconde o custo e as falhas. O Claude Code é prático de usar porque oculta essa organização — mas essa mesma invisibilidade torna impossível diagnosticar “por que travou” sem usar uma ferramenta externa de monitoramento. A partir disso, sempre que uso uma ferramenta baseada em API, busco o equivalente ao arquivo /tmp/litellm.log: o lugar onde o trabalho invisível finalmente aparece. Sem isso, estou pilotando no escuro.

E o segundo aprendizado, mais focado na estrutura de agentes de IA: o modelo que resume a informação é tão crítico quanto o modelo que toma a decisão. Um gerente brilhante trabalhando com um ajudante ruim vai entregar um resultado ruim — e você só percebe isso quando confia no resultado e ele quebra no sistema real (em produção). Fazer um resumo não é uma simples compressão sem perdas; é um filtro que escolhe o que mostrar, e esse filtro pode te deixar cego para o erro que realmente importava.