Delegando Trabalho para Subagentes no Claude Agent SDK

Q: Quais ferramentas um subagente pode usar?

O que você definir para ele através de seu próprio allowed_tools e tool_config, independentemente do escopo de ferramentas do pai; um subagente não recebe automaticamente as ferramentas do pai.

Um subagente é um agente filho com seu próprio contexto isolado para o qual um agente pai pode delegar uma subtarefa.

Em vez de um único agente tentar manter uma tarefa inteira e grande, incluindo cada etapa intermediária de cada subproblema, em uma única janela de contexto, um pai pode delegar peças autônomas para subagentes e receber de volta apenas seus resultados finais.

Resumo

Subagentes existem por duas razões relacionadas: isolamento de contexto e paralelismo.

Isolamento significa que o raciocínio exploratório, as tentativas falhas e as chamadas de ferramentas intermediárias de um subagente nunca poluem o contexto do pai; o pai vê um resultado limpo.

Paralelismo significa que subagentes independentes podem rodar concorrentemente, já que nenhum depende do estado intermediário do outro.

Esta página cobre como definir subagentes, quando uma tarefa é um bom candidato para delegação, e como o escopo de ferramentas e os resultados fluem entre pai e filho.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

from claude_agent_sdk import query, AgentOptions, SubagentConfig
 
options = AgentOptions(
    allowed_tools=["file_edit", "bash"],
    subagents=[
        SubagentConfig(
            name="frontend-reviewer",
            description="Revisa as alterações de componentes React quanto à correção e estilo.",
            allowed_tools=["file_edit"],
        ),
        SubagentConfig(
            name="backend-reviewer",
            description="Revisa as alterações de rotas de API quanto à correção e segurança.",
            allowed_tools=["file_edit", "bash"],
        ),
    ],
)
 
async for message in query(
    prompt="Revise o frontend e o backend deste PR usando os dois subagentes revisores.",
    options=options,
):
    print(message)

Quando usar isso:

Uma tarefa se divide claramente em duas ou mais partes independentes que não precisam ver as etapas intermediárias umas das outras.
Uma parte, de outra forma, inundaria o contexto do pai com raciocínio exploratório irrelevante para o resto da tarefa.
Você deseja um conjunto de ferramentas mais restrito e com escopo diferente para uma parte do trabalho do que para outra.
Você deseja executar partes independentes concorrentemente em vez de uma após a outra.

Exemplo de Trabalho

import asyncio
from claude_agent_sdk import query, AgentOptions, SubagentConfig
 
async def audit_monorepo_packages(repo_path: str, packages: list[str]) -> None:
    subagents = [
        SubagentConfig(
            name=f"audit-{pkg}",
            description=f"Audita o pacote {pkg} quanto a dependências desatualizadas e erros de lint.",
            allowed_tools=["bash", "file_edit"],
            tool_config={
                "bash": {"allowed_commands": ["npm outdated", "npm run lint"]},
                "file_edit": {"allowed_paths": [f"packages/{pkg}/**"]},
            },
        )
        for pkg in packages
    ]
 
    options = AgentOptions(
        cwd=repo_path,
        allowed_tools=["file_edit"],
        subagents=subagents,
    )
 
    prompt = (
        f"Use os subagentes de auditoria para cada um dos {packages} para verificar dependências desatualizadas "
        "e erros de lint, em seguida, escreva um resumo combinado AUDIT.md "
        "na raiz do repositório com uma seção por pacote."
    )
 
    async for message in query(prompt=prompt, options=options):
        if message.get("type") == "text":
            print(message["text"], end="", flush=True)
        elif message.get("type") == "subagent_result":
            print(f"\n[{message['subagent_name']} finished]")
 
asyncio.run(audit_monorepo_packages("/repo", ["billing", "auth", "search"]))

O que isso demonstra:

Geração de um subagente por pacote para que cada auditoria rode em seu próprio contexto isolado, com escopo apenas para os arquivos desse pacote.
Escopo do acesso bash e file_edit de cada subagente independentemente do pai e um do outro.
O agente pai precisando apenas de file_edit para si mesmo, já que seu próprio trabalho é apenas escrever o resumo combinado.
Subtarefas independentes e de formato semelhante (auditar pacotes não relacionados) como o caso mais claro para delegação.

Mergulho Profundo

Como Funciona

Um subagente é definido com um name (nome), uma description (descrição) que o modelo pai usa para decidir quando invocá-lo, e suas próprias allowed_tools (ferramentas permitidas)/tool_config (configuração de ferramentas).
Do loop de uso de ferramentas do pai, invocar um subagente se parece com qualquer outra chamada de ferramenta: o pai decide chamá-lo, o SDK executa o loop interno do próprio subagente até a conclusão, e o resultado retorna como uma observação.
O subagente executa seu próprio ciclo de decidir-agir-observar internamente, com sua própria janela de contexto que começa limpa para essa invocação e não carrega o histórico completo do pai por padrão.
Apenas o resultado final do subagente cruza de volta para o contexto do pai, não suas chamadas de ferramentas intermediárias ou raciocínio; esta é a propriedade de isolamento que mantém o contexto do pai limpo.
Como cada invocação de subagente é autônoma, subagentes independentes podem ser despachados e aguardados concorrentemente, enquanto um subagente cuja tarefa depende da saída de outro subagente deve rodar depois dele.

Quando Delegar vs. Adicionar uma Ferramenta

Sinal	Favorece	Razão
A tarefa precisa de mais uma capacidade, sem exploração independente	Adicionar uma ferramenta	Mais simples; sem necessidade de limite de contexto extra
A tarefa é uma subtarefa autônoma com sua própria exploração	Subagente	Mantém o ruído exploratório fora do contexto do pai
Múltiplas subtarefas semelhantes em entradas independentes	Subagentes (um por entrada)	Permite execução paralela
A subtarefa precisa de um escopo de ferramentas mais restrito ou diferente do pai	Subagente	O escopo da ferramenta é por subagente, não compartilhado

Notas de Python

# A descrição de um subagente é o que o modelo pai lê para decidir
# quando invocá-lo - trate-a como uma descrição de ferramenta, não um comentário.
SubagentConfig(
    name="test-runner",
    description="Executa a suíte de testes do projeto e relata apenas os testes falhos.",
    allowed_tools=["bash"],
    tool_config={"bash": {"allowed_commands": ["pytest"]}},
)

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Descrição
`name`	`str`	Identificador que o pai usa para invocar este subagente
`description`	`str`	Diz ao modelo pai quando este subagente se aplica
`allowed_tools`	`list[str]`	Escopo de ferramentas para este subagente, independente do pai
`tool_config`	`dict`	Escopo por ferramenta para as ferramentas deste subagente

Armadilhas

Delegar uma tarefa que não é realmente independente. Dividir uma tarefa com dependências reais entre dois subagentes força você a sequenciá-los manualmente e passar resultados entre eles. Correção: divida tarefas apenas em limites genuinamente independentes; mantenha etapas dependentes em um agente ou em sequência.
Escrever uma descrição vaga de subagente. Uma descrição como "agente auxiliar" não dá ao modelo pai nenhum sinal para quando invocá-lo. Correção: escreva descrições da mesma forma que escreveria uma descrição de ferramenta: específica, orientada para a ação e com escopo para um trabalho.
Assumir que um subagente vê o histórico completo do pai. Subagentes normalmente começam com um contexto limpo para sua invocação, não toda a conversa do pai. Correção: passe explicitamente qualquer contexto que o subagente realmente precise no prompt que você dá a ele.
Dividir excessivamente uma tarefa simples em muitos subagentes. Cada invocação de subagente adiciona sobrecarga (um contexto limpo, um loop interno completo); uma tarefa simples o suficiente para uma chamada de ferramenta não precisa de um subagente. Correção: reserve subagentes para subtarefas genuinamente independentes e não triviais.
Conceder a um subagente o escopo completo de ferramentas do pai por padrão. Copiar allowed_tools do pai para todos os subagentes anula o propósito de escopar o trabalho de forma restrita. Correção: escope cada subagente apenas para o que seu trabalho específico requer.
Não lidar com uma falha de subagente. Se o loop interno de um subagente falhar ou atingir o tempo limite, o pai precisa decidir o que fazer com um resultado incompleto. Correção: trate os resultados do subagente como qualquer outro resultado de ferramenta que pode falhar e lide com esse caso em seu prompt ou lógica de aplicativo.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Um único agente com mais ferramentas	A tarefa precisa de mais uma capacidade, não exploração independente	A subtarefa inundaria o contexto com raciocínio irrelevante
Chamadas de ferramentas sequenciais em um agente	As etapas dependem genuinamente da saída umas das outras	As etapas são independentes e poderiam ser executadas concorrentemente
Chamadas `query()` de nível superior separadas	Subtarefas são totalmente não relacionadas, sem tarefa pai compartilhada	Subtarefas fazem parte de uma tarefa pai coerente que precisa de um resultado combinado

FAQs

O que exatamente um subagente isola?

Sua própria janela de contexto, separada da do pai.
Seu próprio escopo de ferramentas, independente de allowed_tools do pai.
Seu raciocínio intermediário e chamadas de ferramentas, que nunca aparecem no contexto do pai, apenas o resultado final.

Como o pai decide quando invocar um subagente?

Da mesma forma que decide chamar qualquer ferramenta: o modelo lê a description do subagente junto com a conversa e escolhe invocá-lo quando a tarefa corresponde.

Subagentes podem rodar em paralelo?

Sim, quando são independentes uns dos outros. Subagentes cujas tarefas não dependem da saída uns dos outros podem ser despachados e aguardados concorrentemente.

Um subagente vê o histórico de conversas do pai?

Não por padrão; ele normalmente começa com um contexto limpo para sua própria invocação. Passe explicitamente qualquer contexto necessário no prompt que você dá ao subagente.

Um subagente pode ter seus próprios subagentes?

O modelo de subagente do SDK suporta aninhamento em princípio, já que cada subagente executa seu próprio loop interno de uso de ferramentas, mas aninhamento profundo adiciona sobrecarga real e dificuldade de depuração; a maioria das tarefas é bem atendida por um nível.

Quais ferramentas um subagente pode usar?

O que você definir para ele através de seu próprio allowed_tools e tool_config, independentemente do escopo de ferramentas do pai; um subagente não recebe automaticamente as ferramentas do pai.

Qual a diferença entre delegar para um subagente e apenas chamar uma ferramenta?

Uma chamada de ferramenta executa uma ação discreta e retorna um resultado. Uma invocação de subagente executa um loop interno completo de uso de ferramentas, potencialmente chamando várias ferramentas e raciocinando em várias etapas, antes de retornar um resultado final.

Quando uma tarefa é pequena demais para um subagente?

Quando é uma ação única e simples que uma chamada de ferramenta direta resolveria igualmente bem; a sobrecarga de um contexto limpo e um loop interno não vale a pena para etapas triviais.

O que acontece se a tarefa de um subagente falhar?

A falha (ou um resultado incompleto/erro) retorna ao pai como a observação dessa invocação, e o próprio loop do pai tem que decidir como proceder, da mesma forma que lidaria com qualquer chamada de ferramenta falha.

Posso limitar quantos subagentes rodam ao mesmo tempo?

Limites de concorrência são uma preocupação em nível de aplicativo; você controla quantas invocações de subagente despacha ao mesmo tempo em seu próprio código de orquestração em torno de query().

Relacionados

O Modelo Mental do Claude Agent SDK - como os subagentes se encaixam no loop conceitualmente
Habilitando Ferramentas de Edição de Arquivo, Bash e Web no Agent SDK - escopo de ferramentas, aplicável por subagente também
Referência de Opções de Configuração do Claude Agent SDK - comparando subagentes e outras opções
Adicionando Checkpoints Human-in-the-Loop a um Fluxo de Trabalho do Agent SDK - checkpoints dentro do trabalho delegado
Melhores Práticas do Claude Agent SDK - orientação de produção sobre escopo e delegação

Versões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o Claude Agent SDK (última versão, Python e TypeScript). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.

Resumo

Subagentes existem por duas razões relacionadas: isolamento de contexto e paralelismo.

Isolamento significa que o raciocínio exploratório, as tentativas falhas e as chamadas de ferramentas intermediárias de um subagente nunca poluem o contexto do pai; o pai vê um resultado limpo.

Paralelismo significa que subagentes independentes podem rodar concorrentemente, já que nenhum depende do estado intermediário do outro.

Esta página cobre como definir subagentes, quando uma tarefa é um bom candidato para delegação, e como o escopo de ferramentas e os resultados fluem entre pai e filho.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

from claude_agent_sdk import query, AgentOptions, SubagentConfig
 
options = AgentOptions(
    allowed_tools=["file_edit", "bash"],
    subagents=[
        SubagentConfig(
            name="frontend-reviewer",
            description="Revisa as alterações de componentes React quanto à correção e estilo.",
            allowed_tools=["file_edit"],
        ),
        SubagentConfig(
            name="backend-reviewer",
            description="Revisa as alterações de rotas de API quanto à correção e segurança.",
            allowed_tools=["file_edit", "bash"],
        ),
    ],
)
 
async for message in query(
    prompt="Revise o frontend e o backend deste PR usando os dois subagentes revisores.",
    options=options,
):
    print(message)

Quando usar isso:

Uma tarefa se divide claramente em duas ou mais partes independentes que não precisam ver as etapas intermediárias umas das outras.
Uma parte, de outra forma, inundaria o contexto do pai com raciocínio exploratório irrelevante para o resto da tarefa.
Você deseja um conjunto de ferramentas mais restrito e com escopo diferente para uma parte do trabalho do que para outra.
Você deseja executar partes independentes concorrentemente em vez de uma após a outra.

Exemplo de Trabalho

import asyncio
from claude_agent_sdk import query, AgentOptions, SubagentConfig
 
async def audit_monorepo_packages(repo_path: str, packages: list[str]) -> None:
    subagents = [
        SubagentConfig(
            name=f"audit-{pkg}",
            description=f"Audita o pacote {pkg} quanto a dependências desatualizadas e erros de lint.",
            allowed_tools=["bash", "file_edit"],
            tool_config={
                "bash": {"allowed_commands": ["npm outdated", "npm run lint"]},
                "file_edit": {"allowed_paths": [f"packages/{pkg}/**"]},
            },
        )
        for pkg in packages
    ]
 
    options = AgentOptions(
        cwd=repo_path,
        allowed_tools=["file_edit"],
        subagents=subagents,
    )
 
    prompt = (
        f"Use os subagentes de auditoria para cada um dos {packages} para verificar dependências desatualizadas "
        "e erros de lint, em seguida, escreva um resumo combinado AUDIT.md "
        "na raiz do repositório com uma seção por pacote."
    )
 
    async for message in query(prompt=prompt, options=options):
        if message.get("type") == "text":
            print(message["text"], end="", flush=True)
        elif message.get("type") == "subagent_result":
            print(f"\n[{message['subagent_name']} finished]")
 
asyncio.run(audit_monorepo_packages("/repo", ["billing", "auth", "search"]))

O que isso demonstra:

Geração de um subagente por pacote para que cada auditoria rode em seu próprio contexto isolado, com escopo apenas para os arquivos desse pacote.
Escopo do acesso bash e file_edit de cada subagente independentemente do pai e um do outro.
O agente pai precisando apenas de file_edit para si mesmo, já que seu próprio trabalho é apenas escrever o resumo combinado.
Subtarefas independentes e de formato semelhante (auditar pacotes não relacionados) como o caso mais claro para delegação.

Mergulho Profundo

Como Funciona

Um subagente é definido com um name (nome), uma description (descrição) que o modelo pai usa para decidir quando invocá-lo, e suas próprias allowed_tools (ferramentas permitidas)/tool_config (configuração de ferramentas).
Do loop de uso de ferramentas do pai, invocar um subagente se parece com qualquer outra chamada de ferramenta: o pai decide chamá-lo, o SDK executa o loop interno do próprio subagente até a conclusão, e o resultado retorna como uma observação.
O subagente executa seu próprio ciclo de decidir-agir-observar internamente, com sua própria janela de contexto que começa limpa para essa invocação e não carrega o histórico completo do pai por padrão.
Apenas o resultado final do subagente cruza de volta para o contexto do pai, não suas chamadas de ferramentas intermediárias ou raciocínio; esta é a propriedade de isolamento que mantém o contexto do pai limpo.
Como cada invocação de subagente é autônoma, subagentes independentes podem ser despachados e aguardados concorrentemente, enquanto um subagente cuja tarefa depende da saída de outro subagente deve rodar depois dele.

Quando Delegar vs. Adicionar uma Ferramenta

Sinal	Favorece	Razão
A tarefa precisa de mais uma capacidade, sem exploração independente	Adicionar uma ferramenta	Mais simples; sem necessidade de limite de contexto extra
A tarefa é uma subtarefa autônoma com sua própria exploração	Subagente	Mantém o ruído exploratório fora do contexto do pai
Múltiplas subtarefas semelhantes em entradas independentes	Subagentes (um por entrada)	Permite execução paralela
A subtarefa precisa de um escopo de ferramentas mais restrito ou diferente do pai	Subagente	O escopo da ferramenta é por subagente, não compartilhado

Notas de Python

# A descrição de um subagente é o que o modelo pai lê para decidir
# quando invocá-lo - trate-a como uma descrição de ferramenta, não um comentário.
SubagentConfig(
    name="test-runner",
    description="Executa a suíte de testes do projeto e relata apenas os testes falhos.",
    allowed_tools=["bash"],
    tool_config={"bash": {"allowed_commands": ["pytest"]}},
)

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Descrição
`name`	`str`	Identificador que o pai usa para invocar este subagente
`description`	`str`	Diz ao modelo pai quando este subagente se aplica
`allowed_tools`	`list[str]`	Escopo de ferramentas para este subagente, independente do pai
`tool_config`	`dict`	Escopo por ferramenta para as ferramentas deste subagente

Armadilhas

Delegar uma tarefa que não é realmente independente. Dividir uma tarefa com dependências reais entre dois subagentes força você a sequenciá-los manualmente e passar resultados entre eles. Correção: divida tarefas apenas em limites genuinamente independentes; mantenha etapas dependentes em um agente ou em sequência.
Escrever uma descrição vaga de subagente. Uma descrição como "agente auxiliar" não dá ao modelo pai nenhum sinal para quando invocá-lo. Correção: escreva descrições da mesma forma que escreveria uma descrição de ferramenta: específica, orientada para a ação e com escopo para um trabalho.
Assumir que um subagente vê o histórico completo do pai. Subagentes normalmente começam com um contexto limpo para sua invocação, não toda a conversa do pai. Correção: passe explicitamente qualquer contexto que o subagente realmente precise no prompt que você dá a ele.
Dividir excessivamente uma tarefa simples em muitos subagentes. Cada invocação de subagente adiciona sobrecarga (um contexto limpo, um loop interno completo); uma tarefa simples o suficiente para uma chamada de ferramenta não precisa de um subagente. Correção: reserve subagentes para subtarefas genuinamente independentes e não triviais.
Conceder a um subagente o escopo completo de ferramentas do pai por padrão. Copiar allowed_tools do pai para todos os subagentes anula o propósito de escopar o trabalho de forma restrita. Correção: escope cada subagente apenas para o que seu trabalho específico requer.
Não lidar com uma falha de subagente. Se o loop interno de um subagente falhar ou atingir o tempo limite, o pai precisa decidir o que fazer com um resultado incompleto. Correção: trate os resultados do subagente como qualquer outro resultado de ferramenta que pode falhar e lide com esse caso em seu prompt ou lógica de aplicativo.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Um único agente com mais ferramentas	A tarefa precisa de mais uma capacidade, não exploração independente	A subtarefa inundaria o contexto com raciocínio irrelevante
Chamadas de ferramentas sequenciais em um agente	As etapas dependem genuinamente da saída umas das outras	As etapas são independentes e poderiam ser executadas concorrentemente
Chamadas `query()` de nível superior separadas	Subtarefas são totalmente não relacionadas, sem tarefa pai compartilhada	Subtarefas fazem parte de uma tarefa pai coerente que precisa de um resultado combinado

FAQs

O que exatamente um subagente isola?

Sua própria janela de contexto, separada da do pai.
Seu próprio escopo de ferramentas, independente de allowed_tools do pai.
Seu raciocínio intermediário e chamadas de ferramentas, que nunca aparecem no contexto do pai, apenas o resultado final.

Como o pai decide quando invocar um subagente?

Da mesma forma que decide chamar qualquer ferramenta: o modelo lê a description do subagente junto com a conversa e escolhe invocá-lo quando a tarefa corresponde.

Subagentes podem rodar em paralelo?

Sim, quando são independentes uns dos outros. Subagentes cujas tarefas não dependem da saída uns dos outros podem ser despachados e aguardados concorrentemente.

Um subagente vê o histórico de conversas do pai?

Não por padrão; ele normalmente começa com um contexto limpo para sua própria invocação. Passe explicitamente qualquer contexto necessário no prompt que você dá ao subagente.

Um subagente pode ter seus próprios subagentes?

Quais ferramentas um subagente pode usar?

Qual a diferença entre delegar para um subagente e apenas chamar uma ferramenta?

Quando uma tarefa é pequena demais para um subagente?

Quando é uma ação única e simples que uma chamada de ferramenta direta resolveria igualmente bem; a sobrecarga de um contexto limpo e um loop interno não vale a pena para etapas triviais.

O que acontece se a tarefa de um subagente falhar?

Posso limitar quantos subagentes rodam ao mesmo tempo?

Relacionados

O Modelo Mental do Claude Agent SDK - como os subagentes se encaixam no loop conceitualmente
Habilitando Ferramentas de Edição de Arquivo, Bash e Web no Agent SDK - escopo de ferramentas, aplicável por subagente também
Referência de Opções de Configuração do Claude Agent SDK - comparando subagentes e outras opções
Adicionando Checkpoints Human-in-the-Loop a um Fluxo de Trabalho do Agent SDK - checkpoints dentro do trabalho delegado
Melhores Práticas do Claude Agent SDK - orientação de produção sobre escopo e delegação

Versões da Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o Claude Agent SDK (última versão, Python e TypeScript). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.

Delegando Trabalho para Subagentes no Claude Agent SDK

Buscar na documentação

Delegando Trabalho para Subagentes no Claude Agent SDK