Context Engineering: gastando a atenção finita onde ela conta · Lição 5 de 6

Lição 5: Subagentes e isolamento de contexto

Objetivos de aprendizado:

Explicar por que um subagente conta como um movimento de gestão de contexto: uma janela limpa mais um resumo devolvido, mantendo o “processo” fora da janela principal

Usar a razão entre tokens de processo e tokens de conclusão, mais dados reais de custo, para julgar se vale a pena entregar uma tarefa a um subagente

Ligar o despacho de subagentes ao loop de harness que você escreveu no curso 7 desta série, de modo que cada despacho devolva exatamente um resumo à janela principal

Pré-requisitos: Você concluiu a Lição 4 sobre compactação e notas, e consegue rodar o loop de harness que escreveu no curso 7 desta série, “Fundamentos do Harness de Agente: Laços e Controle” | Anterior: Lição 4 << | Próxima: Lição 6 >>

Uma virada de perspectiva: não é divisão de trabalho, é só isolamento

Você já encontrou subagentes no curso 6 desta série, “Colaboração Multiagente”: como dividir uma tarefa, como reportar resultados, como vários agentes se coordenam. Aquele curso respondeu à pergunta de como múltiplos agentes trabalham juntos. Esta lição responde a outra: o que faz de um subagente, antes de mais nada, uma técnica de gestão de contexto?

Dito de outro jeito: mesmo que você tenha um único agente líder e não precise de coordenação de equipe nenhuma, ainda assim vai querer lançar mão de um subagente — não pela divisão de trabalho, mas pelo isolamento.

Volte à visão de orçamento da Lição 1. Quando um modelo analisa contexto, ele lança mão de um orçamento de atenção, e cada novo token que entra no contexto esgota um pouco desse orçamento¹. Empilhe mais tokens e a capacidade do modelo de recuperar informação com precisão desse contexto declina¹. Um agente é exatamente o cenário mais propenso a empilhar tokens: cada volta do loop produz dados novos que podem ser relevantes para o próximo turno de inferência — difíceis de jogar fora, difíceis de manter¹.

Tarefas de exploração são a versão mais aguda disso. Digamos que o agente principal tenha de rastrear todos os pontos de chamada de alguma API obsoleta em um repositório de algumas centenas de milhares de linhas: uma dúzia de greps, vinte arquivos abertos, alguns milhares de linhas lidas. Esse conteúdo intermediário chega a dezenas de milhares de tokens, enquanto a conclusão que vale manter talvez tenha cinco linhas: “os pontos de chamada se concentram nestes três módulos, e aqui está a ordem de migração sugerida”. Se tudo isso acontece na janela principal, o orçamento de atenção é devorado pelo processo, sobrando pouco para a conclusão e para o trabalho que vem depois.

O subagente é a faca apontada exatamente para esse problema.

O mecanismo: janela limpa na entrada, resumo comprimido na saída

O mecanismo cabe em uma frase: um subagente especializado cuida de uma tarefa focada em uma janela de contexto limpa¹; o grande volume de conteúdo intermediário que a exploração gera — resultados de busca, conteúdo bruto de arquivos, becos sem saída — fica todo dentro do subagente¹; e o que volta ao agente principal é apenas um resumo condensado e destilado do trabalho dele, muitas vezes de 1.000 a 2.000 tokens¹.

A janela do agente principal, portanto, carrega só a conclusão, nunca o processo. É um projeto assimétrico: o subagente pode queimar dezenas de milhares de tokens explorando, mas só um trecho curto de texto chega a sair dele.

Em código, isso é apenas uma nova abertura para o harness que você escreveu no curso 7. Para manter as coisas compactas, duas ações que se repetiam ao longo do loop daquele curso aparecem aqui embrulhadas como auxiliares: textOf extrai o bloco de texto de uma resposta, e appendToolResults roda as ferramentas deste turno e anexa os blocos tool_result ao array de mensagens (internamente ele faz exatamente o que você escreveu à mão naquele curso — rodar cada tool_use, coletar os resultados, devolvê-los).

JAVASCRIPT

const SUBAGENT_SYSTEM = `Você é um subagente de pesquisa.
Quando a tarefa terminar, produza uma conclusão de no máximo 1500 tokens:
achados principais, os caminhos de arquivo envolvidos e ações recomendadas para o agente principal.
Não repita o texto bruto que você leu.`;

async function runSubagent(client, task, maxTurns = 15) {
  // O truque inteiro é esta linha: um array de mensagens novo em folha, nada do histórico do agente principal
  let messages = [{ role: "user", content: task }];
  for (let turn = 0; turn < maxTurns; turn++) {
    const response = await client.messages.create({
      model: "claude-sonnet-5",
      max_tokens: 4096,
      system: SUBAGENT_SYSTEM, // o system prompt do próprio subagente
      tools: SEARCH_TOOLS,     // só as ferramentas de que a exploração precisa
      messages,
    });
    if (response.stop_reason === "end_turn") {
      return textOf(response); // só este texto sai do subagente
    }
    // roda as ferramentas, anexa os resultados a messages, tudo isso fica dentro do subagente
    messages = await appendToolResults(messages, response);
  }
  return "A pesquisa não terminou dentro do orçamento de turnos";
}

Repare em três detalhes. Primeiro, messages parte de uma única e solitária descrição de tarefa, sem carregar uma palavra do histórico do agente principal — esse é o significado inteiro de “janela limpa”. Segundo, a função retorna textOf(response), uma string simples; as dezenas de idas e vindas de ferramenta que se empilharam dentro do loop desaparecem junto com a variável local messages. Terceiro, o system prompt do subagente exige explicitamente “não repita o texto bruto” — a qualidade de compressão do resumo é definida bem aqui.

Do lado do agente principal, a ação de despacho é apenas uma ferramenta comum que se encaixa no loop de stop_reason que você já tem:

JAVASCRIPT

const DISPATCH_TOOL = {
  name: "dispatch_research",
  description:
    "Entrega uma tarefa de pesquisa focada a um subagente e devolve o resumo dos achados dele. " +
    "Use para tarefas que exigem exploração pesada mas cuja conclusão pode ser dita brevemente.",
  input_schema: {
    type: "object",
    properties: {
      task: {
        type: "string",
        description: "Uma descrição de tarefa autocontida; o subagente não enxerga o histórico desta conversa",
      },
    },
    required: ["task"],
  },
};

async function handleDispatch(mainMessages, toolCall) {
  const summary = await runSubagent(client, toolCall.input.task);
  mainMessages.push({
    role: "user",
    content: [{
      type: "tool_result",
      tool_use_id: toolCall.id,
      content: summary, // a janela principal ganha só esta entrada
    }],
  });
}

Olhe a descrição do campo task: “Uma descrição de tarefa autocontida; o subagente não enxerga o histórico desta conversa”. Essa linha foi escrita para o agente principal — ele tem de enunciar a tarefa por inteiro, porque do outro lado está uma janela nova e amnésica. Explicitar propósito e fronteiras com essa precisão na descrição de uma ferramenta é exatamente a ideia de “ferramentas como contexto” da Lição 2: as ferramentas devem ser autocontidas, robustas a erro e extremamente claras a respeito do uso a que se destinam¹.

Quanto do histórico do agente principal um subagente deve receber no início

Você está escrevendo a lógica de despacho de um subagente de pesquisa, e um colega sugere: “Passe ao subagente todo o histórico de mensagens do agente principal até aqui — ele vai entender o quadro geral e fazer um trabalho melhor.” Do ponto de vista da economia de contexto, como você avalia isso?

Dados de primeira mão: subagentes como filtros inteligentes

O mecanismo está assentado; agora as medições. A Anthropic escreveu publicamente sobre seu sistema multiagente de pesquisa — a arquitetura por trás do recurso Research do Claude — que é um raro material de engenharia de primeira mão².

Três de seus achados falam diretamente a esta lição:

Os subagentes viabilizam a compressão ao operarem em paralelo com suas próprias janelas de contexto². Cada subagente explora em uma janela só dele, sem apertar as demais.
Eles chamam os subagentes de "intelligent filters" (filtros inteligentes): condensando os tokens mais importantes para o agente de pesquisa líder². A palavra “filtro” é certeira — entra corpus, saem os pontos essenciais.
Uma frase que vale mastigar: "The essence of search is compression: distilling insights from a vast corpus."² (a essência da busca é a compressão: destilar insights de um corpus vasto.) Lida no contexto desta lição: toda exploração que um subagente roda existe para produzir aquele destilado de mil tokens.

Como observação lateral, o paralelismo também compra velocidade — várias linhas de pesquisa avançando ao mesmo tempo. Mas isso é assunto de orquestração, já coberto no curso 6 desta série; esta lição mantém o olho apenas no lado da compressão.

O outro lado do balanço: isolamento não é economia de custo

Com a vantagem exposta, a conta também precisa ser exposta. O mesmo texto traz os números medidos — note que são medições do sistema de pesquisa da Anthropic, não leis universais:

Os agentes normalmente usam cerca de 4× mais tokens do que interações de chat²;
Os sistemas multiagente usam cerca de 15× mais tokens do que os chats²;
Quando analisaram de onde vinha o desempenho, o uso de tokens sozinho explicou 80% da variância, com o número de chamadas de ferramenta e a escolha do modelo respondendo pela maior parte do resto².

A conclusão deles é franca: "Multi-agent systems work mainly because they help spend enough tokens to solve the problem."² (os sistemas multiagente funcionam principalmente porque ajudam a gastar tokens suficientes para resolver o problema.)

Então vamos ser diretos: um subagente não é uma economia de custo. O total de tokens só sobe — a tarefa tem de ser reenunciada, o pano de fundo reassentado, várias janelas queimando ao mesmo tempo. O que ele compra é outra coisa: cada janela permanece em uma faixa que não se degradou, então a densidade de atenção se mantém alta o tempo todo. É uma troca de atenção — gaste mais tokens no total, ganhe uma janela limpa para cada um.

Quando essa troca vale a pena? De volta à visão de orçamento da Lição 1: o contexto é um recurso finito com retornos marginais decrescentes¹. Duas perguntas para julgar:

Razão entre processo e conclusão. Quão grande é o conteúdo intermediário desta tarefa, e quão pequena é sua conclusão final? Quanto mais desequilibrada a razão, maior o retorno do isolamento. Na direção contrária, uma tarefa cujo processo já é curto vira puro custo de repasse se você a despachar.
Se a complexidade melhora comprovadamente o resultado. A orientação da Anthropic é considerar adicionar complexidade apenas quando isso melhorar comprovadamente os resultados — a palavra no original é "consider" (considerar), uma questão de proporção, não uma regra de ferro³. Se os tokens extras não compram uma saída melhor, volte para uma janela só.

A combinação para tarefas longas: notas como base, repasses para o fôlego

Por mais limpa que seja a janela de um subagente, ela ainda é finita. Para tarefas genuinamente de horizonte longo, o texto descreve uma combinação: os agentes resumem fases de trabalho concluídas e guardam informação essencial em memória externa²; depois geram subagentes novos com contextos limpos para seguir adiante, mantendo continuidade por meio de repasses cuidadosos².

Isso costura a Lição 4 e esta em uma única sequência de movimentos:

As notas estruturadas da Lição 4 cuidam de “colocar o estado-chave fora da janela” — um NOTES.md, uma lista de tarefas — elas vivem no sistema de arquivos e não ocupam a atenção de janela nenhuma;
O isolamento desta lição cuida de “manter cada trecho de trabalho dentro de uma janela limpa” — a primeira coisa que um subagente novo faz é ler as notas; ele não precisa herdar o histórico completo de seu antecessor, apenas os pontos essenciais destilados dele.

O que entra em um documento de repasse? Reutilize o mesmo padrão de trade-off da compactação da Lição 4: manter decisões arquiteturais, bugs não resolvidos e detalhes de implementação, e descartar saídas de ferramenta redundantes¹. Escrever um repasse e escrever um resumo de compactação são o mesmo ofício; só muda o leitor, de “você mesmo no futuro” para “o próximo subagente”.

Como isso aparece no Claude Code

Por fim, confronte tudo isso com uma implementação que você usa todo dia. As boas práticas oficiais do Claude Code colocam a coisa sem rodeios: a janela de contexto enche rápido, e o desempenho se degrada conforme ela enche; "The context window is the most important resource to manage."⁴ (a janela de contexto é o recurso mais importante a gerenciar.) Como o contexto é a restrição fundamental, os subagentes estão entre as ferramentas mais poderosas disponíveis⁴.

A implementação dele corresponde ao mecanismo que esta lição descreve: os subagentes rodam em janelas de contexto separadas e reportam de volta resumos⁴. Peça ao Claude Code para “encontrar a causa-raiz deste bug” e o subagente que ele despacha vai fazer grep, ler arquivos e seguir a cadeia de chamadas — toda essa exploração acontecendo na janela do próprio subagente, com a conversa principal recebendo apenas um resumo da investigação no final. Delimite investigações de forma estreita ou entregue-as a subagentes, e a exploração não consome seu contexto principal⁴.

Quando você vê uma subtarefa rodando em segundo plano na interface e a conversa principal ganha apenas um relatório curto quando ela termina, isso é a “janela limpa na entrada, resumo comprimido na saída” que esta lição vem descrevendo desde o começo.

A esta altura você já viu as três peças do kit de tarefas longas: compactação (Lição 4), notas estruturadas (Lição 4) e arquiteturas multiagente (esta lição). O objetivo comum delas é permitir que um agente mantenha coerência, contexto e comportamento orientado a objetivos ao longo de sequências de ações¹. Na Lição 6 nós ligamos as três ao seu próprio harness.

Recapitulação

Um subagente é uma técnica de gestão de contexto: a tarefa focada roda em uma janela de contexto limpa, o conteúdo intermediário da exploração fica isolado dentro do subagente, e o que volta é muitas vezes apenas um resumo destilado de 1.000 a 2.000 tokens — a janela principal carrega a conclusão, não o processo¹.
No sistema multiagente de pesquisa da Anthropic, os subagentes rodam em janelas de contexto separadas em paralelo e alcançam compressão por meio disso, atuando como "intelligent filters" (filtros inteligentes) que condensam os tokens mais importantes para o agente líder; "The essence of search is compression"².
Números medidos do mesmo sistema: os agentes usam cerca de 4× mais tokens do que os chats, os sistemas multiagente cerca de 15×, e o uso de tokens sozinho explica 80% da variância de desempenho — o isolamento é uma troca de atenção, “gaste mais tokens no total por uma janela que não se degrada”, não uma economia de custo².
Se o isolamento vale a pena depende da razão entre processo e conclusão, e de se a complexidade acrescentada melhora comprovadamente o resultado — a palavra da Anthropic é "consider" (considerar), uma questão de proporção e não uma regra de ferro³.
A combinação para tarefas longas: resuma assim que uma fase se completa, guarde o essencial em memória externa, depois gere um subagente novo com contexto limpo e mantenha a continuidade por meio de repasses cuidadosos — as notas da Lição 4 e o isolamento desta lição formam um par casado².
No Claude Code, a janela de contexto é o recurso mais importante a gerenciar, o que faz dos subagentes uma das ferramentas mais poderosas disponíveis: eles rodam em janelas de contexto separadas e reportam de volta apenas resumos⁴.

>> Lição 6: Prática: ligando a gestão de contexto ao harness

Effective context engineering for AI agents — Anthropic Engineering — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹
How we built our multi-agent research system — Anthropic Engineering — https://www.anthropic.com/engineering/multi-agent-research-system ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³
Building Effective AI Agents — Anthropic Engineering — https://www.anthropic.com/engineering/building-effective-agents ↩ ↩²
Best practices for Claude Code — Claude Code Docs — https://code.claude.com/docs/en/best-practices ↩ ↩² ↩³ ↩⁴ ↩⁵

Exercícios

Seu agente principal assume três tarefas:

Nível 1: Decida sobre isolamento para três tarefas

Tarefa A: Em um repositório de algumas centenas de milhares de linhas, encontre todos os pontos de chamada que ainda usam a API obsoleta LegacyLedgerReader e sugira uma ordem de migração.
Tarefa B: O agente principal acabou de ler uma função de 80 linhas para o contexto; o usuário aponta um bug de erro por um nela e pede uma correção.
Tarefa C: Para uma decisão de escolha de biblioteca, pesquise três bibliotecas de parsing candidatas — leia a documentação de cada uma, vasculhe seu rastreador de issues e faça uma comparação lado a lado.

Para cada tarefa, anote sua decisão — isolar (despachar um subagente) ou não (fazer na janela principal) — apontando o paralelismo onde ele se aplica, e dê uma ou duas frases de justificativa usando os critérios desta lição.

Critérios de conclusão · marcado localmente

Os três julgamentos giram em torno da razão entre tokens de processo e tokens de conclusão: quanto mais pesado o processo e menor a conclusão, mais vale isolarA Tarefa B é julgada como não-isolar, com um raciocínio que inclui o lado do custo: a função já está na janela principal, então um subagente novo teria de retransferir a função e o pano de fundo da tarefa, fazendo o custo do isolamento exceder o benefícioA Tarefa C observa que as três linhas de pesquisa não dependem umas das outras, então podem ocupar janelas separadas em paralelo, cada uma devolvendo apenas os pontos de que a comparação precisa

Você ligou um subagente ao harness do curso 7 desta série, com esta lógica de despacho:

Nível 2: Corrija uma função de despacho com “isolamento de fachada”

JAVASCRIPT

async function runSubagent(client, task, maxTurns = 15) {
  let messages = [{ role: "user", content: task }];
  for (let turn = 0; turn < maxTurns; turn++) {
    const response = await client.messages.create({
      model: "claude-sonnet-5",
      max_tokens: 4096,
      system: SUBAGENT_SYSTEM,
      tools: SEARCH_TOOLS,
      messages,
    });
    if (response.stop_reason === "end_turn") {
      // acrescenta também a resposta final, devolve o histórico completo
      return [
        ...messages,
        { role: "assistant", content: textOf(response) },
      ];
    }
    messages = await appendToolResults(messages, response);
  }
  return messages;
}

async function handleDispatch(mainMessages, toolCall) {
  const subHistory = await runSubagent(client, toolCall.input.task);
  mainMessages.push({
    role: "user",
    content: [{
      type: "tool_result",
      tool_use_id: toolCall.id,
      // renderiza o histórico inteiro como texto e enfia de volta na janela principal
      content: renderAsText(subHistory),
    }],
  });
}

Sintoma: depois de três despachos de pesquisa, o uso de contexto do agente principal está se aproximando do limite da janela, e a lógica de compactação que você instalou na Lição 4 é forçada a disparar cedo. Inspecione o array de mensagens do agente principal e você vai descobrir que a esmagadora maioria dos tokens são os retornos de ferramenta originais do subagente.

Aponte a causa-raiz e edite o código para que cada despacho acrescente apenas um resumo à janela principal.

Critérios de conclusão · marcado localmente

Identifica a causa-raiz no valor de retorno de `runSubagent` e na escrita de volta de `handleDispatch`: o histórico de mensagens completo do subagente (com todos os seus retornos de ferramenta) é renderizado por atacado em texto e enfiado na janela principal, então o isolamento é uma casca ocaDepois da correção, `runSubagent` devolve apenas o texto do resumo final, o `content` do `tool_result` é esse resumo, e cada despacho acrescenta uma mensagem à janela principalExplica a ligação com a Lição 4: a janela principal deixa de ser inundada com o conteúdo de processo do subagente, então a lógica de compactação dispara menos vezes

Lição 5: Subagentes e isolamento de contexto

Uma virada de perspectiva: não é divisão de trabalho, é só isolamento

O mecanismo: janela limpa na entrada, resumo comprimido na saída

Dados de primeira mão: subagentes como filtros inteligentes

O outro lado do balanço: isolamento não é economia de custo

A combinação para tarefas longas: notas como base, repasses para o fôlego

Como isso aparece no Claude Code

Recapitulação

Footnotes

Exercícios

Seu agente principal assume três tarefas:

Você ligou um subagente ao harness do curso 7 desta série, com esta lógica de despacho: