Delegando Trabalho para Subagentes no Claude Agent SDK
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
bashefile_editde cada subagente independentemente do pai e um do outro. - O agente pai precisando apenas de
file_editpara 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), umadescription(descrição) que o modelo pai usa para decidir quando invocá-lo, e suas própriasallowed_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_toolsdo 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_toolsdo 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.