Cap 2: Patrones Coordinator-Subagent

Patrones Coordinator-Subagent

El patrón coordinator-subagent es la arquitectura principal para sistemas multi-agente con Claude. Un agente coordinador descompone tareas complejas y delega a agentes especializados.

---

Hub-and-spoke

En este patrón, toda la comunicación inter-agente pasa por el coordinator. Los subagentes nunca se comunican entre sí directamente.

graph TD
    Coordinator --> A[Agent A]
    Coordinator --> B[Agent B]
    Coordinator --> C[Agent C]

Ventajas del hub-and-spoke:

• El coordinator mantiene visibilidad total del progreso
• No hay dependencias ocultas entre subagentes
• Fácil de agregar, quitar o reemplazar subagentes
• El coordinator puede priorizar, cancelar o re-delegar

Rol del coordinator

El coordinator tiene 4 responsabilidades principales:

1. Descomposición de tareas

Analiza la tarea del usuario y la divide en subtareas manejables. Cada subtarea debe ser lo suficientemente específica para que un subagente la complete sin ambigüedad.

Tarea: "Refactoriza el módulo de autenticación"
  ├── Subtarea 1: Analizar el código actual y sus dependencias
  ├── Subtarea 2: Diseñar la nueva estructura
  ├── Subtarea 3: Implementar los cambios
  └── Subtarea 4: Verificar que los tests pasan

2. Delegación

Asigna cada subtarea al subagente más apropiado según su especialización y las herramientas disponibles.

3. Aggregación de resultados

Recopila los outputs de todos los subagentes, resuelve conflictos y compone una respuesta coherente.

4. Routing por complejidad

No todas las tareas requieren subagentes. El coordinator decide dinámicamente:

Complejidad	Acción
Simple (una sola operación)	El coordinator la resuelve directamente
Media (2-3 pasos conocidos)	Delega a un subagente
Alta (múltiples pasos, incertidumbre)	Delega a varios subagentes

Contexto aislado de los subagentes

Un subagente no hereda el historial de conversación del coordinator. Cada subagente empieza con un contexto limpio que incluye:

• Su system prompt específico
• El prompt de la tarea asignada por el coordinator
• Las herramientas que tiene disponibles

Esto es una decisión de diseño deliberada:

• Reduce contaminación: el subagente no se distrae con contexto irrelevante
• Reduce tokens: no consume context window con historial ajeno
• Mejora enfoque: el subagente solo ve lo necesario para su tarea

Si un subagente necesita información del contexto del coordinator, este debe incluirla explícitamente en el prompt de la tarea.

Riesgo de descomposición demasiado estrecha

Dividir una tarea en subtareas muy pequeñas genera cobertura incompleta. Si cada subagente solo ve una pieza mínima, ninguno puede detectar problemas que cruzan subtareas.

// Descomposición demasiado estrecha — riesgoso
Subtarea 1: Renombrar función getUserById → findUserById
Subtarea 2: Actualizar los imports en auth.ts
Subtarea 3: Actualizar los imports en profile.ts
// ¿Y los tests? ¿Y otros archivos que la usan? Se pierde cobertura.

// Descomposición apropiada
Subtarea 1: Renombrar getUserById → findUserById y actualizar TODAS las referencias
Subtarea 2: Verificar que los tests siguen pasando
// El subagente 1 tiene scope suficiente para encontrar todas las referencias.

La regla general: dar a cada subagente suficiente scope para que su trabajo sea coherente, no fragmentar hasta el nivel de instrucción individual.

Iterative refinement loops

El coordinator no simplemente dispara-y-olvida. Después de recibir el output de un subagente, lo evalúa:

Coordinator asigna tarea → Subagente entrega resultado
    ↓
Coordinator evalúa calidad
    ↓
¿Cumple criterios?
  ├── Sí → Avanzar a la siguiente subtarea
  └── No → Re-delegar con feedback específico

El feedback de re-delegación debe ser concreto:

// MAL: feedback vago
"El resultado no es satisfactorio, intenta de nuevo"

// BIEN: feedback específico
"El análisis cubre auth.ts y profile.ts pero falta user.ts que también
importa getUserById. Repite incluyendo todos los archivos que referencian
esa función."

Cuándo dejar de iterar

• El resultado cumple los quality criteria definidos
• Se alcanzó un máximo de reintentos (2-3 para la mayoría de tareas)
• El subagente reporta que no puede mejorar con la información disponible

Routing dinámico vs pipeline fijo

Pipeline fijo

Todas las tareas pasan por todos los subagentes en secuencia:

Análisis → Diseño → Implementación → Testing

Útil cuando el proceso siempre es el mismo. Desperdicia recursos si una tarea solo necesita uno o dos pasos.

Routing dinámico

El coordinator evalúa cada tarea y decide qué subagentes invocar:

"Corrige el typo en el README"
  → Solo invocar al editor (no necesita análisis ni tests)

"Agrega un nuevo endpoint con validación"
  → Análisis + Implementación + Testing

El routing dinámico es más eficiente pero requiere que el coordinator tenga buen juicio. Para lograrlo, su system prompt debe incluir criterios claros de routing, no dejar la decisión totalmente abierta.

Resumen

Concepto	Detalle
Patrón	Hub-and-spoke, comunicación centralizada
Contexto	Subagentes tienen contexto aislado
Descomposición	Evitar subtareas demasiado estrechas
Refinement	Coordinator evalúa y re-delega con feedback concreto
Routing	Dinámico (por complejidad) supera a pipeline fijo

---

Anterior: Agentic Loops | Índice: Índice | Siguiente: Subagentes: Invocación