Como Subagentes Obtêm Seu Próprio Contexto e Ferramentas
Um subagente não é uma versão menor da sessão principal do Claude Code.
É uma instância separada, com uma janela de contexto que começa quase vazia e uma lista de ferramentas que pode ser mais restrita que a do pai.
Entender por que esse isolamento existe, em vez de tratá-lo como um detalhe de implementação, é o que possibilita usar subagentes bem em vez de apenas criá-los reflexivamente.
Resumo
- Ideia Central: um subagente é executado em sua própria janela de contexto e com suas próprias permissões de ferramentas com escopo, separadas da sessão que o gerou.
- Por Que Importa: sem isolamento, cada etapa exploratória que um subagente realiza consumiria o orçamento de contexto da sessão principal, e cada subagente teria acesso total a tudo que o pai pudesse acessar.
- Conceitos-Chave: janela de contexto, contexto isolado, escopo de ferramentas, prompt de tarefa, relatório de resumo, sessão pai.
- Quando Usar: pesquisas que, de outra forma, inundariam a sessão principal com detalhes intermediários, trabalhos que não deveriam ter acesso a certas ferramentas, ou tarefas independentes que podem ser executadas em paralelo.
- Limitações / Compromissos: o isolamento significa que um subagente não pode ver a conversa anterior do pai, a menos que seja explicitamente incluído, e a criação de um adiciona latência real para tarefas pequenas.
- Tópicos Relacionados: pesquisa paralela de subagentes, o Claude Agent SDK, comandos de barra personalizados, hooks.
Fundamentos
Toda sessão do Claude Code tem uma janela de contexto, o registro em execução de tudo o que foi dito e feito naquela conversa até o momento.
Um subagente recebe sua própria janela de contexto, não uma fatia compartilhada da do pai.
Quando o pai gera um subagente, ele escreve um prompt de tarefa descrevendo exatamente o que o subagente deve fazer, e esse prompt de tarefa é efetivamente todo o ponto de partida do contexto do subagente.
O subagente não herda as turns anteriores do pai, suas leituras de arquivo anteriores ou seu raciocínio em andamento, a menos que o pai reitere explicitamente essas informações no prompt de tarefa.
Uma analogia simples: entregar trabalho a um subagente é como entregar uma pasta selada de instruções a um empreiteiro, não como incluir um colega de trabalho que já estava na sala para toda a reunião.
O empreiteiro faz o trabalho descrito na pasta, depois devolve um relatório escrito. Ele não volta para a sala e começa a narrar tudo o que viu ao longo do caminho.
Mecânicas e Interações
O isolamento resolve dois problemas separados, e é útil nomeá-los separadamente.
O primeiro é o orçamento de contexto. Uma janela de contexto é finita. Se uma tarefa de pesquisa levar quarenta chamadas de ferramenta para explorar uma base de código, executar essa pesquisa diretamente na sessão principal significa que quarenta chamadas de ferramenta de conteúdo de arquivo, resultados de pesquisa e becos sem saída ficam no histórico da conversa principal, independentemente de qualquer coisa que se mostre importante. Delegar essa pesquisa a um subagente significa que apenas o resumo final do subagente, não suas quarenta etapas intermediárias, entra no contexto do pai.
O segundo é o escopo de ferramentas. Um subagente pode ser configurado com uma lista de ferramentas mais restrita do que as permissões do próprio pai.
---
name: codebase-researcher
description: Pesquisa somente leitura sobre como um recurso específico é implementado
tools: Read, Grep, Glob
---
Você investiga como um recurso nomeado é implementado em toda a base de código e
relata os caminhos dos arquivos e uma breve descrição de cada um, em menos de 300 palavras.Essa linha tools é uma restrição real, não uma sugestão. Um subagente definido dessa forma não pode chamar Edit ou Write, não importa como seu prompt de tarefa seja formulado, porque essas ferramentas simplesmente não estão em seu conjunto disponível para aquela invocação. É isso que transforma "isolamento" de uma conveniência em um limite de segurança real.
Quando o pai gera vários subagentes ao mesmo tempo, cada um recebe seu próprio contexto independente, que é exatamente o que torna a execução deles em paralelo segura. Dois subagentes pesquisando subsistemas diferentes não podem acidentalmente ler ou construir sobre as descobertas intermediárias um do outro, porque nenhum deles tem acesso ao contexto do outro em primeiro lugar.
Considerações Avançadas e Aplicações
O modelo de isolamento tem compromissos reais, e tratá-lo como gratuito levaria ao uso excessivo de subagentes.
Gerar um subagente tem um custo de latência: configurar um novo contexto, executar a tarefa e reportar de volta é mais lento do que continuar diretamente na sessão principal para uma tarefa pequena e bem definida. Uma pesquisa de uma linha não precisa de um subagente; uma exploração de quarenta etapas geralmente precisa.
O isolamento também significa que um subagente pode perder o acesso a nuances que a sessão pai construiu ao longo de uma longa conversa. Se o pai está depurando um problema sutil há vinte turns e gera um subagente para verificar uma hipótese, o subagente só sabe o que o prompt de tarefa do pai lhe diz, não os vinte turns de contexto acumulado. Escrever um prompt de tarefa que inclua o suficiente desse contexto, sem colar a conversa inteira, é uma habilidade real, e subespecificá-lo é uma das maneiras mais comuns de o relatório de um subagente voltar menos útil do que o esperado.
Há também um ângulo de governança que vale a pena nomear explicitamente. Como o escopo das ferramentas é aplicado por subagente, um projeto pode definir funções de subagente especializadas: um pesquisador estritamente somente leitura, um executor de testes com acesso a comandos de teste, mas não a edições de código-fonte, um redator de documentação com escopo apenas para arquivos markdown, cada um com permissões correspondentes ao seu trabalho real. Isso é uma postura de segurança significativamente diferente de uma única sessão com acesso uniformemente amplo realizando todos os tipos de tarefas.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| Trabalhar diretamente na sessão principal | Sem sobrecarga de latência, contexto em execução completo disponível | Cada etapa exploratória consome o orçamento de contexto compartilhado | Tarefas pequenas e rápidas estritamente acopladas à conversa em andamento |
| Gerar um subagente | Mantém a exploração fora do contexto principal, pode limitar o escopo das ferramentas | Adiciona latência, o subagente começa com contexto mínimo | Uma pesquisa delimitada ou tarefa isolada com um entregável claro |
| Gerar vários subagentes em paralelo | Trabalho independente ocorre simultaneamente, sem contaminação cruzada | Sobrecarga de coordenação, o pai deve sintetizar vários relatórios | Múltiplas subtarefas genuinamente independentes (por exemplo, auditoria de subsistemas separados) |
Equívocos Comuns
- "Um subagente tem acesso a toda a conversa até agora, apenas em uma janela separada." Não tem. Seu contexto começa essencialmente vazio, semeado apenas com o prompt de tarefa que o pai escreve; qualquer coisa que o pai não inclua explicitamente é invisível para o subagente.
- "Limitar as ferramentas de um subagente é apenas uma formalidade organizacional." É uma restrição aplicada. Um subagente sem
Editem sua lista de ferramentas genuinamente não pode editar arquivos, independentemente do que seu prompt diga ou de como ele seja solicitado. - "Subagentes compartilham o mesmo orçamento de contexto, apenas dividido." Cada subagente recebe sua própria janela de contexto independente; gerar três subagentes não divide um orçamento compartilhado por três, mas cria três separados.
- "Usar um subagente é sempre mais eficiente do que fazer o trabalho diretamente." Para uma tarefa pequena, a sobrecarga de configuração e relatório de um subagente pode custar mais do que fazer o trabalho na sessão principal; o isolamento compensa quando a tarefa é grande ou independente o suficiente para justificá-lo.
- "Um subagente pode voltar livremente e pedir mais contexto ao pai no meio da tarefa." Um subagente geralmente opera com o prompt de tarefa que recebeu inicialmente e reporta uma vez; ele não tem um canal aberto para consultar interativamente a sessão pai enquanto trabalha.
FAQs
Com o que um subagente realmente começa em sua janela de contexto?
- Apenas com o prompt de tarefa que a sessão pai escreveu ao gerá-lo.
- Sem histórico de conversas anterior do pai, a menos que explicitamente incluído nesse prompt de tarefa.
- Sem memória de qualquer outro subagente que possa estar sendo executado em paralelo.
Um subagente pode usar qualquer ferramenta que a sessão pai possa usar?
Não necessariamente. A lista de ferramentas de um subagente pode ser configurada de forma mais restrita que a do pai, e qualquer ferramenta não presente nessa lista simplesmente não está disponível para ele, independentemente do que a tarefa solicite.
A sessão pai vê tudo o que o subagente fez enquanto trabalhava?
Não. O pai recebe apenas o resumo que o subagente reporta no final; as leituras de arquivo individuais, pesquisas e etapas de raciocínio intermediário do subagente não são exibidas ao pai.
Por que o isolamento é importante para executar vários subagentes em paralelo?
Como o contexto de cada subagente é independente, suas pesquisas não podem se contaminar. Dois subagentes investigando subsistemas separados não influenciarão acidentalmente as descobertas um do outro, já que nenhum tem visibilidade do trabalho do outro.
Limitar as ferramentas de um subagente é principalmente uma questão de conveniência ou de segurança?
Ambos, mas o aspecto de segurança é real, não cosmético. Um subagente com escopo para ferramentas somente leitura não pode fazer uma edição, mesmo que seu prompt seja formulado para tentar convencê-lo a fazer isso, porque a ferramenta não está disponível para ser chamada.
Gerar um subagente custa algo além do benefício do isolamento?
Sim, principalmente latência. Configurar um novo contexto e esperar que o subagente conclua sua tarefa e reporte leva mais tempo do que continuar diretamente na sessão principal, o que é importante para tarefas pequenas.
O que acontece se um prompt de tarefa para um subagente for muito vago?
O subagente não tem mais nada em que se basear, então um prompt de tarefa vago ou subespecificado tende a produzir um relatório vago ou incompleto, já que o subagente não pode inferir o contexto ausente de uma conversa que nunca viu.
Um subagente pode gerar seus próprios subagentes?
O mecanismo existe na arquitetura subjacente, mas na prática a maioria dos fluxos de trabalho mantém a geração de subagentes em um único nível, delegada da sessão principal, para evitar o acúmulo de latência e complexidade de coordenação.
A janela de contexto isolada de um subagente é do mesmo tamanho que a da sessão principal?
O mecanismo é o mesmo tipo de janela de contexto, mas como ela começa quase vazia, um subagente normalmente tem muito mais espaço disponível para sua tarefa específica do que a sessão principal tem no meio de uma longa conversa.
Como a sessão pai decide quando gerar um subagente em vez de fazer o trabalho diretamente?
- A tarefa é exploratória e geraria muitos detalhes intermediários que não valem a pena manter no contexto principal.
- A tarefa deve ser executada com acesso a ferramentas mais restrito do que a sessão atual tem.
- A tarefa é independente o suficiente para ser executada em paralelo com outros trabalhos.
O isolamento significa que um subagente nunca pode afetar os arquivos reais da sessão principal?
Não. Um subagente com Edit ou Write em sua lista de ferramentas ainda pode modificar arquivos; o isolamento é sobre contexto e escopo de permissão, não sobre se ele pode agir na mesma base de código em que o pai está trabalhando.
Relacionados
- Comandos Personalizados, Hooks e Subagentes: Para Que Serve Cada Um - como os subagentes diferem de comandos e hooks.
- Noções Básicas de Comandos Personalizados e Subagentes - uma primeira geração prática de subagente.
- Gerando Subagentes Paralelos para Tarefas de Pesquisa Isoladas - colocando o isolamento em prática em vários subagentes ao mesmo tempo.
- Subagentes vs. Agent SDK: Como o Claude Code é Construído - os primitivos subjacentes nos quais este modelo de isolamento é construído.
Versões de Stack: Escrito contra a linha de modelos Claude atual em aproximadamente junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos do produto mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.