SpyBara
Go Premium

agent-sdk/subagents.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

87 added, 75 removed.

2026
Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Subagentes no SDK

Defina e invoque subagentes para isolar contexto, executar tarefas em paralelo e aplicar instruções especializadas em suas aplicações Claude Agent SDK.

Subagentes são instâncias de agente separadas que seu agente principal pode gerar para lidar com subtarefas focadas. Use subagentes para isolar contexto para subtarefas focadas, executar múltiplas análises em paralelo e aplicar instruções especializadas sem sobrecarregar o prompt do agente principal.

Este guia explica como definir e usar subagentes no SDK usando o parâmetro agents.

Visão geral

Você pode criar subagentes de três maneiras:

  • Programaticamente: use o parâmetro agents em suas opções query() (TypeScript, Python)
  • Baseado em sistema de arquivos: defina agentes como arquivos markdown em diretórios .claude/agents/ (veja definindo subagentes como arquivos)
  • Propósito geral integrado: Claude pode invocar o subagente integrado general-purpose a qualquer momento via a ferramenta Agent sem você definir nada

Este guia se concentra na abordagem programática, que é recomendada para aplicações SDK.

Quando você define subagentes, Claude determina se deve invocá-los com base no campo description de cada subagente. Escreva descrições claras que expliquem quando o subagente deve ser usado, e Claude delegará automaticamente tarefas apropriadas. Você também pode solicitar explicitamente um subagente pelo nome em seu prompt (por exemplo, "Use o agente code-reviewer para...").

Benefícios de usar subagentes

Isolamento de contexto

Cada subagente é executado em sua própria conversa nova. Chamadas de ferramentas intermediárias e resultados permanecem dentro do subagente; apenas sua mensagem final retorna ao pai. Veja O que subagentes herdam para saber exatamente o que está no contexto do subagente.

Exemplo: um subagente research-assistant pode explorar dezenas de arquivos sem que nenhum desse conteúdo se acumule na conversa principal. O pai recebe um resumo conciso, não cada arquivo que o subagente leu.

Paralelização

Múltiplos subagentes podem ser executados simultaneamente, portanto subtarefas independentes terminam no tempo do mais lento em vez da soma de todos eles.

Exemplo: durante uma revisão de código, você pode executar os subagentes style-checker, security-scanner e test-coverage simultaneamente em vez de sequencialmente.

Instruções e conhecimento especializados

Cada subagente pode ter prompts de sistema personalizados com expertise específica, melhores práticas e restrições.

Exemplo: um subagente database-migration pode ter conhecimento detalhado sobre melhores práticas SQL, estratégias de reversão e verificações de integridade de dados que seriam ruído desnecessário nas instruções do agente principal.

Restrições de ferramentas

Subagentes podem ser limitados a ferramentas específicas, reduzindo o risco de ações não intencionais.

Exemplo: um subagente doc-reviewer pode ter acesso apenas às ferramentas Read e Grep, garantindo que possa analisar mas nunca modifique acidentalmente seus arquivos de documentação.

Criando subagentes

Defina subagentes diretamente em seu código usando o parâmetro agents. Este exemplo cria dois subagentes: um revisor de código com acesso somente leitura e um executor de testes que pode executar comandos. Claude invoca subagentes através da ferramenta Agent, portanto inclua Agent em allowedTools para aprovar automaticamente invocações de subagentes sem um prompt de permissão.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
async for message in query(
prompt="Review the authentication module for security issues",
options=ClaudeAgentOptions(
# Auto-approve these tools, including Agent for subagent invocation
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"code-reviewer": AgentDefinition(
# description tells Claude when to use this subagent
description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
# prompt defines the subagent's behavior and expertise
prompt="""You are a code review specialist with expertise in security, performance, and best practices.

When reviewing code:
- Identify security vulnerabilities
- Check for performance issues
- Verify adherence to coding standards
- Suggest specific improvements

Be thorough but concise in your feedback.""",
# tools restricts what the subagent can do (read-only here)
tools=["Read", "Grep", "Glob"],
# model overrides the default model for this subagent
model="sonnet",
),
"test-runner": AgentDefinition(
description="Runs and analyzes test suites. Use for test execution and coverage analysis.",
prompt="""You are a test execution specialist. Run tests and provide clear analysis of results.

Focus on:
- Running test commands
- Analyzing test output
- Identifying failing tests
- Suggesting fixes for failures""",
# Bash access lets this subagent run test commands
tools=["Bash", "Read", "Grep"],
),
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Configuração de AgentDefinition

Campo Tipo Obrigatório Descrição
description string Sim Descrição em linguagem natural de quando usar este agente
prompt string Sim O prompt do sistema do agente definindo seu papel e comportamento
tools string[] Não Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas
disallowedTools string[] Não Array de nomes de ferramentas a remover do conjunto de ferramentas do agente. Padrões de nível de servidor MCP também são aceitos: mcp__server ou mcp__server__* remove todas as ferramentas desse servidor, e mcp__* remove todas as ferramentas MCP de qualquer servidor
model string Não Substituição de modelo para este agente. Aceita um alias como 'fable', 'opus', 'sonnet', 'haiku', 'inherit', ou um ID de modelo completo. Padrão é o modelo principal se omitido
skills string[] Não Lista de nomes de skills para pré-carregar no contexto do agente na inicialização. Skills não listadas permanecem invocáveis através da ferramenta Skill
memory 'user' | 'project' | 'local' Não Fonte de memória para este agente
mcpServers (string | object)[] Não Servidores MCP disponíveis para este agente, por nome ou configuração inline
initialPrompt string Não Auto-enviado como o primeiro turno do usuário quando este agente é executado como o agente da thread principal. Ignorado quando o agente é invocado como um subagente
maxTurns number Não Número máximo de turnos agentic antes do agente parar
background boolean Não Executar este agente como uma tarefa de fundo não-bloqueante quando invocado
effort 'low' | 'medium' | 'high' | 'xhigh' | 'max' | number Não Nível de esforço de raciocínio para este agente
permissionMode PermissionMode Não Modo de permissão para execução de ferramentas dentro deste agente

No SDK Python, esses nomes de campo usam camelCase para corresponder ao formato de transmissão. Veja a referência AgentDefinition para detalhes.

Definição baseada em sistema de arquivos (alternativa)

Você também pode definir subagentes como arquivos markdown em diretórios .claude/agents/. Veja a documentação de subagentes Claude Code para detalhes sobre essa abordagem. Agentes definidos programaticamente têm precedência sobre agentes baseados em sistema de arquivos com o mesmo nome.

O que subagentes herdam

A janela de contexto de um subagente começa nova (sem conversa pai) mas não está vazia. O único canal do pai para o subagente é a string de prompt da ferramenta Agent, então inclua quaisquer caminhos de arquivo, mensagens de erro ou decisões que o subagente precise diretamente nesse prompt.

O subagente recebe O subagente não recebe
Seu próprio prompt do sistema (AgentDefinition.prompt) e o prompt da ferramenta Agent O histórico de conversa do pai ou resultados de ferramentas
CLAUDE.md do projeto (carregado via settingSources) Conteúdo de skill pré-carregado, a menos que listado em AgentDefinition.skills
Definições de ferramentas (herdadas do pai, ou o subconjunto em tools) O prompt do sistema do pai

Invocando subagentes

Invocação automática

Claude decide automaticamente quando invocar subagentes com base na tarefa e na description de cada subagente. Por exemplo, se você definir um subagente performance-optimizer com a descrição "Performance optimization specialist for query tuning", Claude o invocará quando seu prompt mencionar otimizar consultas.

Escreva descrições claras e específicas para que Claude possa corresponder tarefas ao subagente certo.

Invocação explícita

Para garantir que Claude use um subagente específico, mencione-o pelo nome em seu prompt:

"Use the code-reviewer agent to check the authentication module"

Isso ignora a correspondência automática e invoca diretamente o subagente nomeado.

Configuração dinâmica de agente

Você pode criar definições de agente dinamicamente com base em condições de tempo de execução. Este exemplo cria um revisor de segurança com diferentes níveis de rigor, usando um modelo mais poderoso para revisões rigorosas.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


# Factory function that returns an AgentDefinition
# This pattern lets you customize agents based on runtime conditions
def create_security_agent(security_level: str) -> AgentDefinition:
is_strict = security_level == "strict"
return AgentDefinition(
description="Security code reviewer",
# Customize the prompt based on strictness level
prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",
tools=["Read", "Grep", "Glob"],
# Key insight: use a more capable model for high-stakes reviews
model="opus" if is_strict else "sonnet",
)


async def main():
# The agent is created at query time, so each request can use different settings
async for message in query(
prompt="Review this PR for security issues",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
# Call the factory with your desired configuration
"security-reviewer": create_security_agent("strict")
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Detectando invocação de subagente

Subagentes são invocados via a ferramenta Agent. Para detectar quando um subagente é invocado, verifique blocos tool_use onde name é "Agent". Mensagens de dentro do contexto de um subagente incluem um campo parent_tool_use_id.

A estrutura de mensagem difere entre SDKs. Em Python, blocos de conteúdo são acessados diretamente via message.content. Em TypeScript, SDKAssistantMessage envolve a mensagem da API Claude, então o conteúdo é acessado via message.message.content.

Este exemplo itera através de mensagens transmitidas, registrando quando um subagente é invocado e quando mensagens subsequentes originam-se de dentro do contexto de execução desse subagente.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ToolUseBlock


async def main():
async for message in query(
prompt="Use the code-reviewer agent to review this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="Expert code reviewer.",
prompt="Analyze code quality and suggest improvements.",
tools=["Read", "Glob", "Grep"],
)
},
),
):
# Check for subagent invocation. Match both names: older SDK
# versions emitted "Task", current versions emit "Agent".
if hasattr(message, "content") and message.content:
for block in message.content:
if isinstance(block, ToolUseBlock) and block.name in (
"Task",
"Agent",
):
print(f"Subagent invoked: {block.input.get('subagent_type')}")

# Check if this message is from within a subagent's context
if hasattr(message, "parent_tool_use_id") and message.parent_tool_use_id:
print("  (running inside subagent)")

if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Retomando subagentes

Subagentes podem ser retomados para continuar de onde pararam. Subagentes retomados retêm seu histórico de conversa completo, incluindo todas as chamadas de ferramentas anteriores, resultados e raciocínio. O subagente continua exatamente de onde parou em vez de começar do zero.

Quando um subagente é concluído, o resultado da ferramenta Agent inclui um bloco de texto contendo agentId: <id>. Os agentes integrados Explore e Plan são de uma única execução e não retornam um agentId, então use um agente personalizado ou general-purpose quando você precisar retomar. Para retomar um subagente programaticamente:

  1. Capture o ID da sessão: Extraia session_id de mensagens durante a primeira query
  2. Extraia o ID do agente: Analise agentId do texto do resultado da ferramenta Agent
  3. Retome a sessão: Passe resume: sessionId nas opções da segunda query e inclua o ID do agente em seu prompt

O exemplo abaixo define um agente personalizado endpoint-finder. A primeira query o executa e captura o ID da sessão e ID do agente do resultado da ferramenta Agent, então a segunda query retoma a sessão para fazer uma pergunta de acompanhamento que requer contexto da primeira análise.

import asyncio
import re
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ToolResultBlock

AGENTS = {
"endpoint-finder": AgentDefinition(
description="Locates and catalogs API endpoints in a codebase.",
prompt="You find and document API endpoints. Report each endpoint's path, method, and handler.",
tools=["Read", "Grep", "Glob"],
)
}


def extract_agent_id(block: ToolResultBlock) -> str | None:
"""Extract agentId from an Agent tool result's text content."""
parts = block.content if isinstance(block.content, list) else [{"text": block.content}]
for part in parts:
if match := re.search(r"agentId:\s*([\w-]+)", part.get("text") or ""):
return match.group(1)
return None


async def main():
agent_id = None
session_id = None

# First invocation - run the endpoint-finder subagent
async for message in query(
prompt="Use the endpoint-finder agent to find all API endpoints in this codebase",
options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS),
):
# Capture session_id from ResultMessage (needed to resume this session)
if hasattr(message, "session_id"):
session_id = message.session_id
# Search tool results for the agentId trailer
for block in getattr(message, "content", None) or []:
if isinstance(block, ToolResultBlock):
agent_id = extract_agent_id(block) or agent_id
# Print the final result
if hasattr(message, "result"):
print(message.result)

# Second invocation - resume and ask follow-up
if agent_id and session_id:
async for message in query(
prompt=f"Resume agent {agent_id} and list the top 3 most complex endpoints",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS, resume=session_id
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Transcrições de subagentes persistem independentemente da conversa principal:

  • Compactação de conversa principal: Quando a conversa principal se compacta, transcrições de subagentes não são afetadas. Elas são armazenadas em arquivos separados.
  • Persistência de sessão: Transcrições de subagentes persistem dentro de sua sessão. Você pode retomar um subagente após reiniciar Claude Code retomando a mesma sessão.
  • Limpeza automática: Transcrições são limpas com base na configuração cleanupPeriodDays (padrão: 30 dias).

Restrições de ferramentas

Subagentes podem ter acesso restrito a ferramentas via o campo tools:

  • Omita o campo: agente herda todas as ferramentas disponíveis (padrão)
  • Especifique ferramentas: agente pode usar apenas ferramentas listadas

Este exemplo cria um agente de análise somente leitura que pode examinar código mas não pode modificar arquivos ou executar comandos.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
async for message in query(
prompt="Analyze the architecture of this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"code-analyzer": AgentDefinition(
description="Static code analysis and architecture review",
prompt="""You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.""",
# Read-only tools: no Edit, Write, or Bash access
tools=["Read", "Grep", "Glob"],
)
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

Combinações comuns de ferramentas

Caso de uso Ferramentas Descrição
Análise somente leitura Read, Grep, Glob Pode examinar código mas não modificar ou executar
Execução de testes Bash, Read, Grep Pode executar comandos e analisar saída
Modificação de código Read, Edit, Write, Grep, Glob Acesso completo de leitura/escrita sem execução de comandos
Acesso completo Todas as ferramentas Herda todas as ferramentas do pai (omita o campo tools)

Escalar com fluxos de trabalho dinâmicos

Subagentes funcionam bem para algumas tarefas delegadas por turno. Para execuções que coordenam dezenas a centenas de agentes, use a ferramenta Workflow, que move a orquestração para um script que o runtime executa fora do contexto da conversa. Veja fluxos de trabalho dinâmicos para como fluxos de trabalho diferem da delegação de subagentes turno a turno.

A ferramenta Workflow está disponível no TypeScript Agent SDK v0.3.149 e posterior. Inclua Workflow em allowedTools para aprovar automaticamente execuções de fluxo de trabalho. Os esquemas de entrada e saída da ferramenta estão listados na referência TypeScript.

Troubleshooting

Claude não delegando para subagentes

Se Claude completa tarefas diretamente em vez de delegar para seu subagente:

  1. Verifique se as invocações de Agent são aprovadas: inclua Agent em allowedTools para aprovar automaticamente chamadas de subagentes. Sem isso, as invocações de Agent caem no seu callback canUseTool ou, no modo dontAsk, são negadas
  2. Use prompting explícito: mencione o subagente pelo nome em seu prompt (por exemplo, "Use o agente code-reviewer para...")
  3. Escreva uma descrição clara: explique exatamente quando o subagente deve ser usado para que Claude possa corresponder tarefas apropriadamente

Agentes baseados em sistema de arquivos não carregando

Agentes definidos em .claude/agents/ são carregados apenas na inicialização. Se você criar um novo arquivo de agente enquanto Claude Code está em execução, reinicie a sessão para carregá-lo.

Windows: falhas de prompt longo

No Windows, subagentes com prompts muito longos podem falhar devido a limites de comprimento de linha de comando (8191 caracteres). Mantenha prompts concisos ou use agentes baseados em sistema de arquivos para instruções complexas.