CH 13 · Subagentes e Orquestração Multi-Agent

Número de palavras~3.800 palavrasTempo~22 minPré-requisitoCH 08, CH 11NívelReproduzível

Objetivo do capítulo

Quando uma tarefa é grande demais ou emaranhada demais, em vez de deixar um único Agent ir até o fim, deixe-o dividir em algumas partes, enviar vários subagentes para trabalhar em paralelo, e reunir os resultados quando prontos. Este capítulo esclarece: por que multi-Agent, como são os subagentes do dsh, e depois coloca a mão na massa rodando "dividir tarefa → delegar em paralelo → mesclar resultados", e por fim coloca a família completa de ferramentas no inventário.

Por que multi-Agent: três pontos críticos do single-threaded

Um Agent indo do início ao fim vai esbarrar em três problemas:

Ponto crítico	Sintoma
Poluição de contexto	No meio da tarefa, as etapas iniciais, resultados intermediários e erros se acumulam na mesma sessão, e o modelo cada vez menos consegue distinguir qual informação é a mais importante agora
Impossibilidade de paralelizar	Pesquisar informação, escrever um rascunho, revisar código — três coisas só podem enfileirar, a próxima espera a anterior terminar
Desvia cada vez mais do rumo	Em tarefas longas o modelo facilmente fica preso descendo por um caminho errado, tentando de novo a mesma rota que falhou, queimando tokens

A mentalidade multi-Agent é exatamente o remédio: isolamento de contexto. Cada subagente carrega apenas o contexto relevante à sua tarefa; o agente principal divide, despacha e coleta. O consumo de tokens é controlável, e cada etapa pode ser revisada na Trajectory.

Um fato-chave: subagentes também são plugins

Primeiro, um alívio: subagentes não são algo separado que o dsh escondeu; eles são plugins — outra confirmação do "tudo é um plugin" do CH 08. E subagentes já são padrão nas ferramentas Agent atuais — Claude Code e Codex têm essa capacidade; a única diferença é que no dsh ainda existe como plugin: pegue se quiser, ou troque tudo se não quiser.

Na árvore de configuração, você pode ver um contrato de delegação ctx.subagents cujo único trabalho é registrar "quem pode ser um subagente". Então diferentes plugins provedores montam backends específicos sobre ele:

Plugin	O que executa
subagent-spawn-in-process	Um subagente in-process totalmente novo (contexto independente)
subagent-fork-in-process	"Deriva" um subagente a partir do histórico concluído da sessão pai
subagent-acp	Usa o Agent Client Protocol, aceita Agents compatíveis com ACP fora do processo
subagent-codex	Roda um Codex real (protocolo oficial app-server)
subagent-claude-code	Roda um Claude Code real (Agent SDK oficial)
subagent-dsh-sdk	Inicia outro Harness completo via o SDK TypeScript

O que o agente principal enxerga? São algumas "ferramentas visíveis ao modelo". Abra a árvore de configuração web, o padrão é:

Ferramenta	O que faz	Padrão
subagent	Despacha um subagente, modo continuable	on
subagent_fork	Despacha um subagente com a memória da sessão pai, one-shot	on
ralph	A cada rodada troca num novo subagente para avançar o mesmo objetivo	on
workflow	Escreve scripts para orquestrar em paralelo múltiplas sub-tarefas	off (não ativado por padrão)
send_message	Envia instruções de acompanhamento a um subagente específico	off (não ativado por padrão)
interrupt_agent	Interrompe a rodada atual de um subagente	off (não ativado por padrão)
list_agents	Lista os subagentes atuais e seus estados	off (não ativado por padrão)

Portanto, fora da caixa, dá para chamar diretamente subagent, subagent_fork e ralph. As outras ferramentas estão desligadas por padrão e precisam ser ativadas manualmente, ou só são úteis no "modo continuable" — a próxima seção vai cobrir onde cada uma delas aparece.

spawn vs fork: duas "aberturas"

Os dois subagentes mais usados diferem em apenas um ponto: se levam o histórico da sessão pai junto.

• subagent (spawn): contexto totalmente novo. O subagente não sabe sobre o que o agente principal vinha conversando, ele só segue as instruções que você dá desta vez. Economiza tokens, adequado para tarefas independentes.
• subagent_fork (fork): herda a parte concluída da sessão pai. O subagente sabe "até onde a gente estava analisando" e pode continuar a partir dali. Custa um pouco mais pelo contexto repetido, adequado para tarefas que precisam se construir sobre conclusões anteriores.

Um detalhe que vale a pena notar: o dsh coloca "se herda ou não" diretamente na descrição da ferramenta — as descrições estilo spawn dizem "ele não consegue ver essa conversa", as estilo fork dizem "ele não consegue ver a turn em andamento". Ou seja, o próprio modelo sabe se deve repetir o contexto nas instruções.

Uma frase para lembrar

subagent é como paraquedar um colega novo, que só tem o briefing verbal da tarefa; subagent_fork é como colar a ata da reunião nele, "continue de onde paramos".

Mãos à obra: primeiros subagentes em paralelo

Em paralelo, iniciar três subagentes, cada um fazendo:

1. Organizar a estrutura do diretório packages/ do repositório deepseek-harness, e explicar o que cada família de capacidades faz;
2. Resumir os conceitos centrais cobertos pelo README raiz;
3. Encontrar a documentação relacionada a subagentes em docs/, e listá-la. Depois que os três terminarem, mesclar os resultados em um único resumo.

Note os três elementos dessa frase, faltar qualquer um vai causar caos:

Elemento	Por que é necessário
Regras de divisão da tarefa	Diz ao modelo "dividir em quais pedaços", senão ele só chuta por conta própria
Mecanismo de espera (esperar todos terminarem)	Sem isso, o agente principal pode começar a organizar resultados incompletos antes mesmo de um subagente terminar
Requisito de saída (mesclar em um resumo)	Sem isso, os três subagentes devolvem cada um um monte de texto bruto, e você tem que juntar manualmente

Depois de enviar, você pode ver na conversa que o modelo faz várias chamadas subagent em sequência — é ele despachando. No modo continuable padrão, o modelo "primeiro envia as paralelizáveis juntas, depois continua seu próprio trabalho", em vez de esperar o primeiro subagente retornar.

Se alguns subagentes terminarem mais cedo, tudo bem — o agente principal continua aguardando os restantes, e só começa a mesclar quando todos chegarem:

Foreground / Background / Continuable: três modos de execução

Subagentes não se resumem a "despachar e esperar o resultado". Por "se espera, se continua conversando" eles se dividem em três modos:

Modo	Quando usar	O que você vê
Foreground one-shot	O próximo passo depende imediatamente desse resultado	Espera o subagente retornar o texto final
Background job (one-shot background)	Não precisa esperar, colete depois	started background subagent job <id>, use job_output para coletar, job_kill para parar
Continuable subagent	Pode precisar enviar instruções de acompanhamento, vai e volta	started subagent <childId>, dá para mandar mensagens depois

O subagent padrão é o modo continuable: despachado para rodar em segundo plano por padrão, e o agente principal segue sua vida; quando o subagente termina, uma notificação de callback entrega "pronto, aqui está o resultado". O modelo só muda para espera em foreground quando o próximo passo realmente precisa do resultado.

Quando você quer mais controle sobre um subagente continuable, precisa ativar send_message (instruções de acompanhamento), interrupt_agent (interrompe a rodada atual, não destrói, dá para retomar), list_agents (lista subagentes e estados). Eles ficam off por padrão porque a maioria dos cenários não precisa deles — é uma "capacidade avançada, ative quando precisar".

workflow e ralph: duas ferramentas de "orquestração"

Além de "dividir em pedaços e rodar em paralelo", o dsh também tem dois tipos mais estruturados de orquestração, ambos plugins:

Ferramenta	O que faz	Adequada para
workflow	Deixa o modelo escrever um pequeno script de orquestração, distribuir sub-tarefas com agent() / parallel() / pipeline(), e por fim retornar um resultado	Grande volume de tarefas, estrutura fixa, precisa de controle preciso da ordem de execução (por exemplo analisar 10 documentos de uma vez)
ralph	A cada rodada troca num novo subagente para avançar o mesmo objetivo, com um relatório de handoff escrito no fim de cada rodada para a próxima rodada	Refinamento multi-rodada, fácil ficar preso em uma rotina, tarefas criativas ou de debug

ralph vem ativado por padrão (subagent usa spawn, máximo 64 rodadas). workflow está off por padrão — seu script roda numa thread separada, é uma "restrição de orquestração" não um sandbox de segurança, vale a pena ativar só para cenários em lote bem definidos.

::: tl;dr Paralelo do dia a dia → subagent; Para continuar com conclusões anteriores → subagent_fork; Lote estruturado → workflow (off por padrão); Refinamento iterativo anti-rotina → ralph. :::

Armadilhas comuns

Armadilha	Como evitar
Múltiplos subagentes escrevendo no mesmo arquivo ao mesmo tempo	Tarefas em paralelo devem priorizar leituras (pesquisar, analisar, revisar); para escritas, deixe o agente principal coletar todos os resultados e escrever de uma vez
Esqueceu de dizer "espere todos terminarem" nas instruções	Inclua o mecanismo de espera ao despachar, senão o agente principal pode começar a trabalhar com metade dos resultados
Tarefas divididas em granularidade fina demais	Cada subagente tem custo de inicialização; dividir uma tarefa de 5 minutos em 10 subagentes é na verdade mais lento; divida até "completar de forma independente uma coisa significativa"
Subagentes aninham infinitamente	A profundidade de delegação tem um teto (padrão 3, 0 significa proibido); manter uma topologia em estrela "agente principal → subagente" é o mais estável

O que você aprendeu neste capítulo

Você passa se conseguir completar os itens abaixo:

• [ ] Dizer os três pontos críticos de tarefas longas single-Agent, e o valor central do multi-Agent (isolamento de contexto)
• [ ] Saber que subagentes também são plugins: ctx.subagents é o contrato de delegação, spawn / fork são os dois backends mais usados
• [ ] Distinguir subagent (contexto totalmente novo) de subagent_fork (com o histórico concluído da sessão pai)
• [ ] Ter rodado pelo menos uma vez um "dividir tarefas + esperar todos terminarem + mesclar resultados" em paralelo, e visto a chamada subagent na Trajectory
• [ ] Dizer as diferenças entre os modos foreground, background job e continuable subagent
• [ ] Saber o que cada um faz: workflow, ralph, send_message, interrupt_agent, list_agents