Phase 19 - Lesson 10

Capstone 10 — Equipe de Engenharia de Software Multiagente

A arquitetura de fábrica do SWE-AF, o prompting baseado em papéis do MetaGPT, o gráfico de atores tipados do AutoGen 0.4, o Devin da Cognition e os Droids da Factory convergiram para o mesmo formato em 2026: um arquiteto planeja, N programadores trabalham em worktrees paralelas, um revisor controla as aprovações e um testador verifica. Worktrees paralelas convertem tempo real (wall-clock) em rendimento (throughput). O estado compartilhado e os protocolos de entrega (handoff) tornam-se a superfície de falha. O capstone consiste em construir a equipe, avaliar no SWE-bench Pro e relatar quais handoffs falham e com que frequência.

Tipo: Capstone Linguagens: Python / TypeScript (agentes), Shell (scripts de worktree) Pré-requisitos: Fase 11 (engenharia de LLM), Fase 13 (ferramentas), Fase 14 (agentes), Fase 15 (autônomos), Fase 16 (multiagentes), Fase 17 (infraestrutura) Fases exercitadas: P11 · P13 · P14 · P15 · P16 · P17 Tempo: 40 horas

Problema

As estruturas de codificação baseadas em um único agente atingem um limite em tarefas grandes. Não porque algum agente individual seja fraco, mas porque um contexto de 200k tokens não consegue conter um plano de arquitetura mais quatro trechos de código paralelos mais os comentários do revisor mais a saída dos testes. Fábricas multiagentes dividem o problema: um arquiteto é o dono do plano, os programadores são os donos da implementação em worktrees paralelas, um revisor controla a aprovação e um testador verifica. A arquitetura de "fábrica" do SWE-AF, as funções do MetaGPT e o gráfico de atores tipados do AutoGen — todos os três enquadramentos descrevem o mesmo formato.

A superfície de falha é a entrega (handoff). O arquiteto planeja algo que os programadores não conseguem implementar. Os programadores produzem diffs conflitantes. O revisor aprova uma correção alucinada. O testador entra em concorrência com um programador que ainda está escrevendo. Você construirá uma dessas equipes, a executará em 50 problemas do SWE-bench Pro, rastreará cada entrega (handoff) e publicará o relatório pós-mortem (post-mortem).

Concept

Os papéis são agentes tipados. O Arquiteto (Claude Opus 4.7) lê o problema, escreve um plano e o divide em subtarefas com interfaces explícitas. Os Programadores (Claude Sonnet 4.7, N instâncias paralelas, cada uma em um git worktree + sandbox Daytona) implementam as subtarefas de forma independente. O Revisor (GPT-5.4) lê o diff mesclado e aprova ou solicita alterações específicas. O Testador (Gemini 2.5 Pro) executa a suíte de testes de forma isolada e relata aprovação/falha com artefatos.

A comunicação é feita por meio de um quadro de tarefas compartilhado (baseado em arquivo ou Redis). Cada papel consome tarefas que tem permissão para manipular. As entregas (handoffs) são mensagens tipadas do protocolo A2A. Preocupações de coordenação: resolução de conflitos de mesclagem (papel de coordenador ou mesclagem de três vias automática), sincronização de estado compartilhado (o plano é congelado assim que os programadores começam; replanejamentos são eventos separados) e controle de acesso do revisor (o revisor não pode aprovar suas próprias alterações ou alterações que ele mesmo propôs).

A amplificação de tokens é o custo oculto. Cada limite de papel adiciona prompts de resumo e contexto de handoff. Uma execução de 40 turnos com um único agente torna-se 160 turnos totais distribuídos em quatro funções. A rubrica pesa especificamente a eficiência de tokens em relação à linha de base de agente único, porque a questão não é "o multiagente funciona?", mas "ele ganha em termos de custo por dólar".

Architecture

GitHub issue URL
      |
      v
Architect (Opus 4.7)
   reads issue, produces plan with subtasks + interfaces
      |
      v
Task board (file / Redis)
      |
   +-- subtask 1 ---+-- subtask 2 ---+-- subtask 3 ---+-- subtask 4 ---+
   v                v                v                v                v
Coder A          Coder B          Coder C          Coder D          (4 parallel)
 (Sonnet)         (Sonnet)         (Sonnet)         (Sonnet)
 worktree A       worktree B       worktree C       worktree D
 Daytona          Daytona          Daytona          Daytona
      |                |                |                |
      +--------+-------+-------+--------+
               v
           merge coordinator  (three-way merge + conflict resolution)
               |
               v
           Reviewer (GPT-5.4)
               |
               v
           Tester  (Gemini 2.5 Pro)  -> passes? -> open PR
                                     -> fails?  -> route back to coder

Stack

• Orquestração: LangGraph com estado compartilhado + subgráficos por agente
• Mensagens: protocolo A2A (Google 2025) para mensagens tipadas entre agentes
• Modelos: Opus 4.7 (arquiteto), Sonnet 4.7 (programadores), GPT-5.4 (revisor), Gemini 2.5 Pro (testador)
• Isolamento de worktree: git worktree add por programador + sandbox Daytona
• Coordenador de mesclagem: mesclagem de três vias personalizada + resolução de conflitos mediada por LLM
• Avaliação: SWE-bench Pro (50 problemas), cenários SWE-AF, HumanEval++ para testes unitários
• Observabilidade: Langfuse com vãos (spans) marcados por função, contabilidade de tokens por agente
• Implantação: K8s com cada papel como um Deployment separado + HPA no backlog

Build It

1. Quadro de tarefas. JSONL baseado em arquivo com mensagens tipadas: plan_request, subtask, diff_ready, review_needed, test_needed, approved, rejected, replan_needed. Os agentes assinam as tags.

2. Arquiteto. Lê o problema do GitHub, executa o Opus 4.7 com um modelo de plano que exige interfaces de subtarefas explícitas (arquivos modificados, funções públicas, impacto nos testes). Emite um plan_request com um DAG de subtarefas.

3. Programadores. N trabalhadores paralelos, cada um reivindica uma subtarefa do quadro. Cada um gera uma ramificação via git worktree add mais uma sandbox Daytona. Implementa a subtarefa. Emite diff_ready com a correção (patch) + variações de teste.

4. Coordenador de mesclagem. Quando todos os programadores terminarem, realiza a mesclagem de três vias das N ramificações em uma ramificação de staging. Resolução de conflitos mediada por LLM apenas quando existir sobreposição no nível do arquivo.

5. Revisor. O GPT-5.4 lê o diff mesclado. Não pode aprovar diffs de sua própria autoria. Emite approved (sem operação) ou review_feedback com solicitações de alteração específicas encaminhadas de volta ao programador relevante.

6. Testador. O Gemini 2.5 Pro executa a suíte de testes em uma sandbox limpa. Captura os artefatos. Emite test_passed ou test_failed com stacktraces. Testes com falha retornam em loop para o programador dono da subtarefa com falha.

7. Contabilidade de handoffs. Cada mensagem que cruza o limite de uma função recebe um span no Langfuse contendo o tamanho do payload e o modelo utilizado. Calcule a amplificação de tokens por subtarefa (coder_tokens + reviewer_tokens + tester_tokens + architect_share / coder_tokens).

8. Avaliação. Execute em 50 problemas do SWE-bench Pro. Compare o pass@1 e o custo em $-por-problema-resolvido em relação a uma linha de base de agente único (um Sonnet 4.7 em uma única worktree).

9. Relatório pós-mortem. Para cada problema com falha, identifique a entrega (handoff) que falhou (plano muito vago, conflito de mesclagem, aprovação falsa do revisor, teste instável). Produza um histograma de falhas de handoff.

Use It

$ team run --issue https://github.com/acme/widget/issues/842
[architect] plan: 4 subtasks (parser, cache, api, migration)
[board]     dispatched to 4 coders in parallel worktrees
[coder-A]   subtask parser  -> 42 lines, tests pass locally
[coder-B]   subtask cache   -> 88 lines, tests pass locally
[coder-C]   subtask api     -> 31 lines, tests pass locally
[coder-D]   subtask migration -> 19 lines, tests pass locally
[merge]     3-way merge: 0 conflicts
[reviewer]  comments on cache (thread pool sizing); routed to coder-B
[coder-B]   revision: 92 lines; submits
[reviewer]  approved
[tester]    all 412 tests pass
[pr]        opened #3382   4 coders, 1 revision, $4.90, 18m

Ship It

outputs/skill-multi-agent-team.md é o entregável. Dado uma URL do problema e o nível de paralelismo, a equipe gera um PR pronto para mesclagem com contabilidade de tokens por função.

Exercises

1. Injete um bug óbvio em um diff no meio da execução (um return None extra antes do corpo principal). Meça a taxa de aprovação falsa do revisor. Ajuste o prompt do revisor até que a aprovação falsa fique abaixo de 5%.

2. Reduza para dois programadores (arquiteto + programador + revisor + testador, onde o programador executa duas subtarefas sequencialmente). Compare o tempo de execução real e a taxa de aprovação.

3. Substitua o coordenador de mesclagem por uma restrição de gravação única (as subtarefas afetam conjuntos de arquivos disjuntos). Meça a carga de planejamento sobre o arquiteto.

4. Substitua o revisor de GPT-5.4 para Claude Opus 4.7. Meça a taxa de aprovação falsa e a diferença no custo de tokens.

5. Adicione um quinto papel: documentador (Haiku 4.5). Após a revisão, ele produz uma entrada no changelog. Meça se a qualidade da documentação justifica o gasto extra de tokens.

Key Terms

Further Reading

• Arquitetura de fábrica do SWE-AF — a fábrica multiagente de referência de 2026
• MetaGPT — framework multiagente baseado em papéis
• AutoGen v0.4 — o framework de atores tipados da Microsoft
• Cognition AI (Devin) — produto de referência
• Factory Droids — produto de referência alternativo
• Protocolo Google A2A — especificação de mensagens entre agentes
• Documentação do git worktree — o substrato de isolamento
• SWE-bench Pro — o alvo de avaliação