Os agentes invisíveis do Claude Code: o que são, riscos e como controlá-los

A interface principal do Claude Code é limpa e simples: você digita uma requisição e ele te responde. Mas, por trás dessa aparente simplicidade, o sistema atua como um gerente distribuindo tarefas para subordinados invisíveis.

Estes subordinados são os Subagentes. O Claude Code usa instâncias secundárias e concorrentes do LLM para tarefas periféricas e investigativas, permitindo que o modelo principal da sua sessão não perca o foco (nem o limite de janela de contexto) com coisas triviais.

Mas delegar às cegas para instâncias invisíveis traz sérios riscos — de performance, financeiros e até de degradação da qualidade do seu código.

Como os Subagentes atuam?

Se você pede ao Claude: “Dê uma olhada no projeto e veja onde posso otimizar a conexão de banco de dados”, o agente principal pode orquestrar o seguinte fluxo:

1. Pede a um subagente para mapear os arquivos na pasta src/db/.
2. O subagente lê os arquivos, extrai as strings de conexão e os métodos de ORM, e devolve um resumo curto ao agente principal.
3. O agente principal analisa o resumo gerado e elabora o plano final.

Neste fluxo, a LLM que executa o passo 2 é uma requisição totalmente nova à API.

O Modelo Padrão: Haiku

A Anthropic projetou o Claude Code assumindo que você está pagando a eles. Por padrão, o agente principal sempre tenta usar o modelo de ponta (Claude 3.5 Sonnet ou Opus), mas delega tarefas mecânicas dos subagentes para o Claude 3.5 Haiku.

O Haiku é extremamente rápido e muito barato na Anthropic. E ele é perfeito para tarefas objetivas (leia o arquivo e retorne o conteúdo sem formatação).

O Risco da Contaminação do Trabalho Principal

O problema surge quando o subagente não executa uma tarefa puramente mecânica (como ler o conteúdo de um arquivo), mas sim uma análise analítica.

Imagine que o agente principal peça a um subagente: “Leia o arquivo de rotas e me dê um resumo das vulnerabilidades de segurança encontradas.”

Se o subagente estiver configurado para rodar um modelo fraco, “burro”, ou que alucina demais, o resumo de segurança devolvido será incompleto ou falho. O agente principal receberá a informação corrompida. Como a arquitetura confia cegamente no output do subagente, a solução final entregue a você será fundamentada em premissas falsas.

Esse é o fenômeno da “contaminação da pipeline”. Um trabalhador ruim no meio da linha de montagem estraga o produto final, por mais inteligente que seja o gerente da linha.

Como configurar via LiteLLM?

Quando você intercepta o tráfego do Claude Code com LiteLLM para rotear para a Zhipu ou DeepSeek, você precisa mapear os aliases internos da Anthropic.

Se você ignorar os subagentes e rotear tudo (claude-sonnet, claude-opus, claude-haiku) para o seu modelo mais parrudo e caro (ex: GLM-4-Plus), você vai esgotar rapidamente sua cota, sua taxa de limites paralelos e causar os infames RateLimits e Crashes detalhados no nosso outro artigo.

A solução segura é um meio-termo na sua infraestrutura do config.yaml do LiteLLM:

  # Agente Principal - O "Gerente" Brilhante
  - model_name: claude-sonnet-4-5
    litellm_params:
      model: openai/glm-4-plus
      
  # Subagentes (Haiku) - Os "Operários" Rápidos
  - model_name: claude-haiku-4-5
    litellm_params:
      model: openai/glm-4-flash

Com essa configuração, você garante que os subagentes sejam leves o suficiente para não gastar cota, mas (sendo da geração GLM-4-Flash) competentes o suficiente para tarefas mecânicas e resumos não críticos.

E quando a tarefa envolver auditorias profundas de segurança, a recomendação final: não terceirize para a AI. Instrua claramente o Claude Code a ler todo o código no agente principal. (“Leia estes arquivos e analise você mesmo, não resuma”).