Subagentes y orquestación

Cómo reparte el trabajo una sesión de IA cuando la tarea no cabe en una sola cabeza: qué se delega, cómo se escribe el encargo, qué patrón conviene en cada caso y por qué un mensaje de "éxito" todavía no prueba nada.

FundamentosSubagentesBriefingWorkers

La sesión principal como command center

Cuando trabajas con un agente como Claude Code, OpenCode o Codex, la conversación que tienes abierta tiene una ventana de contexto finita. Cada archivo que el agente lee, cada salida de un comando y cada respuesta de un MCP ocupan espacio en ella. Si la misma sesión lee veinte archivos, corre la suite de tests y además decide qué hacer después, llega un punto en que el plan original queda enterrado bajo miles de líneas de salida que ya no sirven.

La orquestación separa dos papeles. La sesión principal, el command center, habla contigo, planifica, decide y revisa. Los ejecutores (subagentes) reciben un encargo cerrado, hacen el trabajo pesado en su propio contexto y devuelven un reporte corto. El detalle de lo que leyeron se queda con ellos. A la sesión principal solo llega la conclusión, y por eso puede seguir coordinando durante horas sin perder el hilo.

Hay una segunda ventaja: el paralelismo. Tres lecturas independientes lanzadas a la vez tardan lo mismo que la más lenta de ellas. El costo también existe. Anthropic midió en su sistema de research que los sistemas multiagente consumen unas 15 veces más tokens que un chat normal, así que delegar tiene sentido cuando la tarea lo vale.

Command center con dos tipos de ejecutor La sesión principal, en el centro, envía briefs a la izquierda a tres subagentes de un turno que devuelven un reporte y desaparecen, y a la derecha, a través de un mailbox, a dos workers persistentes que conversan en ambos sentidos. Abajo, cada resultado se verifica en el destino (archivo, pantalla, fila del tracker) antes de darlo por hecho. Subagentes de un turno por defecto Workers supervisados opcionales Sesión principal planifica, decide, revisa Subagente A Subagente B Subagente C brief reporte, y termina Mailbox ida y vuelta Worker 1 su worktree Worker 2 su worktree Verificar en el destino releer el archivo, la pantalla, la fila del tracker "ok" dice que la llamada salió el destino dice si pasó
La sesión principal delega por dos vías: subagentes que viven un turno y workers persistentes que conversan por un mailbox. Ninguna de las dos confirma un resultado; eso se lee en el destino.

Qué se delega y qué no

La regla práctica es delegar lo que llena el contexto y quedarse con lo que requiere criterio. Leer y escribir varios archivos, operar un MCP, investigar en varios repos, hacer operaciones de git, correr la verificación (tests, tipos, lint) o una tarea larga son trabajo de ejecutor. Una consulta rápida, leer o guardar memoria, llevar la lista de tareas, preguntarte algo a ti y planificar se quedan en la sesión principal.

La planificación merece una nota aparte. Un subagente al que se le permite "decidir qué hacer después" amplía su propio alcance sin avisar, y la sesión principal pierde la imagen real del progreso. Las decisiones son del command center; los subagentes ejecutan.

El briefing de 7 componentes

Un subagente arranca sin nada de lo que tú y la sesión principal hablaron. Todo lo que sabe está en el encargo que recibe, así que un encargo vago produce trabajo duplicado, huecos o una interpretación distinta de la tarea. Anthropic cuenta un caso concreto en su sistema de research: con instrucciones cortas del tipo "investiga la escasez de semiconductores", varios subagentes terminaban haciendo las mismas búsquedas.

Este repo obliga a que cada despacho lleve siete partes:

# Componente Qué contiene
1 Goal Una sola oración con el resultado esperado.
2 Context docs Los archivos que debe leer primero, con ruta absoluta (el directorio de trabajo de un subagente se reinicia entre llamadas).
3 Project Standards Reglas compactas de las skills relevantes, tomadas del registro de skills, para que el subagente no relea cada SKILL.md completo.
4 Skills to load Qué skills invocar antes de usar sus herramientas.
5 Exact instructions Pasos numerados, cada uno con la herramienta o acción que usa.
6 Report format Qué devuelve y con qué forma: campos con nombre, no prosa libre.
7 Rules Las reglas críticas del proyecto que aplican a esta tarea.

Un ejemplo recortado, del tipo que la sesión principal escribe antes de despachar:

Goal: Descargar el reporte de Allure del run <<RUN_ID>> y dejarlo generado en local.

Context docs:
  - <<REPO_ROOT>>/.github/workflows/regression.yml

Skills to load: (ninguna, es una tarea de gh)

Exact instructions:
  1. Descargar el artefacto allure-results del run.
  2. Si el directorio queda vacío, reportar el fallo y PARAR (sin reintentar).
  3. Generar el reporte y comprobar que existe index.html.

Report format: { "artifact": "allure", "ok": bool, "path": string, "error": string|null }

Rules: no tocar archivos fuera del directorio de reportes; no correr git.

El formato del reporte es la parte que más se olvida y la que más ahorra. Si pides campos con nombre, puedes juntar cinco reportes en paralelo sin leer cinco ensayos.

Patrones de ejecución

Hay cuatro formas de despachar. Para elegir, recorre las preguntas en orden y quédate con la primera que encaja:

Patrón Cuándo Ejemplo en QA Trampa típica
Inline (sin despacho) Tarea corta que toca uno o dos archivos Leer un archivo de config Levantar un subagente para una lectura
Background Algo largo que se vigila desde afuera Esperar a que termine la suite de regresión en CI Mandar a background algo de menos de 5 minutos
Parallel N tareas iguales e independientes Descargar tres artefactos del mismo run Más de 10 a la misma API: Jira o GitHub responden con 429
Sequential Cada etapa consume la salida de la anterior Plan, luego código, luego review de un test Encadenar dos lecturas que no dependen una de otra
Single Una tarea no trivial que conviene aislar Analizar un ticket de Jira y escribir el borrador del ATP Reusar el mismo subagente en varias fases

Antes de un fan-out en paralelo tienes que saber qué harás con los N reportes que vuelvan. Si no puedes explicar ese paso de unión, en realidad tienes un trabajo secuencial disfrazado.

Subagente de un turno contra worker supervisado

El subagente clásico vive dentro de un turno: recibe el brief, trabaja, reporta y desaparece. No puedes hablarle a mitad de camino, y su contexto se pierde al terminar. Para la mayoría del trabajo (leer, mapear, verificar) es exactamente lo que quieres.

Algunas tareas son más grandes: una historia completa, un módulo entero, algo en lo que quieres poder intervenir mientras avanza. Para eso existe un segundo ejecutor, el worker supervisado: una sesión de agente persistente, con su propio worktree de git, a la que la sesión principal (aquí llamada conductor) le escribe y de la que recibe mensajes por un mailbox. Este ejecutor es opcional. Depende de tener instalado el binario de orquestación y un runtime alcanzable; si falta cualquiera de los dos, el trabajo sigue con subagentes y con líneas de lanzamiento que una persona pega a mano en terminales.

Subagente de un turno (por defecto) Worker supervisado (opcional)
Cuánto vive Lo que dura el turno Hasta que alguien lo cierra
Memoria Se pierde al entregar el reporte Persiste; puedes seguir hablándole
Comunicación Ninguna hasta que termina Preguntas y respuestas en ambos sentidos, en cualquier momento
Git Comparte el índice de la sesión principal Su propio worktree, o el checkout compartido con dueños de archivo declarados
Sirve para Leer, mapear, verificar, tareas de una sola vez Escribir e integrar por su cuenta una historia o un módulo entero

Aun con workers en marcha, el conductor sigue usando subagentes para sus propias lecturas y verificaciones. Eso mantiene limpio el contexto de quien coordina.

Vale la pena conocer la postura contraria. Cognition (el equipo de Devin) argumenta que los sistemas de varios agentes son frágiles porque las decisiones quedan repartidas y el contexto no se comparte lo suficiente entre ellos. La respuesta práctica de este repo va en esa línea: un worker recibe un alcance completo que escribe e integra solo, y cualquier cosa que amplíe ese alcance vuelve al conductor.

Errores comunes

Lo que sale mal cuando se orquesta

Dos sesiones en el mismo checkout. Aunque nunca toquen el mismo archivo, comparten el índice de git: lo que una sesión agrega al staging entra en el próximo commit de la otra, y un descarte global (git restore ., git reset --hard) borra sin remedio lo que otra sesión todavía no guardó. Si el trabajo escribe código, cada worker va en su propio worktree, y nadie descarta rutas que no modificó en su sesión.

Conversar escribiendo en la terminal de otro agente. El envío de texto a una terminal trunca en silencio, se queda solo con el final y aun así responde que salió bien. Un mensaje que empieza a mitad de frase es una truncación hasta que se demuestre lo contrario: pide el puntero al archivo y no respondas al fragmento. Los mensajes van por el mailbox, y lo que pase de un par de oraciones va en un archivo.

Confundir el éxito de la llamada con el resultado. ok: true, exit 0 o un id devuelto dicen que la petición estaba bien formada. Un mensaje puede quedar aceptado con "delivered_at": null en el mismo recibo. Una escritura se verifica releyéndola en el destino, un mensaje cuando el otro responde, una transición de Jira releyendo el status.

Arreglar el error de un subagente por tu cuenta. Si un ejecutor falla, la sesión principal para, te cuenta el contexto completo y te ofrece reintentar, saltar o abortar. No corrige sin tu aprobación.

Así lo hace este repo

El modo orquestación está activo en todas las sesiones y lo define la sección 3 de AGENTS.md, que guarda el núcleo (cuándo usar subagentes, el briefing de siete componentes, el protocolo de error); el resto de la sección (ejecutores, patrones, gates) está en .agents/instructions/agent-orchestration-detail.md. La doctrina completa, con una copia para que los subagentes la carguen sin leer todo AGENTS.md, está en .agents/skills/agentic-qa-core/references/orchestration-doctrine.md. De ahí salen las tablas de esta página.

El briefing
.agents/skills/agentic-qa-core/references/briefing-template.md tiene la plantilla de 7 componentes y un ejemplo completo por patrón. La raíz del repo se escribe como <<REPO_ROOT>> y la sesión principal la resuelve a una ruta absoluta al despachar. La sección de Project Standards se arma desde .agents/skills/REGISTRY.md, que genera bun run skills:registry.
Los patrones
.agents/skills/agentic-qa-core/references/dispatch-patterns.md tiene la heurística por orden, los límites de paralelismo y de cuándo ir a background, y ejemplos reales: descargas en paralelo en .agents/skills/regression-testing/SKILL.md y la cadena Plan, Code, Review en .agents/skills/test-automation/SKILL.md.
Las skills de workflow
Las skills de workflow que son dueñas de un stage (las que llevan metadata.stage_owner: true en su frontmatter; REGISTRY.md dice cuáles son) deben tener una sección ## Subagent Dispatch Strategy con briefings de 7 componentes. bun run skills:check lo hace cumplir.
Los workers supervisados
.agents/skills/orca-orchestration/SKILL.md es la capa de transporte. Comprueba tres estados (sin binario, binario sin runtime, listo) y en los dos primeros las skills de workflow no mencionan el orquestador. Sus valores por defecto (máximo de workers, agente, y por nivel de conductor, worker y subagente: modelo, esfuerzo, modo de permisos y overrides de modelo por tema) están en el bloque orchestration: de .agents/project.yaml; la decisión está en .context/ADR/ADR-0024-agentic-work-profile-and-permission-posture.md. Un worker nunca te pregunta nada a ti: sus errores, bloqueos y decisiones van al conductor, que te los trae. Cada worker trabaja en su propio worktree, que se prepara y se revisa solo antes de borrarse; cómo funciona está en Worktrees.
Las rutinas sin supervisión
El modo AUTOMATION de la misma skill corre un prompt versionado con un disparador tipo cron, sin una persona del otro lado. Es un conductor que despacha y no produce: abre los workers que hacen el trabajo, no publica ni aprueba nada, y lo ambiguo lo reporta en vez de adivinarlo. Las recetas que encajan en este repo están en .agents/skills/orca-orchestration/references/automations.md.

Cinco de las hard rules de esa skill recogen los errores de la sección anterior:

La disciplina de canales completa, con lo que el envío a terminal sí hace bien (reactivar un MCP caído en un worker, recargar plugins, interrumpir), está en .agents/skills/orca-orchestration/references/channel-discipline.md. A nivel de todo el repo, la regla crítica 16 de AGENTS.md generaliza la regla 17 a cualquier escritura en Jira, llamada a un MCP o reporte de subagente, y la regla crítica 15 prohíbe los descartes globales de git porque varias sesiones pueden compartir el mismo árbol.

Para profundizar