Subagentes no 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 inchar 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 Task sem você definir nada

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

Quando você define subagentes, Claude decide 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

Gerenciamento de contexto

Subagentes mantêm contexto separado do agente principal, prevenindo sobrecarga de informações e mantendo interações focadas. Este isolamento garante que tarefas especializadas não poluam o contexto da conversa principal com detalhes irrelevantes.

Exemplo: um subagente research-assistant pode explorar dezenas de arquivos e páginas de documentação sem poluir a conversa principal com todos os resultados intermediários de busca, retornando apenas os achados relevantes.

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

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(
            # Task tool is required for subagent invocation
            allowed_tools=["Read", "Grep", "Glob", "Task"],
            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

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 do Claude Code para detalhes sobre esta abordagem. Agentes definidos programaticamente têm precedência sobre agentes baseados em sistema de arquivos com o mesmo nome.

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 correto.

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"

Isto 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", "Task"],
            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 Task. Para detectar quando um subagente é invocado, procure por blocos tool_use com name: "Task". 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 daquele 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", "Task"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Expert code reviewer.",
                    prompt="Analyze code quality and suggest improvements.",
                    tools=["Read", "Glob", "Grep"]
                )
            }
        )
    ):
        # Check for subagent invocation in message content
        if hasattr(message, 'content') and message.content:
            for block in message.content:
                if getattr(block, 'type', None) == 'tool_use' and block.name == 'Task':
                    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 ferramenta 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 Task. Para retomar um subagente programaticamente:

1. Capture o ID da sessão: Extraia session_id de mensagens durante a primeira consulta
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 consulta e inclua o ID do agente em seu prompt

O exemplo abaixo demonstra este fluxo: a primeira consulta executa um subagente e captura o ID da sessão e o ID do agente, então a segunda consulta 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', 'Task'] }
})) {
  // 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 Task 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', 'Task'], resume: sessionId }
  })) {
    if ('result' in message) console.log(message.result);
  }
}

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

• Compactação da 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 as 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", "Task"],
            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

Solução de problemas

Claude não delegando a subagentes

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

1. Inclua a ferramenta Task: subagentes são invocados via a ferramenta Task, então ela deve estar em allowedTools
2. Use prompting explícito: mencione o subagente pelo nome em seu prompt (por exemplo, "Use the code-reviewer agent to...")
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

• Subagentes do Claude Code: documentação abrangente de subagentes incluindo definições baseadas em sistema de arquivos
• Visão geral do SDK: começando com o Claude Agent SDK