Building Multi-Agent Systems

A primeira vez que executei meu harness SDLC e vi oito agentes reescreverem oito módulos de aprendizagem independentes em paralelo — cada um no seu próprio worktree git, nenhum ciente dos outros — o resultado chegou em menos de 45 minutos. Executar o mesmo spec sequencialmente leva cerca de três horas e eventualmente esbarra em limites de contexto.

Esse harness é agora a espinha dorsal de produção de como gerencio grandes reescritas. Ele roda num Mac Mini atrás de um Cloudflare Tunnel, despacha tarefas em ondas ordenadas por dependência e mescla resultados em main em uma sequência controlada. Este módulo é sobre os padrões por trás disso — não como arquitetura abstrata, mas como decisões que tomei após encontrar problemas reais.

Pense em um único agente como um freelancer habilidoso que só pode pegar um projeto por vez. Um sistema multi-agente é uma empresa coordenada: especialistas trabalham em paralelo em problemas diferentes, e um gerente de projeto (o orquestrador) distribui trabalho, aguarda resultados e integra saídas em uma ordem definida.

Onde Agentes Únicos Quebram

Três problemas que me empurraram para padrões multi-agentes:

Limites de contexto. Uma grande reescrita de spec tem 10 tarefas. Um agente acumula contexto de cada tarefa que faz, eventualmente degradando em qualidade e atingindo limites de token. Oito agentes paralelos, cada um com escopo de uma tarefa, permanecem focados.

Paralelismo. As tarefas 2 a 8 do meu harness SDLC são independentes (cada uma toca arquivos diferentes). Executá-las sequencialmente significa que a tarefa 3 espera a tarefa 2 terminar mesmo que não compartilhem nada. A execução paralela elimina esse tempo morto.

Isolamento de falhas. Se a tarefa 5 falha, quero tentar novamente apenas a tarefa 5 — não re-executar todo o spec. Agentes que cada um é dono de uma tarefa tornam a lógica de retry trivial.

Ponto de Verificação no Meio do Módulo

Antes de continuar lendo: No seu próprio trabalho, nomeie um processo recorrente que tem subtarefas independentes que não compartilham arquivos. Essa é a juntura onde padrões multi-agentes compensam. Se você ainda não consegue nomear um, o restante deste módulo aguçará o que procurar.

Sub-agentes não são threads em segundo plano — eles são sessões Claude separadas, cada uma com uma janela de contexto nova. Eles não sabem nada sobre sua conversa, seu projeto ou um ao outro. O orquestrador é a fonte da verdade; agentes são especialistas que executam exatamente o que lhes é dito e escrevem saídas em locais conhecidos.

Aqui está como a coordenação funciona no meu harness SDLC:

A regra crucial: agentes coordenam apenas através do orquestrador. Eles não conversam diretamente entre si. Suas saídas — commits git e relatórios estruturados — são o único canal de volta ao orquestrador. Tentar ter agentes se comunicando peer-to-peer cria condições de corrida que são quase impossíveis de depurar.

Uma Analogia

Imagine cinco equipes de construção construindo asas separadas do mesmo edifício. Cada equipe trabalha a partir de um trecho de projeto cobrindo apenas sua asa. O gerente de projeto mantém o projeto mestre e inspeciona cada asa antes de integrá-la à estrutura geral. As equipes não entram nas asas umas das outras para fazer ajustes.

Worktrees paralelos funcionam exatamente assim. Cada agente tem sua própria cópia do repositório, trabalha independentemente, e o orquestrador mescla resultados em uma ordem fixa.

Antes de escrever qualquer YAML ou código, responda a três perguntas: quais arquivos esse agente lê, quais arquivos ele escreve e o que ele está explicitamente proibido de tocar?

No meu harness SDLC, cada agente de implementação recebe:

• O trecho do spec para sua única tarefa atribuída (não o spec completo)
• O caminho absoluto para seu worktree dedicado
• Uma restrição explícita: editar apenas arquivos no caminho do seu worktree

Essa restrição previne os conflitos de merge que fizeram duas execuções paralelas precoces exigirem intervenção manual para desembaraçar.

O campo description é o que o orquestrador lê para decidir quando delegar. Torne-o concreto: triggers, entradas esperadas e restrições de propriedade.

O Contrato de Comunicação

O único canal de um sub-agente de volta ao orquestrador é sua saída — arquivos escritos em caminhos conhecidos e um commit estruturado. No meu harness, cada agente escreve um relatório em um local previsível e então commita. O orquestrador lê esse relatório para determinar se passa ou tenta novamente.

Um meta-agente é um agente cujo trabalho é gerar configuração para outros agentes. Em vez de escrever cada YAML de sub-agente manualmente, você descreve o que precisa e um meta-agente produz uma configuração completa e pronta para uso.

Na prática uso isso quando um projeto introduz um novo tipo de tarefa que ainda não automatizei. Em vez de projetar a configuração do agente manualmente, descrevo a tarefa a um meta-agente e itero em sua saída.

O padrão de meta-agente é mais útil para bootstrapping. Uma vez que uma configuração de sub-agente esteja funcionando bem, ela raramente precisa mudar. Pense no meta-agente como um acelerador de configuração pontual, não uma dependência de tempo de execução.

Este é o padrão central do meu harness SDLC. As tarefas são agrupadas em ondas onde todas as tarefas de uma onda são independentes. O orquestrador lança todas as tarefas de uma onda em paralelo, aguarda todas completarem e então mescla resultados em ordem de número de tarefa antes da próxima onda começar.

O detalhe chave: merge_wave_results mescla em ordem de número de tarefa, não em ordem de conclusão. Isso torna o resultado do merge determinístico — essencial quando tarefas podem tocar arquivos de configuração sobrepostos.

Padrão 2: Pipeline Sequencial

Quando as tarefas têm dependências explícitas — a tarefa B precisa da saída da tarefa A — execute-as sequencialmente. Meu harness usa isso dentro de uma onda para tarefas estruturais que devem pousar antes dos rewrites de módulo começarem:

O limite de onda é sua primitiva de sequenciamento. Use-a quando trabalho anterior cria uma dependência que trabalho posterior consome.

Padrão 3: Orquestrador como Tomador de Decisão

O orquestrador em si pode chamar o SDK do Anthropic para lidar com modos de falha que lógica if/else baseada em regras perderia. Quando uma tarefa falha, em vez de fazer correspondência de padrões em strings de erro, peço ao Claude Haiku para classificar a falha e recomendar uma estratégia de retry:

Uma triagem baseada em regras só captura falhas que você antecipou no tempo de design. Um LLM pode classificar mensagens de erro novas usando raciocínio geral — útil na primeira vez que você encontra um modo de falha que não planejou.

Reflexão

Considere um spec onde as tarefas 3 e 5 ambas modificam metadata.json. Você poderia executá-las em paralelo, mas o merge vai conflitar. Quais são suas opções?

• Dividir a responsabilidade para que apenas uma tarefa seja dona desse arquivo?
• Serializar essas duas tarefas em ondas separadas?
• Tornar a escrita de arquivo idempotente para que qualquer ordem de merge produza o mesmo resultado?

Não há uma única resposta certa — mas pensar nisso antes de começar é muito mais barato do que desembaraçar um conflito de merge depois.

Quando oito agentes estão escrevendo em oito worktrees em paralelo, você precisa saber o que está acontecendo sem ler oito janelas de terminal separadas.

O Que Rastrear

Meu harness registra quatro eventos por agente: started, checkpoint-passed, completed e merged. Quatro eventos por tarefa são suficientes para reconstruir a linha do tempo completa de qualquer execução e detectar qual agente travou ou falhou.

Uma linha JSON por evento. Sem banco de dados, sem servidor, sem dependências. Para ver o que aconteceu, leia o arquivo JSONL. Para construir uma linha do tempo, ordene por ts. Para encontrar agentes travados, procure por started sem completed correspondente.

Detecção de Conflito

O modo de falha multi-agente mais comum que encontro é dois agentes modificando o mesmo caminho de arquivo. A correção é arquitetural (divisões de tarefa melhores), mas a detecção é simples:

Usando Claude Haiku para Resumos de Log

Quando uma onda produz cinquenta páginas de logs, uso o Claude Haiku para produzir um resumo de um parágrafo de cada sessão de agente. Ao preço atual, resumir uma execução de oito agentes custa bem menos de $0,05 — menos do que o custo cognitivo de ler os logs manualmente.

Você agora conhece os padrões centrais. Este projeto pede que você construa um wave runner mínimo: despachar duas tarefas independentes em paralelo, aguardar ambas completarem e mesclar resultados em ordem de id de tarefa.

Critérios de Aceitação

1. Define uma dataclass Task com id, spec_excerpt e output_path
2. run_task(task) simula trabalho async e escreve um arquivo de resultado em output_path
3. run_wave(tasks) despacha todas as tarefas em paralelo usando asyncio.gather
4. Os resultados são ordenados por task.id antes do merge — independentemente da ordem de conclusão
5. Se qualquer tarefa lançar uma exceção, a onda falha rápido e não chama merge_results

Código Inicial

Dicas escalonadas:

• Dica 1: asyncio.gather(*[run_task(t) for t in tasks], return_exceptions=True) executa todas as tarefas e captura exceções como valores de retorno em vez de lançá-las.
• Dica 2: Verifique isinstance(r, Exception) na lista de resultados para detectar falhas antes do merge.
• Dica 3: sorted(results, key=lambda r: r["task_id"]) coloca os resultados em ordem de merge determinística.

Solução Trabalhada

A linha crítica é sorted(..., key=lambda r: r["task_id"]). asyncio.gather retorna resultados na ordem de conclusão, que é não-determinística. Ordenar por task id torna a ordem de merge reproduzível em cada execução.