SpyBara
Go Premium

agent-sdk/subagents.md 2026-05-07 22:59 UTC to 2026-05-08 22:00 UTC

601 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

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, acelerando dramaticamente fluxos de trabalho complexos.

Exemplo: durante uma revisão de código, você pode executar os subagentes style-checker, security-scanner e test-coverage simultaneamente, reduzindo o tempo de revisão de minutos para segundos.

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

Definição programática (recomendada)

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. A ferramenta Agent deve ser incluída em allowedTools já que Claude invoca subagentes através da ferramenta Agent.

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(
# Agent tool is required 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
model string Não Substituição de modelo para este agente. Aceita um alias como 'sonnet', 'opus', '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
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.

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


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 getattr(block, "type", None) == "tool_use" 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, Claude recebe seu ID de agente no resultado da ferramenta Agent. 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 conteúdo da mensagem
  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 demonstra esse fluxo: a primeira query executa um subagente e captura o ID da sessão e ID do agente, então a segunda query retoma a sessão para fazer uma pergunta de acompanhamento que requer contexto da primeira análise.

import { query, type SDKMessage } from "@anthropic-ai/claude-agent-sdk";

// Helper to extract agentId from message content
// Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.)
function extractAgentId(message: SDKMessage): string | undefined {
if (!("message" in message)) return undefined;
// Stringify the content so we can search it without traversing nested blocks
const content = JSON.stringify(message.message.content);
const match = content.match(/agentId:\s*([a-f0-9-]+)/);
return match?.[1];
}

let agentId: string | undefined;
let sessionId: string | undefined;

// First invocation - use the Explore agent to find API endpoints
for await (const message of query({
prompt: "Use the Explore agent to find all API endpoints in this codebase",
options: { allowedTools: ["Read", "Grep", "Glob", "Agent"] }
})) {
// Capture session_id from ResultMessage (needed to resume this session)
if ("session_id" in message) sessionId = message.session_id;
// Search message content for the agentId (appears in Agent tool results)
const extractedId = extractAgentId(message);
if (extractedId) agentId = extractedId;
// Print the final result
if ("result" in message) console.log(message.result);
}

// Second invocation - resume and ask follow-up
if (agentId && sessionId) {
for await (const message of query({
prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`,
options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], resume: sessionId }
})) {
if ("result" in message) console.log(message.result);
}
}

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)

Troubleshooting

Claude não delegando para subagentes

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

  1. Inclua a ferramenta Agent: subagentes são invocados via a ferramenta Agent, então ela deve estar em allowedTools
  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.

Documentação relacionada