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 conversa de um-pra-um: eu digito, ele responde, fim. A interface reforça essa ilusão — é um prompt limpo, você pergunta, recebe uma resposta. Então por que minha cota da Zhipu acabava tão rápido? Por que às vezes ele travava em tarefas que pareciam pequenas?

A resposta veio quando fui debugar um RateLimit persistente e percebi que o número de requisições não batia com o que eu achava que estava gerando. Eu pedia uma coisa; a API recebia cinco. A diferença eram os subagentes — instâncias secundárias do modelo que o Claude Code dispara em paralelo, sem te avisar.

Esse artigo é o mapa do que descobri. Não é teoria; é o comportamento que medi observando os logs do LiteLLM. E entender isso mudou completamente como configuro o proxy.

O que são subagentes e quando disparam

O Claude Code age como um gerente. Quando você pede algo complexo — “analisa o projeto e vê onde dá pra otimizar a conexão de banco” — ele não faz tudo numa única requisição. Ele orquestra:

1. Pede a um subagente pra mapear os arquivos em src/db/.
2. Esse subagente lê os arquivos, extrai strings de conexão e métodos do ORM, devolve um resumo curto.
3. O agente principal recebe o resumo (não os arquivos inteiros) e elabora o plano final.

A LLM que executa o passo 2 é uma requisição totalmente nova à API. Você não vê isso na interface — vê só o resultado final. Mas a API sabe. E a cota também.

Isso não é defeito. É design: preserva a janela de contexto do agente principal (ele não precisa carregar 20 arquivos inteiros) e paraleliza trabalho mecânico. O problema é que, se você não sabe que isso existe, não consegue prever consumo nem diagnosticar travamento.

O modelo padrão: Haiku

A Anthropic projetou o Claude Code assumindo que você paga eles. Por padrão, o agente principal usa o modelo de ponta (Sonnet/Opus), mas delega as tarefas mecânicas dos subagentes pra um modelo menor e barato: o Haiku.

O Haiku é rápido e barato na Anthropic. É perfeito pra “lê esse arquivo e devolve o conteúdo sem formatação”. O design inteiro pressupõe esse gradiente — gerente caro, operário barato.

Onde isso quebra pra quem usa LiteLLM com Zhipu: você não tem um Haiku de verdade. Você tem que escolher qual modelo da Zhipu vai fazer esse papel. E aí a tentação é mapear tudo pro modelo mais caro (GLM-4-Plus, com Deep Thinking) — o que dispara inferências pesadas em paralelo, esgota cota e derruba o RateLimit. É exatamente a causa 2 dos crashes.

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

Tem um problema mais sutil que o custo. Ocorre quando o subagente não faz tarefa mecânica (ler arquivo e devolver texto), mas sim análise.

Imagine: o agente principal pede “lê o arquivo de rotas e me dá um resumo das vulnerabilidades de segurança”. Se o subagente roda um modelo fraco, o resumo de segurança volta incompleto ou alucinado. O agente principal recebe informação corrompida. E como a arquitetura confia cegamente no output do subagente, a solução final que chega em você é fundamentada em premissas falsas.

Isso é contaminação de pipeline: um trabalhador ruim no meio da linha de montagem estraga o produto final, por mais inteligente que seja o gerente. Você nunca vê o erro diretamente — só vê o resultado final que “parece certo” mas tem uma premissa podre dentro.

Eu só percebi isso quando um relatório de segurança do Claude Code listou “sem vulnerabilidades relevantes” num arquivo que eu sabia ter uma injeção de SQL óbvia. O subagente tinha resumido o arquivo e perdido o trecho crítico no caminho.

Como configurar no LiteLLM

Quando você intercepta o tráfego do Claude Code com LiteLLM, precisa mapear os aliases internos da Anthropic pra modelos reais. A tentação é ignorar o Haiku e mapear tudo pro modelo mais forte. Não faça isso — você paga em cota e em crashes.

O meio-termo seguro no 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 pra não esgotar cota nem derrubar concorrência — mas competentes o suficiente pra tarefas mecânicas e resumos não-críticos.

Exceção importante: quando a tarefa envolver auditoria de segurança ou análise que vai informing uma decisão séria, não terceirize pro subagente. Instrua explicitamente o Claude Code a ler os arquivos no agente principal: “Leia estes arquivos e analise você mesmo, não resuma.” Mais lento, mais caro, mas o resumo não passa por filtro intermediário.

Como eu detectei quantos subagentes rodavam

O LiteLLM loga cada requisição que passa por ele. Rodando o proxy com saída em arquivo (litellm --config config.yaml --port 4001 > /tmp/litellm.log 2>&1), dá pra ver em tempo real quantos requests saem por pergunta sua. Foi assim que descobri que “analisar uma pasta” virava 8 requisições, não 1. Sem esse log, eu estaria operando no escuro.

Se você usa o monitor de cota no terminal, a correlação é imediata: a cota desce em blocos, não aos poucos — cada bloco é um subagente terminando.

O que aprendi

A lição que sobrevive fora deste caso: toda abstração que esconde trabalho paralelo também esconde custo e falha. O Claude Code é elegante porque você não vê a orquestração — mas essa mesma invisibilidade é o que torna impossível diagnosticar “por que quebrou” sem ferramenta externa. A partir daí, sempre que uso uma ferramenta que depende de API, procuro o equivalente do /tmp/litellm.log: o lugar onde o trabalho invisível aparece. Sem isso, eu tô pilotando no escuro.

E o segundo aprendizado, mais específico de arquitetura de agentes: o modelo que resume é tão crítico quanto o modelo que decide. Um gerente brilhante com operário ruim produz resultado ruim — e você só percebe quando confia no resultado e ele quebra em produção. Resumo não é compressão inofensiva; é filtro com viés, e o viés pode te cegar pro erro que importava.