Phase 19 - Lesson 10

Capstone 10 — Equipo de ingeniería de software multiagente

La arquitectura de fábrica de SWE-AF, el prompting basado en roles de MetaGPT, el gráfico de actores con tipos de AutoGen 0.4, Devin de Cognition y los Droids de Factory convergieron en el mismo diseño de 2026: un arquitecto planifica, N programadores trabajan en worktrees paralelas, un revisor controla y un probador verifica. Las worktrees paralelas convierten el tiempo real (wall-clock) en rendimiento (throughput). El estado compartido y los protocolos de entrega (handoff) se convierten en la superficie de falla. El capstone consiste en construir el equipo, evaluar en SWE-bench Pro e informar qué handoffs fallan y con qué frecuencia.

Tipo: Capstone Lenguajes: Python / TypeScript (agentes), Shell (scripts de worktree) Requisitos previos: Fase 11 (ingeniería de LLM), Fase 13 (herramientas), Fase 14 (agentes), Fase 15 (autónomos), Fase 16 (multiagentes), Fase 17 (infraestructura) Fases ejercitadas: P11 · P13 · P14 · P15 · P16 · P17 Tiempo: 40 horas

Problema

Los arneses de codificación de un solo agente tocan techo en tareas grandes. No porque algún agente individual sea débil, sino porque un contexto de 200k tokens no puede contener un plan de arquitectura más cuatro fragmentos de código paralelos más comentarios del revisor más la salida de la prueba. Las fábricas multiagente dividen el problema: un arquitecto es el propietario del plan, los programadores se encargan de la implementación en worktrees paralelas, un revisor controla y un probador verifica. La arquitectura de "fábrica" de SWE-AF, los roles de MetaGPT, el gráfico de actores con tipos de AutoGen: las tres descripciones se refieren al mismo diseño.

La superficie de falla es la entrega (handoff). El arquitecto planifica algo que los programadores no pueden implementar. Los programadores producen diffs en conflicto. El revisor aprueba una solución alucinada. El probador compite con un programador que todavía está escribiendo. Construirás uno de estos equipos, lo ejecutarás en 50 problemas de SWE-bench Pro, registrarás cada entrega (handoff) y publicarás el post-mortem.

Concept

Los roles son agentes con tipos. El Arquitecto (Claude Opus 4.7) lee el problema, escribe un plan y lo divide en subtareas con interfaces explícitas. Los Programadores (Claude Sonnet 4.7, N instancias paralelas, cada una en un git worktree + sandbox Daytona) implementan las subtareas de manera independiente. El Revisor (GPT-5.4) lee el diff fusionado y aprueba o solicita cambios específicos. El Probador (Gemini 2.5 Pro) ejecuta la suite de pruebas de forma aislada y reporta aprobación/falla con artefactos.

La comunicación se realiza a través de un tablero de tareas compartido (respaldado por archivos o Redis). Cada rol consume tareas que tiene permitido manejar. Las entregas (handoffs) son mensajes con tipos de protocolo A2A. Aspectos de coordinación: resolución de conflictos de fusión (rol de coordinador o fusión de tres vías automática), sincronización de estado compartido (el plan se congela una vez que los programadores comienzan; las replanificaciones son eventos separados) y control del revisor (el revisor no puede aprobar sus propios cambios ni los cambios que propuso).

La amplificación de tokens es el costo oculto. Cada límite de rol añade prompts de resumen y contexto de entrega. Una ejecución de 40 turnos con un solo agente se convierte en 160 turnos en total distribuidos entre cuatro roles. La rúbrica pondera específicamente la eficiencia de tokens frente a la línea de base de un solo agente porque la pregunta no es "si el enfoque multiagente funciona", sino "si gana por cada dólar invertido".

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

Orquestación: LangGraph con estado compartido + subgráficos por agente
Mensajería: protocolo A2A (Google 2025) para mensajes con tipos entre agentes
Modelos: Opus 4.7 (arquitecto), Sonnet 4.7 (programadores), GPT-5.4 (revisor), Gemini 2.5 Pro (probador)
Aislamiento de worktrees: git worktree add por programador + sandbox Daytona
Coordinador de fusión: fusión de tres vías personalizada + resolución de conflictos mediada por LLM
Evaluación: SWE-bench Pro (50 problemas), escenarios SWE-AF, HumanEval++ para pruebas unitarias
Observabilidad: Langfuse con spans etiquetados por rol, contabilidad de tokens por agente
Despliegue: K8s con cada rol como un Despliegue separado + HPA en la carga de trabajo pendiente

Build It

Tablero de tareas. JSONL respaldado por archivos con mensajes con tipos: plan_request, subtask, diff_ready, review_needed, test_needed, approved, rejected, replan_needed. Los agentes se suscriben a las etiquetas.
Arquitecto. Lee el problema de GitHub, ejecuta Opus 4.7 con una plantilla de plan que requiere interfaces de subtareas explícitas (archivos modificados, funciones públicas, impacto en pruebas). Emite un plan_request con un DAG de subtareas.
Programadores. N trabajadores en paralelo, cada uno reclama una subtarea del tablero. Cada uno genera una nueva rama git worktree add más una sandbox Daytona. Implementa la subtarea. Emite diff_ready con el parche + deltas de prueba.
Coordinador de fusión. Cuando todos los programadores terminan, realiza una fusión de tres vías de las N ramas en una rama de staging. Resolución de conflictos mediada por LLM solo cuando existe superposición a nivel de archivos.
Revisor. GPT-5.4 lee el diff fusionado. No puede aprobar diffs que haya escrito. Emite approved (sin operación) o review_feedback con solicitudes de cambio específicas dirigidas al programador correspondiente.
Probador. Gemini 2.5 Pro ejecuta la suite de pruebas en una sandbox limpia. Captura artefactos. Emite test_passed or test_failed con stacktraces. Las pruebas fallidas regresan en loop al programador propietario de la subtarea que falló.
Contabilidade de entregas. Cada mensaje que cruza un límite de rol obtiene un span en Langfuse con el tamaño del payload y el modelo utilizado. Calcula la amplificación de tokens por subtarea (coder_tokens + reviewer_tokens + tester_tokens + architect_share / coder_tokens).
Evaluación. Se ejecuta en 50 problemas de SWE-bench Pro. Compara pass@1 y $-por-problema-resuelto frente a una línea de base de un solo agente (un Sonnet 4.7 en una sola worktree).
Post-mortem. Para cada problema fallido, identifica la entrega (handoff) que falló (plan demasiado vago, conflicto de fusión, aprobación falsa del revisor, prueba inestable). Produce un histograma de fallas 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 es el entregable. Dada una URL de problema y el nivel de paralelismo, el equipo genera un PR listo para fusionar con contabilidad de tokens por rol.

Peso	Criterio	Cómo se mide
25	pass@1 en SWE-bench Pro	Subconjunto coincidente de 50 problemas, pass@1
20	Aceleración paralela	Tiempo real frente a la línea de base de un solo agente
20	Calidad de la revisión	Tasa de aprobación falsa en sondeo de bug inyectado
20	Eficiencia de tokens	Tokens totales por problema resuelto frente a un solo agente
15	Ingeniería de coordinación	Resolución de conflictos de fusión, histograma de fallas de handoff

Exercises

Inyecta un bug obvio en un diff a mitad de la ejecución (return None adicional antes del cuerpo principal). Mide la tasa de aprobación falsa del revisor. Ajusta el prompt del revisor hasta que la tasa de aprobación falsa sea menor del 5%.
Reduce a dos programadores (arquitecto + programador + revisor + probador, el programador ejecuta dos subtareas secuencialmente). Compara el tiempo real y la tasa de aprobación.
Reemplaza el coordinador de fusión con una restricción de escritor único (las subtareas tocan conjuntos de archivos disjuntos). Mide la carga de planificación sobre el arquitecto.
Cambia el revisor de GPT-5.4 a Claude Opus 4.7. Mide la tasa de aprobación falsa y la diferencia en el costo de tokens.
Agrega un quinto rol: documentador (Haiku 4.5). Después de la revisión, produce una entrada en el registro de cambios. Mide si la calidad de la documentación justifica el gasto adicional de tokens.

Key Terms

Término	Lo que la gente dice	Lo que realmente significa
Worktree paralela	"Rama aislada"	git worktree add que produce un árbol de trabajo nuevo por programador
Tablero de tareas	"Bus de mensajes compartido"	Almacenamiento de archivos o Redis de mensajes con tipos a los que se suscriben los agentes
Handoff	"Límite de roles"	Cualquier mensaje que cruza del contexto de un rol al de otro
Amplificación de tokens	"Sobrecarga multiagente"	Tokens totales en todos los roles / tokens de un solo agente para la misma tarea
Protocolo A2A	"Agente a agente"	Especificación de Google de 2025 para mensajes con tipos entre agentes
Coordinador de fusión	"Integrador"	Componente que ejecuta la fusión de tres vías y media en los conflictos
Aprobación falsa	"Alucinación del revisor"	El revisor aprueba un diff con bugs conocidos