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.
//
Busque em todas as páginas da documentação
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.
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.
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.
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) |
Edit em sua lista de ferramentas genuinamente não pode editar arquivos, independentemente do que seu prompt diga ou de como ele seja solicitado.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.
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.
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.
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.
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 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.
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.
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.
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.
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.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026