CH 13 · Subagentes y orquestación multi-Agent
Objetivo del capítulo
Cuando una tarea es demasiado grande o demasiado enrevesada, en vez de dejar a un solo Agent arrastrarse hasta el final, déjalo que la divida en unos cuantos trozos, mande varios subagentes a trabajar en paralelo y reúna los resultados cuando terminen. Este capítulo aclara: por qué multi-Agent, qué aspecto tienen los subagentes de dsh, luego hace en la práctica "dividir tarea → delegación en paralelo → fusionar resultados", y finalmente pone toda la familia de herramientas en el inventario.
Por qué multi-Agent: tres puntos duros del hilo único
Un Agent que va de principio a fin se va a encontrar tres problemas:
| Punto duro | Síntoma |
|---|---|
| Contaminación de contexto | A mitad de tarea, los primeros pasos, los resultados intermedios y los errores se acumulan en la misma sesión, y el modelo cada vez distingue peor qué información es la más importante ahora mismo |
| No se puede paralelizar | Buscar info, escribir un borrador, revisar código — las tres cosas solo se pueden poner en cola, la siguiente espera a que termine la anterior |
| Se desvía cada vez más | En tareas largas el modelo se queda atascado fácilmente por un camino equivocado, reintentando la misma ruta fallida y quemando tokens |
El razonamiento multi-Agent es exactamente el remedio: aislamiento de contexto. Cada subagente solo guarda el contexto relevante para su tarea; el Agent principal divide, despacha y recoge. El consumo de tokens es controlable, y cada paso se puede revisar en la Trayectoria.
Un hecho clave: los subagentes también son plugins
Primero, un respiro: los subagentes no son algo separado que dsh tenga escondido; son plugins — otra confirmación del "todo es un plugin" de CH 08. Y los subagentes ya son estándar en las herramientas Agent actuales — Claude Code y Codex tienen esa capacidad; lo único que cambia es que en dsh siguen existiendo como plugin: lo coges si lo quieres o lo cambias entero si no.
En el árbol de configuración puedes ver un contrato de delegación ctx.subagents cuya única labor es registrar "quién puede ser un subagente". Luego distintos plugins provider montan backends concretos sobre él:
| Plugin | Qué ejecuta |
|---|---|
subagent-spawn-in-process | Un subagente nuevo in-process (contexto independiente) |
subagent-fork-in-process | "Deriva" un subagente a partir del historial completado de la sesión padre |
subagent-acp | Usa el Agent Client Protocol, acepta Agents compatibles con ACP out-of-process |
subagent-codex | Ejecuta un Codex real (protocolo oficial app-server) |
subagent-claude-code | Ejecuta un Claude Code real (Agent SDK oficial) |
subagent-dsh-sdk | Arranca otro Harness completo vía el SDK de TypeScript |
¿Qué ve el Agent principal? Son unas "herramientas visibles por el modelo". Abre el árbol de configuración web, por defecto trae:
| Herramienta | Qué hace | Por defecto |
|---|---|---|
subagent | Despacha un subagente, modo continuable | on |
subagent_fork | Despacha un subagente con la memoria de la sesión padre, one-shot | on |
ralph | Cada ronda intercambia un subagente nuevo para avanzar el mismo objetivo | on |
workflow | Escribe scripts para orquestar en paralelo varias sub-tareas | off (no habilitado por defecto) |
send_message | Envía instrucciones de seguimiento a un subagente concreto | off (no habilitado por defecto) |
interrupt_agent | Interrumpe la ronda actual de un subagente | off (no habilitado por defecto) |
list_agents | Lista los subagentes actuales y su estado | off (no habilitado por defecto) |
Así que nada más sacarlo de la caja puedes llamar directamente a subagent, subagent_fork y ralph. Las demás herramientas están desactivadas por defecto y hay que activarlas a mano, o solo tienen sentido en "modo continuable" — la siguiente sección cubre dónde aparece cada una.
spawn vs fork: dos "aperturas"
Los dos subagentes más usados se diferencian solo en una cosa: si traen consigo el historial de la sesión padre.
subagent(spawn): contexto totalmente nuevo. El subagente no sabe de qué ha estado hablando el Agent principal, solo sigue las instrucciones que le das en este momento. Ahorra tokens, va bien para tareas independientes.subagent_fork(fork): hereda la parte completada de la sesión padre. El subagente sabe "qué veníamos analizando hasta ahora" y puede continuar desde ahí. Cuesta un poco más por repetir contexto, va bien para tareas que tienen que apoyarse en conclusiones anteriores.
Un detalle que conviene tener en cuenta: dsh pone "si hereda o no" directamente en la descripción de la herramienta — las descripciones estilo spawn dicen "no puede ver esta conversación", las estilo fork dicen "no puede ver el turno en curso". Es decir, el propio modelo sabe si tiene que repetir el contexto en las instrucciones.
Una línea para recordar
subagent es como lanzar en paracaídas a un compañero nuevo, que solo tiene tu brief verbal de la tarea; subagent_fork es como pegarle el acta de la reunión, "continúa desde donde lo dejamos".
Manos a la obra: tus primeros subagentes en paralelo
En paralelo, arranca tres subagentes, cada uno haciendo:
- Ordenar la estructura del directorio
packages/del repodeepseek-harnessy explicar qué hace cada familia de capacidades;- Resumir los conceptos clave que cubre el README raíz;
- Buscar la documentación relacionada con subagent bajo
docs/y listarla. Cuando los tres hayan terminado, fusiona los resultados en un único resumen.
Fíjate en los tres elementos de esta frase; si falta cualquiera habrá caos:
| Elemento | Por qué hace falta |
|---|---|
| Reglas de división de la tarea | Dile al modelo "divide en qué trozos", si no se lo inventará él |
| Mecanismo de espera (esperar a que todos terminen) | Sin esto, el Agent principal puede empezar a organizar resultados incompletos antes de que un subagente haya terminado |
| Requisito de salida (fusionar en un resumen) | Sin esto, los tres subagentes te escupen cada uno un montón de texto en crudo y lo tienes que montar tú |
Tras enviar, en la conversación verás que el modelo hace varias llamadas subagent seguidas — eso es el despacho. En el modo continuable por defecto, el modelo "primero manda juntos los que se pueden paralelizar y luego sigue con su propio trabajo", en vez de esperar a que vuelva el primer subagente.
Si algunos subagentes terminan antes, no pasa nada — el Agent principal seguirá esperando a los que faltan y solo empezará a fusionar cuando estén todos:
Foreground / Background / Continuable: tres modos de ejecución
Los subagentes no son solo "despachar y esperar al resultado". Según "si esperar o no, si seguir hablando o no" se dividen en tres modos:
| Modo | Cuándo usarlo | Qué ves |
|---|---|---|
| Foreground one-shot | El siguiente paso depende ya mismo de este resultado | Esperar a que el subagente devuelva el texto final |
| Background job (one-shot en background) | No necesitas esperar, recoges luego | started background subagent job <id>, usa job_output para recoger, job_kill para parar |
| Subagente continuable | Puede que necesites mandar instrucciones de seguimiento, ida y vuelta | started subagent <childId>, puedes mandarle mensajes después |
El subagent por defecto está en modo continuable: se despacha para correr en background por defecto y el Agent principal hace lo suyo; cuando el subagente termina, una notificación de callback entrega "ya está, aquí va el resultado". El modelo solo cambia a espera en foreground cuando el siguiente paso realmente necesita el resultado.
Cuando quieras tener más control sobre un subagente continuable, necesitas activar send_message (instrucciones de seguimiento), interrupt_agent (interrumpir la ronda actual, sin destruir, se puede reanudar), list_agents (listar subagentes y estados). Están desactivados por defecto porque la mayoría de escenarios no los necesitan — es una "capacidad avanzada, actívala cuando la necesites".
workflow y ralph: dos herramientas de "orquestación"
Además de "dividir en trozos y correr en paralelo", dsh también tiene dos tipos de orquestación más estructurada, ambos plugins:
| Herramienta | Qué hace | Apta para |
|---|---|---|
workflow | Dejar que el modelo escriba un pequeño script de orquestación, reparta sub-tareas con agent() / parallel() / pipeline() y al final devuelva un resultado | Muchas tareas, estructura fija, necesidad de controlar con precisión el orden de ejecución (p. ej. analizar 10 documentos a la vez) |
ralph | Cada ronda intercambia un subagente nuevo para avanzar el mismo objetivo, con un informe de traspaso al final de cada ronda para la siguiente | Refinamiento multi-ronda, fácil caer en un surco, tareas creativas o de debugging |
ralph está activado por defecto (subagent usa spawn, máximo 64 rondas). workflow está desactivado por defecto — su script corre en un hilo aparte, es una "restricción de orquestación" no un sandbox de seguridad, solo merece la pena activarlo para escenarios claros por lotes.
::: tl;dr Paralelo del día a día → subagent; Para continuar con conclusiones previas → subagent_fork; Lotes estructurados → workflow (off por defecto); Refinamiento iterativo anti-surco → ralph. :::
Errores comunes
| Trampa | Cómo evitarla |
|---|---|
| Varios subagentes escribiendo en el mismo archivo a la vez | Las tareas en paralelo deben priorizar lecturas (buscar, analizar, revisar); para escrituras, deja que el Agent principal reúna todos los resultados y escriba de una sola vez |
| Olvidaste decir "espera a que todos terminen" en las instrucciones | Incluye el mecanismo de espera al despachar, si no el Agent principal puede empezar a trabajar con la mitad de los resultados |
| Tareas partidas demasiado finas | Cada subagente tiene overhead de arranque; partir una tarea de 5 minutos en 10 subagentes en realidad es más lento; parte solo hasta "completar independientemente algo con sentido" |
| Subagentes que se anidan sin límite | La profundidad de delegación tiene tope (por defecto 3, 0 significa prohibido); mantener una topología en estrella "Agent principal → subagente" es lo más estable |
Qué aprendiste en este capítulo
Apruebas si puedes completar los siguientes puntos:
- [ ] Enunciar los tres puntos duros de las tareas largas con un solo Agent y el valor esencial del multi-Agent (aislamiento de contexto)
- [ ] Saber que los subagentes también son plugins:
ctx.subagentses el contrato de delegación, spawn / fork son los dos backends más usados - [ ] Distinguir
subagent(contexto totalmente nuevo) desubagent_fork(con la parte completada de la sesión padre) - [ ] Haber ejecutado al menos una vez un "dividir tareas + esperar a que todas terminen + fusionar resultados" con subagentes en paralelo y haber visto la llamada subagent en la Trayectoria
- [ ] Enunciar las diferencias entre los modos foreground, background job y subagente continuable
- [ ] Saber qué hacen
workflow,ralph,send_message,interrupt_agent,list_agents