Orquestando múltiples subagentes en Claude Code: creando flujos de trabajo complejos (2026)

- La superficie de orquestación de agentes en Claude Code cambia rápido (equipos de agentes, flujos de trabajo dinámicos, límites de profundidad); las cifras aquí se volvieron a comprobar con la documentación de Claude Code y el post de investigación de Anthropic al momento de escribir — verifica la documentación en vivo antes de depender de ellas.

¿Qué significa orquestar subagentes?

Cuando ya te sientes cómoda creando y ejecutando un solo subagente, el siguiente paso es orquestar subagentes en Claude Code: dejar que un agente principal coordine varios subagentes trabajadores al mismo tiempo, o encadenarlos. Este es el clásico patrón orquestador-trabajador (a veces llamado un agente líder que coordina trabajadores).

La definición corta para recordar: orquestar subagentes significa que un agente coordinador (el orquestador) crea varios subagentes, cada uno haciendo una porción del trabajo en su propia ventana de contexto separada, y luego devolviendo un resumen conciso para que el agente principal lo combine.

Todo el truco vive en esas dos palabras: "contexto separado". Cada subagente obtiene una ventana de contexto independiente, así que puede leer decenas de archivos, ejecutar muchos comandos y producir salidas largas sin inflar el contexto de tu sesión principal. El agente principal solo recibe de vuelta la parte destilada. Así es como abordas una tarea grande y con varias ramas mientras el contexto de la sesión original se mantiene limpio.

Esta es una capacidad avanzada. Si todavía no tienes claro qué es un subagente y cómo declarar uno básico, lee primero la guía de subagentes para principiantes y luego vuelve aquí. Este artículo asume que ya has creado al menos un subagente y ahora quieres dirigir varios a la vez — algo que casi ningún tutorial práctico cubre de principio a fin.

Cuándo SÍ y cuándo NO deberías orquestar varios subagentes

Coordinar varios agentes no siempre es una ventaja. Consume muchos tokens y añade latencia, así que solo vale la pena cuando la tarea realmente se divide en ramas. Este es el punto de decisión más valioso, y es justo la parte que la documentación y los blogs suelen saltarse.

La cifra de 15x en tokens y la advertencia sobre el estado compartido provienen ambas del post de Anthropic sobre el Multi-Agent Research System (13 de junio de 2025). Ese mismo post señala que la mayor parte de la variación de rendimiento (alrededor del 80%) proviene de cuántos tokens se consumen — es decir, los tokens son a la vez el costo y la palanca. Regla pragmática: si no puedes plantear la tarea como ramas claras y separadas, no orquestes — usa solo una sesión lineal. Para ver dónde encajan los subagentes en relación con skills, hooks y MCP, lee la diferencia entre skills, subagentes, hooks y MCP.

Los dos patrones de orquestación: paralelo vs pipeline

Existen exactamente dos patrones fundamentales. Saber cuándo recurrir a cada uno ya te pone por delante de la mayoría de los desarrolladores.

Paralelo (fan-out / fan-in): el agente principal crea varios subagentes al mismo tiempo, cada uno atendiendo una rama independiente, y luego el agente principal reúne (hace el fan-in) los resúmenes en un solo resultado.

 ┌─→ subagent: auth ────┐
main agent ├─→ subagent: database ─┤─→ synthesize
 └─→ subagent: API ─────┘
 (parallel fan-out) (fan-in)

Pipeline (cadena / secuencial): los subagentes corren en orden, donde la salida de un paso se convierte en la entrada del siguiente. El agente principal pasa el contexto entre los eslabones.

main → subagent: reviewer → subagent: optimizer → result
 (find issues) (fix based on issues)

La prueba de una frase: si las ramas NO necesitan conocer los resultados de las demás, ve por paralelo; si el paso B necesita el resultado del paso A, ve por pipeline. Muchos flujos reales son híbridos: haz el fan-out en paralelo durante una fase de recolección y luego encadena un paso final de síntesis.

Ejemplo 1 — Ejecutar subagentes EN PARALELO (desde cero)

Una tarea real: quieres auditar rápido un repositorio de backend, revisando tres áreas independientes a la vez — auth, base de datos y API. Estas tres áreas no dependen entre sí, lo que las convierte en un encaje de manual para la ejecución en paralelo.

1. Escribe el prompt coordinador. Pídele a Claude que haga fan-out de forma explícita, nombra las tres ramas y dile a cada subagente que devuelva solo un resumen:

   Audit this repo in parallel using 3 independent subagents:
   1) auth: check login flow, sessions, permission holes
   2) database: check schema, N+1 queries, missing indexes
   3) API: check input validation, rate limiting, error handling
   Each subagent should return only a short summary (~10 bullets max),
   NOT a full log dump. Then combine into one report.

2. Observa a Claude hacer el fan-out. Claude Code crea los tres subagentes para correr en paralelo, cada uno leyendo el código en su propio contexto. Verás tres flujos de trabajo corriendo al mismo tiempo en la sesión.
3. Lee el resumen combinado. Cuando los tres terminan (fan-in), el agente principal los combina en un solo informe. Como cada subagente solo devolvió viñetas concisas, el contexto de la sesión principal se mantiene ligero.

La salida condensada del paso de síntesis se ve más o menos así (ilustrando el formato, no números reales de tu repositorio):

Audit report (merged from 3 subagents):
[auth] - Sessions not setting HttpOnly/Secure flags
 - Missing permission check on /admin/* endpoints
[database] - Order list query has N+1 (findOne in loop)
 - users table missing index on email column
[API] - 4 endpoints not validating the request body
 - No rate limit on the login route

Por qué el paralelo encaja aquí: las tres ramas no necesitan los datos de las demás, así que ejecutarlas en simultáneo recorta el tiempo de reloj y aísla cada informe largo en su propio contexto. Forzar que esto corra en secuencia solo lo haría más lento, no más correcto.

Ejemplo 2 — Un pipeline secuencial (cadena): del reviewer al optimizer

Una tarea real: sospechas que un módulo tiene problemas de rendimiento. En el paso 1, un subagente code-reviewer encuentra los cuellos de botella. En el paso 2, un subagente optimizer los corrige con base en esa lista. Esto es una dependencia clara — el optimizer necesita saber lo que encontró el reviewer — así que tiene que ser secuencial, no paralelo.

1. Ejecuta el reviewer primero. Prompt coordinador:

   Use the code-reviewer subagent to find performance bottlenecks
   in the src/services/ directory and return a prioritized list.

2. Pasa el resultado al optimizer. El agente principal toma la lista del reviewer como entrada para el siguiente paso:

   Hand the list above to the optimizer subagent:
   fix in priority order, add one line explaining each change,
   and do NOT change any public API behavior.

3. Obtén el resultado final. El optimizer trabaja exactamente en lo que el reviewer marcó. Claude actúa como el relevo, pasando el contexto entre los dos eslabones.

[reviewer] Found 3 bottlenecks:
 P1 - parseAll() re-reads the file inside a loop
 P2 - sequential API calls that could be batched
 P3 - JSON.parse repeated on the same payload
[optimizer] Fixed:
 P1 → cache file contents outside the loop
 P2 → merge into a single batch request
 P3 → parse once, reuse the object

El punto central: usa un pipeline cuando un paso posterior necesita la salida de uno anterior. Si intentaras paralelizar estos dos pasos dependientes, el optimizer estaría corrigiendo a ciegas, porque la lista del reviewer todavía no existiría. La orquestación no vive aislada — es una pieza del flujo de brainstorm a plan a cook a ship; normalmente planificas primero y luego sueltas los subagentes para "cocinar" las ramas.

Avanzado — Agentes orquestadores, subagentes anidados y límites de profundidad

En lugar de escribir un prompt coordinador cada vez, puedes declarar un agente orquestador dedicado cuya única tarea es coordinar. Crea un archivo en .claude/agents/coordinator.md:

---
name: coordinator
description: Coordinates worker subagents for large, multi-branch tasks.
 Only splits work, spawns workers, and merges summaries - does NOT write code itself.
---

You are a coordinating agent. Your job:
1. Decompose the request into independent branches (if any).
2. Independent branches → dispatch in parallel; dependent branches → chain.
3. Require each worker to return ONLY a tight summary.
4. Merge everything into a single result for the user.
Do not do the detailed work yourself; always delegate to workers.

El name y la description en el frontmatter ayudan a Claude a saber cuándo llamar a este agente. La restricción de "solo coordinar" evita que se meta a hacer el trabajo por sí mismo y reviente su propio contexto.

Subagentes anidados: un subagente puede crear sus propios subagentes hijos. Esto es poderoso pero fácil de perder el control, así que Claude Code limita la profundidad. Según la documentación de Claude Code sobre subagentes (revisada en 2026-08), la profundidad de creación por defecto es de 3 niveles y es ajustable mediante la variable de entorno CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. Configurarla demasiado alto lleva fácilmente a una explosión en la cantidad de agentes y a tokens quemados; la mayoría de los flujos reales nunca necesita pasar del valor por defecto.

Para tareas paralelas duraderas o que superan una sola ventana de contexto, dos primitivos nativos más nuevos retoman donde este patrón se detiene — mira "Lo nuevo en orquestación (2026)" más abajo.

Más allá del modelo orquestador-trabajador, hay un patrón menos común para cuando quieres consejo en vez de ejecución delegada: el patrón consultivo: llamar a kongming para orientación en un checkpoint.

Lo nuevo en orquestación (2026): flujos de trabajo dinámicos & equipos de agentes

El patrón prompt-y-coordinador que vimos arriba sigue funcionando exactamente como se describe, y sigue siendo el valor por defecto correcto para la delegación de rutina en varias ramas — la mayoría de las tareas no necesita más que eso. Desde que esta guía se publicó por primera vez, Claude Code lanzó dos primitivos nativos más nuevos que escalan la orquestación aún más: los flujos de trabajo dinámicos de Claude Code, donde Claude escribe un script para repartir el trabajo de forma programática, y los equipos de agentes de Claude Code, un modo experimental de múltiples sesiones. Ninguno reemplaza el patrón de arriba — se apoyan sobre él para trabajos más grandes o de mayor duración.

Mantén el patrón prompt-y-coordinador de arriba para el trabajo de rutina en varias ramas, como los dos ejemplos de esta guía. Recurre a los Flujos de Trabajo Dinámicos cuando una tarea supere una ventana de contexto o se beneficie de una ejecución en segundo plano con verificación cruzada a escala real. Recurre a los Equipos de Agentes para una configuración colaborativa de múltiples sesiones y larga duración, en vez de una sola ronda de delegar y recibir de vuelta. Ambos primitivos todavía están evolucionando, incluidos sus límites exactos de cantidad de agentes y de concurrencia, así que vuelve a revisar la documentación en vivo antes de depender de cualquiera de ellos en producción.

Optimizar tokens y costo cuando orquestas

Como las ejecuciones multiagente cuestan alrededor de 15 veces los tokens de una sesión de chat normal (según Anthropic), optimizar tokens no es opcional — es la condición que hace que la orquestación valga el dinero. Algunos movimientos pragmáticos:

• Limita el número de subagentes a 3-5 por fan-out. Añadir más agentes rara vez mejora la calidad de forma proporcional, pero aumenta los tokens de manera lineal.
• Dirige los trabajadores a un modelo más barato. Las ramas simples (leer archivos, listar cosas) pueden ir a un modelo barato como Haiku, reservando el modelo fuerte para el paso de síntesis.
• Fuerza a los subagentes a devolver solo resúmenes, no volcados completos de log/diff de vuelta al agente principal. Esta es la mayor fuente de tokens desperdiciados, y todo el mundo cae en ella.
• Evita que muchos subagentes devuelvan salidas largas al principal — hacer el fan-in de varias salidas largas atiborra el contexto principal y anula todo el propósito del aislamiento.

Para profundizar en los presupuestos de tokens para sesiones multiagente, mira la guía sobre optimizar tokens al ejecutar muchos agentes.

¿No quieres construirlo tú misma? Un kit de agente orquestador listo para usar (AgentKit)

Escribir un coordinador decente y un escuadrón de trabajadores lleva tiempo. Si prefieres tener algo listo para usar, existe un kit que lo empaqueta todo. Una línea para evitar confusiones: el AgentKit de aquí es un kit para Claude Code (agentkit.best, la CLI ak) — NO el AgentKit de OpenAI (Agent Builder/ChatKit, lanzado el 6 de octubre de 2025).

El Engineer Kit de AgentKit viene con 17 agentes de ingeniería (de los 45 totales de la plataforma = 17 de ingeniería + 28 de marketing) más flujos de orquestación — como la skill ak-orchestrate — para que no tengas que escribir un coordinador desde cero. El precio listado del Engineer Kit es de US$ 99, y la página no menciona ninguna cuota recurrente. Siendo franca: puedes construir un orquestador tú misma perfectamente siguiendo las secciones de arriba; el kit solo vale la pena si quieres ahorrar tiempo de configuración y usar agentes preajustados. Para ver exactamente qué hay dentro, lee la reseña del Engineer Kit, o mira directamente los agentes orquestadores listos de AgentKit.

Errores comunes al orquestar varios subagentes

• Crear demasiados subagentes. Cuando todos devuelven resultados a la vez, el contexto principal se consume. Evítalo: mantén 3-5 agentes por ronda y fuerza resúmenes.
• Usar paralelo para trabajo dependiente. Resultados erróneos o condiciones de carrera. Evítalo: pregúntate "¿el paso posterior necesita la salida del anterior?" — si es sí, usa un pipeline.
• Subagentes que devuelven logs largos en vez de resúmenes. Tokens desperdiciados y contexto atiborrado. Evítalo: declara los límites de salida de forma explícita en el prompt o en la definición del agente.
• Olvidar el límite de profundidad. Los subagentes anidados desbordan los niveles y la cantidad de agentes explota. Evítalo: mantén CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH en el valor por defecto a menos que tengas una razón clara.
• Gasto desproporcionado de tokens. Usar multiagente para un cambio pequeño. Evítalo: para tareas pequeñas o rápidas, ejecuta una sola sesión lineal en vez de orquestar.

Preguntas frecuentes (FAQ)

¿Cuántos subagentes pueden correr en paralelo?

En la práctica, mantén 3-5 subagentes por fan-out. No es un límite estricto, pero más que eso normalmente no mejora la calidad de forma proporcional, mientras que los tokens suben rápido y el contexto combinado se sobrecarga con facilidad. Varias rondas pequeñas de fan-out le ganan a una ronda gigante.

¿Paralelo o pipeline cuesta más tokens?

El paralelo normalmente dispara los tokens con más fuerza, porque muchos agentes corren a la vez, cada uno con su propio contexto. Un pipeline consume tokens de forma más moderada en cualquier instante aislado, pero se acumulan a lo largo de los pasos y es más lento. Elige según las dependencias de la tarea, no solo por los tokens.

¿Un subagente puede crear sus propios subagentes hijos (anidados)?

Sí. Un subagente puede crear subagentes hijos (subagentes anidados). Claude Code limita la profundidad — 3 niveles por defecto — y es ajustable mediante la variable CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. La mayoría de los flujos nunca necesita pasar del valor por defecto.

¿Necesitas equipos de agentes para orquestar?

No, no es obligatorio. Puedes orquestar solo con un prompt coordinador o un agente orquestador declarado por ti. Equipos de agentes es una superficie para el paralelismo duradero y de gran escala que supera una sola ventana de contexto; consulta la documentación en vivo, ya que la función es nueva y cambia rápido — mira "Lo nuevo en orquestación (2026)" arriba para la comparación completa.

¿Flujos de Trabajo Dinámicos es lo mismo que orquestar subagentes?

No. El patrón orquestador-trabajador de esta guía es guiado por prompt — Claude decide qué corre a continuación en cada turno. Flujos de Trabajo Dinámicos es un primitivo separado y más nuevo: Claude escribe un script JS de antemano, así que el plan vive en el script en vez del contexto de Claude, y puede repartir a muchos más agentes (hasta 1.000, según la documentación al momento de escribir) de los que coordinarías a mano. Mira la guía completa de Flujos de Trabajo Dinámicos para la configuración y los límites.

¿Vale la pena orquestar varios agentes para un proyecto pequeño?

Normalmente no. Para cambios pequeños o rápidos, la coordinación y el costo en tokens (las ejecuciones multiagente cuestan alrededor de 15 veces los tokens, según Anthropic) superan el beneficio. Solo orquesta cuando la tarea realmente se divide en ramas independientes o abarca muchas áreas.

¿Existe un kit de agente coordinador listo para usar?

Sí. El Engineer Kit de AgentKit (agentkit.best, la CLI ak — distinto del AgentKit de OpenAI) empaqueta 17 agentes de ingeniería más flujos de orquestación para que no tengas que escribir un coordinador tú misma. Aún puedes construirlo todo por tu cuenta como se muestra arriba; el kit solo ahorra tiempo de configuración.

Conclusión y próximos pasos

No empieces con una orquesta de diez agentes. Construye primero un pipeline de dos pasos (como reviewer a optimizer), mide los tokens que quema y solo entonces expande al fan-out en paralelo cuando la tarea realmente se divida en ramas independientes. Domina los fundamentos en la guía de subagentes para principiantes y pon la orquestación en su lugar correcto dentro del flujo de brainstorm a plan a cook a ship. Si prefieres no escribir un coordinador tú misma, echa un vistazo a la reseña del Engineer Kit.