Subagentes: use para isolar contexto, não para montar time de agentes

Subagente é uma chamada de modelo com janela de contexto própria, disparada pelo agente principal para resolver uma subtarefa e devolver só o resultado. O motivo número um para usar subagentes em 2026 não é montar um "time de agentes". É isolar contexto: tirar da janela do agente principal o lixo de busca, log e tentativa que ele não precisa carregar.

Essa virada é sutil, mas muda a arquitetura inteira.

Em 2024 todo mundo desenhava organograma: agente pesquisador, agente redator, agente revisor, agente gerente conversando entre si. Bonito no diagrama. Frágil em produção.

O que os times que estão rodando agente de verdade aprenderam é outra coisa: comece com um agente só. Adicione subagente quando a janela de contexto virar o gargalo. E escolha com cuidado o que o subagente enxerga quando nasce.

Neste post você vai ver quando um subagente se paga, a diferença entre os modos isolated e fork, e como implementar os dois num harness em PHP chamando a API do Claude direto, sem framework.

TL;DR

• O que é: subagente como ferramenta de isolamento de contexto, não como divisão de cargos.
• Stack/Modelos: PHP 8.3 + Laravel HTTP client + Claude Messages API (qualquer modelo com tool use).
• Custo/Acesso: chave paga da Anthropic. Multi-agente gasta cerca de 15x mais tokens que um chat, então o custo é o principal critério.
• Link útil: Organizing Context in a Multi-Agent Harness, da LangChain.

Por que subagente virou ferramenta de contexto, não de organograma

Em junho de 2025 a Cognition, do Devin, publicou um texto com título direto: Don't Build Multi-Agents. O argumento é simples e continua válido. Subagentes trabalhando em paralelo, cada um com uma visão parcial, tomam decisões que se contradizem. Dois princípios do texto:

• "Share context, and share full agent traces, not just individual messages."
• "Actions carry implicit decisions, and conflicting decisions carry bad results."

Ou seja: cada ação carrega uma decisão implícita. O subagente que escolheu um padrão de nomes não avisou o outro que escolheu outro. Na hora de juntar, quebra.

Na mesma semana a Anthropic publicou como construiu o sistema multi-agente do Research. Os números são bons: um Opus 4 orquestrando subagentes Sonnet 4 superou o Opus 4 sozinho em 90,2% na avaliação interna de pesquisa. Mas o mesmo post explica de onde vem o ganho. No BrowseComp, uso de tokens sozinho explica 80% da variância de performance. Subagente funciona porque dá ao sistema mais janelas de contexto para gastar em paralelo.

E o preço vem junto: agentes usam cerca de 4x mais tokens que um chat, sistemas multi-agente cerca de 15x. A própria Anthropic avisa que domínios em que todos os agentes precisam do mesmo contexto não são bom encaixe, e que "most coding tasks involve fewer truly parallelizable tasks than research".

Junte as duas visões e sai a regra que está virando consenso em 2026. O Modern Agent Harness Blueprint resume numa linha: "Use subagents for context isolation, not because 'multi-agent' sounds advanced."

Esse é o tipo de decisão que separa harness que aguenta produção de demo bonita, e é exatamente o que vamos abrir ao vivo no AI Engineering Lab 4ª Edição, dias 14 e 15 de novembro, das 9h às 13h: onde cortar o contexto, o que o subagente recebe e o que volta, com código rodando na tela.

Quando usar subagentes (e quando não usar)

O blueprint lista quatro motivos legítimos. Fora deles, um agente só com boas ferramentas resolve:

1. Exploração em paralelo. Pesquisar cinco fontes ao mesmo tempo, varrer três diretórios grandes.
2. Janela de contexto separada. A subtarefa gera muito ruído (busca, log, leitura de arquivo) e o agente principal só precisa da conclusão.
3. Prompt ou ferramentas especializadas. Um revisor que só pode ler, nunca escrever.
4. Fronteira de responsabilidade explícita. Quem decide o quê fica claro no código.

E os sinais de que você não precisa de subagente:

• A tarefa é sequencial e cada passo depende de decisões do anterior. Clássico de código.
• Os "agentes" precisariam compartilhar quase todo o contexto.
• Você está separando por cargo ("o agente de SQL", "o agente de frontend") e não por volume de contexto.

O teste prático: se o subagente devolve um resumo de 300 tokens depois de consumir 40 mil, ele se pagou. Se devolve quase tudo que leu, você só adicionou latência.

Isolated vs fork: os dois modos de contexto do subagente

Em setembro de 2026 a LangChain formalizou no Deep Agents uma escolha que todo harness faz, mesmo sem nome: o que o subagente recebe quando nasce. São dois modos.

O isolated é o padrão e o comportamento histórico: o subagente recebe "a fresh context window, receiving only the task description specified by the supervisor". O fork propaga o estado do supervisor, e o post diz que ele pode ser "faster and cheaper than isolated subagents" justamente porque o prefixo já está em cache.

A configuração no Deep Agents fica assim (trecho do post da LangChain):

subagents = [
    {
        "name": "fixer",
        "description": "Use when a problem has already been diagnosed and the remaining work is to implement and test the fix",
        "mode": "fork",
    },
    {
        "name": "reviewer",
        "description": "Use after an implementation is complete and needs an independent review",
        "mode": "isolated",
    },
]

A regra de escolha que sai do post é a parte que vale ouro: quem continua o trabalho usa fork, quem verifica usa isolated. Para o revisor, herdar o raciocínio do supervisor "can be counterproductive". Faz sentido. Se o revisor leu toda a justificativa do código, ele vai concordar com ela.

Mão na massa: subagente isolated e fork num harness PHP

Vamos implementar o padrão sem framework, direto na Messages API. A ideia é o agente principal ter uma tool delegate e o harness decidir, por tipo de subagente, se o contexto nasce zerado ou herdado.

Passo 1: declare a tool de delegação

O modelo não chama outro agente. Ele chama uma tool. Quem cria o subagente é o seu código.

$delegateTool = [
    'name' => 'delegate',
    'description' => 'Delega uma subtarefa a um subagente. Use "researcher" para buscas '
        . 'que geram muito ruído e "reviewer" para revisão independente de algo pronto. '
        . 'Você recebe apenas o resultado final, não o raciocínio intermediário.',
    'input_schema' => [
        'type' => 'object',
        'properties' => [
            'agent' => ['type' => 'string', 'enum' => ['researcher', 'reviewer', 'fixer']],
            'task'  => ['type' => 'string', 'description' => 'Tarefa completa e autocontida.'],
        ],
        'required' => ['agent', 'task'],
    ],
];

Repare na descrição da tool. Ela diz quando delegar. É ali que você evita o agente delegando tudo por reflexo.

Passo 2: rode o subagente com o modo de contexto certo

Cada tipo de subagente tem modo, prompt e ferramentas próprios. O reviewer é isolated e só lê. O fixer é fork.

use Illuminate\Support\Facades\Http;

class SubagentRunner
{
    private array $profiles = [
        'researcher' => ['mode' => 'isolated', 'tools' => ['web_search', 'read_file']],
        'reviewer'   => ['mode' => 'isolated', 'tools' => ['read_file']],
        'fixer'      => ['mode' => 'fork',     'tools' => ['read_file', 'write_file', 'run_tests']],
    ];

    public function run(string $agent, string $task, array $parentMessages): string
    {
        $profile = $this->profiles[$agent];

        $messages = $profile['mode'] === 'fork'
            // fork: herda o histórico do supervisor (prefixo igual = cache quente)
            ? [...$this->withoutPendingToolCall($parentMessages),
               ['role' => 'user', 'content' => "Você é um subagente. Tarefa: {$task}"]]
            // isolated: janela nova, só a tarefa
            : [['role' => 'user', 'content' => $task]];

        return $this->loop($agent, $messages, $profile['tools'], maxTurns: 15);
    }

    private function loop(string $agent, array $messages, array $tools, int $maxTurns): string
    {
        for ($turn = 0; $turn < $maxTurns; $turn++) {
            $response = Http::withHeaders([
                'x-api-key' => config('services.anthropic.key'),
                'anthropic-version' => '2023-06-01',
            ])->post('https://api.anthropic.com/v1/messages', [
                'model' => config('services.anthropic.model'),
                'max_tokens' => 4096,
                'system' => $this->systemPrompt($agent),
                'tools' => ToolRegistry::only($tools),
                'messages' => $messages,
            ])->throw()->json();

            if ($response['stop_reason'] !== 'tool_use') {
                return $this->finalText($response); // só isso volta pro supervisor
            }

            $messages[] = ['role' => 'assistant', 'content' => $response['content']];
            $messages[] = ['role' => 'user', 'content' => ToolRegistry::execute($response['content'], $tools)];
        }

        return "Subagente {$agent} parou no limite de {$maxTurns} turnos sem concluir.";
    }
}

Três detalhes que fazem diferença:

• Só o texto final volta. As 15 rodadas de busca morrem com o subagente. É aqui que mora o ganho de contexto.
• No fork, remova a tool call pendente do histórico antes de passar adiante. A LangChain faz o mesmo: "The trailing tool call is excised". Sem isso, a conversa herdada fica inválida.
• Limite de turnos sempre. Subagente sem teto é custo sem teto.

Passo 3: force o subagente a devolver resumo, não transcrição

O erro mais comum é o subagente devolver tudo que leu. Aí você pagou 15x em tokens e não isolou nada. Coloque o contrato de saída no system prompt:

Você é um subagente de pesquisa. Ao terminar, responda SOMENTE com:
1. Conclusão em até 5 linhas.
2. Fontes usadas (caminho ou URL), uma por linha.
3. O que você NÃO conseguiu verificar.
Não inclua trechos longos de arquivo nem logs. O agente principal não precisa deles.

O item 3 é o mais importante. O supervisor precisa saber o que ficou de fora, senão ele assume que o subagente cobriu tudo.

Passo 4: verificador sempre isolated e com ferramenta restrita

O reviewer só tem read_file. Não pode corrigir, só apontar. E nasce isolated, sem ler a justificativa do supervisor. É a mesma lógica de code review humano: quem revisa não deveria ter escrito.

Limitações e pontos de atenção

• Custo. Multi-agente gasta cerca de 15x os tokens de um chat. Meça antes e depois. Se a qualidade não subiu, volte para agente único.
• Decisões implícitas perdidas. No modo isolated o subagente não sabe o que o supervisor já decidiu. Se a tarefa depende disso, ou você escreve na descrição da tarefa, ou usa fork.
• Fork herda vieses. O fork carrega o raciocínio do supervisor, inclusive o errado. Nunca use fork para revisar.
• Escrita em paralelo. Dois subagentes escrevendo nos mesmos arquivos é a receita do conflito que a Cognition descreveu. Paralelo para ler, sequencial para escrever.
• Segurança. Subagente com ferramenta de escrita ou rede é superfície de ataque igual ao agente principal. Restrinja ferramentas por perfil, como no Passo 2.

FAQ rápido

Subagente é a mesma coisa que sistema multi-agente?

Não necessariamente. Multi-agente costuma significar agentes com papéis fixos conversando entre si. Subagente, no sentido usado aqui, é uma chamada efêmera disparada pelo agente principal via tool, com contexto controlado pelo harness. Ele nasce, resolve, devolve o resultado e morre.

Quando usar fork e quando usar isolated?

Fork quando o subagente continua um trabalho que depende do que o supervisor já descobriu, como implementar uma correção já diagnosticada. Isolated quando você quer uma visão independente ou a subtarefa é autocontida, como pesquisar ou revisar. Na dúvida, isolated é o padrão mais seguro.

Subagente economiza tokens?

Economiza tokens na janela do agente principal, não no total. O total sobe, às vezes muito. O ganho é qualidade: o agente principal raciocina sobre resumos em vez de afogar em ruído. O fork reduz parte do custo porque reaproveita o cache do prefixo.

O Claude Code tem subagentes?

Tem. Você define subagentes em .claude/agents/, cada um com prompt, ferramentas permitidas e janela de contexto própria. O padrão pesquisador, executor e validador está destrinchado em Subagentes na prática.

Conclusão

Subagente não é cargo. É janela de contexto.

A pergunta certa não é "quantos agentes meu sistema tem", é "o que entra e o que sai de cada janela". Comece com um agente. Adicione subagente quando o ruído de uma subtarefa estiver poluindo o raciocínio principal. Use isolated para pesquisar e revisar, fork para continuar trabalho. E exija resumo, não transcrição.

O próximo passo dessa tendência já está aparecendo: modelos melhores decidindo sozinhos quando delegar, com o harness só oferecendo os modos. Isso conversa direto com o que discutimos em Harness minimalista: quanto mais esperto o modelo, menos o harness decide por ele.