Orquestar en LangGraph

3.1El problema

Tu worker de L2 funciona. Lo lanzaste a mano, con el brief escrito por ti, sobre un subtema concreto. Devolvió su destilado de 1.500 tokens y lo metiste en el informe. Un worker, un subtema, control manual.

El encargo real de N4 no cabe así. Tiene diez subtemas independientes sobre 200 documentos. Necesitas varios workers a la vez, y alguien que decida quién investiga qué, recoja los destilados y escriba el informe. Ese "alguien" no puedes ser tú a mano: es código.

La primera tentación es delegar con un brief de una línea: "investiga el subtema 3". Parece suficiente. No lo es. Anthropic documentó qué pasa con esa delegación. Sin objetivo, formato de salida, guía de fuentes y límites claros, los subagentes "duplican trabajo, dejan huecos o no encuentran la información necesaria" (E.1). · fuente: corpus E.1.

La delegación vaga no es un detalle de pulido. Es EL modo de fallo de este patrón. Un orquestador con código impecable y briefs flojos produce un informe peor que tu worker manual de L2. En esta lección montas la orquestación: el grafo supervisor, los handoffs y —lo que de verdad decide el resultado— los briefs.

3.2Qué vas a poder hacer

Al terminar serás capaz de:

• Distinguir los tres patrones multi-agente de LangGraph (supervisor, swarm, jerárquico) y justificar por qué el lab usa supervisor.
• Implementar un grafo supervisor con 2 workers exploradores de ventana propia, usando las firmas verificadas de langgraph-supervisor y Command.
• Escribir un brief de delegación con los cuatro elementos de Anthropic: objetivo, formato de salida, guía de tools/fuentes y límites.
• Predecir el fallo de un brief defectuoso y reescribirlo, y verificar en una traza que ningún contenido del worker contaminó el contexto del supervisor.

Necesitas saber antes:

• De L2 (/cursos/context-engineering/aislamiento/subagentes-como-palanca-de-contexto): qué cruza la frontera (el destilado) y qué muere dentro del sub-contexto. Lo recuperamos en 3.3.
• De N0·L3 (/cursos/context-engineering/diagnostico/el-presupuesto-de-tu-agente): qué partida del presupuesto crecía por turno en el monolítico. También en 3.3.
• El esqueleto congelado de Magallanes: el grafo de LangGraph y sus 3 tools (buscar, leer, escribir_seccion).

3.3Recupera

Antes de seguir, responde de memoria. Esto reactiva lo anterior y engancha lo nuevo.

1. De L2: en el patrón de sub-agentes, ¿qué información debe cruzar la frontera hacia el orquestador y qué debe morir dentro del sub-contexto?
2. De N0·L3: en el Magallanes monolítico, ¿qué partida del presupuesto crecía por turno y por qué no se podía frenar?
3. ¿Cuál de las 3 tools de Magallanes escribe en el informe, y cuáles solo leen del corpus?

En el monolítico crecían los tool results. En el orquestado crecen los destilados que devuelven los workers: misma contabilidad, otra pendiente. El presupuesto no desaparece con la orquestación; se reparte. Esa es la idea que arrastras a 3.4.

3.4El concepto

Los tres patrones multi-agente de LangGraph

LangGraph ofrece tres formas de coordinar varios agentes. Defínelas antes de elegir, porque la elección no es estética: cambia quién acumula contexto y cuántas llamadas al modelo gastas.

Un patrón supervisor es una arquitectura donde un agente central enruta el trabajo: tras cada especialista, el control vuelve al supervisor, que decide el siguiente paso. La analogía: un editor de redacción que reparte temas a corresponsales y recoge cada crónica antes de asignar la siguiente. Dónde falla la analogía: el editor humano recuerda el contexto de toda la redacción; el supervisor solo ve lo que cada destilado le devuelve. · fuente: corpus E.4.

Un patrón swarm es una arquitectura sin nodo central: los agentes se pasan el control directamente entre ellos, y el sistema "recuerda cuál agente fue el último activo" (E.4). Sirve cuando el flujo es una conversación que salta de especialista a especialista sin un coordinador que medie cada turno. · fuente: corpus E.4.

Un patrón jerárquico es supervisores de supervisores: subgrafos anidados, cada uno con su propio coordinador. Sirve cuando el sistema es tan grande que un solo supervisor no abarca todos los especialistas. · fuente: corpus E.4. La documentación de "hierarchical agent teams" estaba en transición con LangGraph v1.0 a junio de 2026; el lab no lo usa. · fuente: api-nivel4 (matiz E.4).

El lab usa supervisor. La razón: tu encargo es breadth-first read-heavy —varios subtemas independientes que solo leen— y necesitas un único punto que acumule destilados y escriba el informe. El supervisor es ese punto. El swarm dispersaría la escritura; el jerárquico añade complejidad que tu encargo no pide todavía.

El handoff: cómo el control salta del supervisor al worker

Un handoff es el mecanismo por el que un nodo cede el control a otro y le pasa estado. En LangGraph, un nodo lo ejecuta devolviendo un objeto Command con un destino (goto) y una actualización de estado (update). · fuente: corpus E.4, api-nivel4.

Dentro de un subgrafo, el handoff hacia el grafo padre lleva además graph=Command.PARENT: le dice a LangGraph que el nodo destino vive en "el grafo padre más cercano", no en el subgrafo actual. · fuente: api-nivel4 (Command, tier 1). Junto al salto se añade un ToolMessage de acuse al historial —un mensaje que confirma "transferido a X"— para que la traza de mensajes quede coherente. · fuente: corpus E.4, api-nivel4.

No tienes que escribir ese handoff a mano. El paquete langgraph-supervisor (v0.0.31, 19 nov 2025) trae create_handoff_tool, que fabrica la tool de transferencia por ti. · fuente: api-nivel4 (ÍTEM 1, tier 1). Un aviso del propio paquete: su readme recomienda, para la mayoría de casos, montar el patrón supervisor directamente con tools en vez de usar la librería. · fuente: api-nivel4 (ÍTEM 1, matiz). El lab usa el paquete por brevedad didáctica; el código a mano es una alternativa válida.

Hay una trampa de import que produce un bug silencioso. Existen DOS create_handoff_tool: una en langgraph_supervisor y otra en langgraph_swarm. La del swarm NO tiene el parámetro add_handoff_messages. Importar del paquete equivocado compila y falla en silencio. · fuente: api-nivel4 (ÍTEM 1b). Verifica siempre de qué paquete importas.

El brief de delegación: los cuatro elementos

Aquí está lo que de verdad decide el resultado. Un brief de delegación es la instrucción que el supervisor pasa a un worker. Anthropic documentó los cuatro elementos que necesita cada delegación, "sin esto: duplicación de trabajo" (E.1):

1. Objetivo — qué subtema investigar, sin ambigüedad.
2. Formato de salida — la forma exacta del destilado: claims + doc_id citados, ≤2.000 tokens.
3. Guía de tools/fuentes — qué tools usar (buscar, leer) y dónde buscar.
4. Límites claros — qué NO hacer: no salirse del subtema, no exceder N llamadas, no escribir.

· fuente: corpus E.1. Estos cuatro elementos son la dim 3 de la rúbrica C4 ("handoffs completos"). Un brief que omite el formato de salida recibe respuestas de 10K tokens; uno que omite los límites recibe trabajo duplicado. El brief no es prosa de relleno: es la interfaz entre dos contextos aislados.

La decisión de diseño del lab: la frontera read/write

El lab toma una decisión deliberada sobre las tools por rol. Los workers solo ven buscar y leer; escribir_seccion queda exclusivamente en el orquestador. Esto no es dogma; es la aplicación directa de la lección de Cognition.

Cognition lo formula así: "Actions carry implicit decisions, and conflicting decisions carry bad results" (E.2, verbatim) —las acciones cargan decisiones implícitas; las decisiones en conflicto producen malos resultados. · fuente: corpus E.2. Dos workers escribiendo el informe en paralelo tomarían decisiones de estructura y tono incompatibles. Nadie podría reconciliarlas —es el fallo del ejemplo Flappy Bird de su post. La lectura en paralelo no tiene ese problema: dos workers que leen documentos distintos no se pisan.

LangChain lo refuerza con una observación que el corpus marca como paráfrasis de confianza media: "las acciones de escritura en conflicto suelen producir resultados mucho peores que las lecturas en conflicto" (E.5). · fuente: corpus E.5 (confianza media). La conclusión de diseño es robusta: paraleliza las lecturas, centraliza la escritura. Por eso un solo rol ve escribir_seccion.

Antes del bloque de código

El grafo supervisor tiene más piezas móviles que cualquier cosa anterior del curso: un grafo padre, dos subgrafos worker, handoffs, estado compartido y briefs. Lo que lo hace difícil no es ninguna pieza suelta; es ver cómo encajan.

La estrategia: lee primero el diagrama del flujo completo en 3.5, sin mirar el código. Cuando tengas la forma en la cabeza —supervisor reparte, workers leen aislados, supervisor recoge y escribe—, entonces lee el código nodo a nodo. No al revés.

Lo que NO es orquestación

Un contraejemplo afila la frontera. Imagina un "orquestador" que, en cada handoff, reenvía a cada worker el historial completo del hilo principal. Suena a delegar. No lo es.

Si el worker recibe todo el historial del supervisor, su ventana arranca ya cargada con lo que otros workers leyeron. No tiene ventana limpia; no aísla nada. Eso es un monolítico con pasos extra: pagas la coordinación de un sistema multi-agente sin comprar la ventana limpia que lo justificaba. La orquestación real pasa al worker solo su brief —nada más.

3.5Míralo funcionar

Vamos a montar Magallanes-N4 mínimo: un grafo supervisor con 2 workers exploradores de ventana propia, briefs con los cuatro elementos, y trazas que muestran los contextos separados.

Primero el diagrama. Léelo entero antes del código. El flujo: el supervisor recibe el encargo, fabrica un brief por subtema y delega. Cada worker explora en su ventana con buscar + leer y devuelve un destilado. El supervisor recoge los destilados y —solo él— escribe con escribir_seccion.

                    ┌─────────────────────────────┐
   encargo  ───────▶│        SUPERVISOR           │
                    │  ventana: encargo +         │
                    │  destilados (~1-2K c/u)     │
                    │  tool: escribir_seccion     │
                    └───┬───────────────────┬─────┘
            brief 1 │   │ handoff           │ brief 2 │ handoff
                    ▼   │                   ▼         │
          ┌──────────────────┐    ┌──────────────────┐
          │  WORKER explor. A │    │  WORKER explor. B │
          │  ventana PROPIA   │    │  ventana PROPIA   │
          │  decenas de miles │    │  decenas de miles │
          │  tools: buscar,   │    │  tools: buscar,   │
          │         leer      │    │         leer      │
          └────────┬─────────┘    └────────┬─────────┘
        destilado A │ (claims + doc_id)     │ destilado B
                    └──────────▶ SUPERVISOR ◀┘

Fíjate en lo que el diagrama hace explícito: la ventana del worker crece a decenas de miles de tokens (lee documentos enteros), pero al supervisor solo le cruza el destilado. Esa asimetría es todo el punto del nivel.

El worker explorador

El worker es un nodo con su propia ventana. Recibe un brief, ejecuta buscar + leer, y devuelve un destilado. No ve escribir_seccion. El código muestra solo la superficie verificada; la lógica interna del loop va como ....

1# magallanes_n4.py — worker explorador (superficie verificada; lógica interna -> ...)
2from langgraph.graph import StateGraph, MessagesState, START, END
3from langgraph.types import Command   # también: from langgraph.graph import Command
4
5def worker_explorador(state: MessagesState) -> Command:
6    # El brief llega como el último mensaje del estado del subgrafo.
7    # En SU ventana propia: ejecuta buscar() + leer() sobre el corpus.
8    # Lee documentos enteros -> la ventana crece a decenas de miles de tokens.
9    # SOLO ve las tools de lectura: buscar, leer. NO ve escribir_seccion.
10    ...
11    destilado = ...   # claims accionables + doc_id citados, <= 2.000 tokens
12
13    # Handoff de vuelta al supervisor (grafo padre): solo cruza el destilado.
14    return Command(
15        goto="supervisor",
16        update={"messages": [{"role": "assistant", "content": destilado}]},
17        graph=Command.PARENT,   # el nodo "supervisor" vive en el grafo padre
18    )

Tres cosas de este nodo:

• graph=Command.PARENT indica que goto="supervisor" apunta al grafo padre, no al subgrafo del worker. Sin esto, LangGraph buscaría un nodo "supervisor" dentro del subgrafo y no lo hallaría. · fuente: api-nivel4 (Command, tier 1).
• El update que cruza la frontera contiene SOLO el destilado. El texto de los documentos leídos no aparece aquí: muere dentro del sub-contexto del worker.
• El worker recibe buscar y leer; nunca escribir_seccion. La frontera read/write se aplica en el toolset, no por buena voluntad.

Antes de pasar el worker al supervisor hay que empaquetarlo en un grafo compilado. create_supervisor espera list[Pregel] —grafos compilados, no funciones. Aquí se ve para qué importamos StateGraph y START:

1# Empaquetar el nodo worker en un subgrafo compilado (Pregel)
2worker_subgraph = StateGraph(MessagesState)
3worker_subgraph.add_node("explorador", worker_explorador)
4worker_subgraph.add_edge(START, "explorador")
5worker_a = worker_subgraph.compile()   # ahora worker_a es un Pregel; idem worker_b

Si pasaras la función worker_explorador directamente a create_supervisor, chocarías con un TypeError: espera un grafo compilado donde tú diste una función. · fuente: api-nivel4 (ÍTEM 2, tier 1).

El supervisor y el grafo

El supervisor delega con briefs, acumula destilados y es el único que escribe. El paquete langgraph-supervisor arma el enrutado; le pasas los agentes worker y el modelo. La firma es la verificada.

1# magallanes_n4.py — supervisor (firma verificada de langgraph-supervisor v0.0.31)
2from langgraph_supervisor import create_supervisor
3# OJO: importar de langgraph_supervisor, NO de langgraph_swarm (bug silencioso).
4
5# Brief con los 4 elementos de Anthropic (E.1). Esto es lo que decide el resultado.
6BRIEF_EXPLORADOR = """\
7OBJETIVO: investiga el subtema «{subtema}» del encargo, nada más.
8FORMATO DE SALIDA: claims accionables + el doc_id de cada uno. Máximo 2.000 tokens.
9TOOLS/FUENTES: usa buscar() y leer() sobre el corpus del encargo. No inventes doc_id.
10LÍMITES: no te salgas del subtema; máximo 10 llamadas a tools; NO escribas el informe.
11"""
12
13supervisor_graph = create_supervisor(
14    [worker_a, worker_b],      # los 2 subgrafos worker compilados
15    model=modelo,              # el LLM del supervisor (requerido)
16    prompt=(
17        "Eres el orquestador de Magallanes. Reparte cada subtema a un worker "
18        "con un brief completo (objetivo, formato, tools, límites). "
19        "Acumula sus destilados. Solo TÚ escribes con escribir_seccion."
20    ),
21    tools=[escribir_seccion],  # escribir_seccion vive aquí, no en los workers
22    output_mode="last_message",   # al supervisor solo cruza el último mensaje del worker
23)
24graph = supervisor_graph.compile()   # create_supervisor devuelve StateGraph SIN compilar

Un matiz que cambia tu diseño: parallel_tool_calls (default False) controla si el supervisor emite varios handoffs en un mismo turno. Con False, los workers corren secuencialmente —el supervisor enruta a worker_a, espera su destilado, luego enruta a worker_b. Para ejecución concurrente real, pasa parallel_tool_calls=True. · fuente: api-nivel4 (ÍTEM 2). La ventaja de las ventanas aisladas —el contexto del worker no contamina el del supervisor— existe en ambos casos; la reducción de latencia solo con True.

El parámetro output_mode decide cuánto del worker cruza la frontera. Con "last_message" (el default) solo vuelve el último mensaje del subagente —el destilado—; con "full_history" volvería todo su historial, decenas de miles de tokens. · fuente: api-nivel4 (ÍTEM 2, matiz). Para el context budget del nivel, "last_message" es la elección: es la frontera de L2 expresada en un parámetro.

Y create_supervisor devuelve un StateGraph SIN compilar. Hay que llamar .compile() antes de invocarlo. · fuente: api-nivel4 (ÍTEM 2, tier 1).

Las trazas: ver los contextos separados

Para comprobar que el aislamiento es real, instrumenta el grafo con Langfuse. El CallbackHandler registra cada contexto por separado. La firma es la verificada (F.7).

1# Instrumentación: trazas que muestran los contextos separados (F.7)
2from langfuse.langchain import CallbackHandler   # v4: sin update_trace
3
4handler = CallbackHandler()
5result = graph.invoke(
6    {"messages": [{"role": "user", "content": ENCARGO_QUE_EXCEDE_LA_VENTANA}]},
7    config={"callbacks": [handler], "configurable": {"thread_id": "run-c4"}},
8)

En la traza verás dos perfiles de contexto distintos. El de cada worker crece a decenas de miles de tokens —lee documentos enteros. El del supervisor solo suma los destilados: dos entradas de ~1.500 tokens, no dos documentos completos. Esa diferencia entre las dos curvas de la traza es la prueba de que el aislamiento funciona. · fuente: corpus F.7.

Self-explanation

Antes de leer la respuesta, intenta tú. ¿Por qué importa el ToolMessage de acuse para que el historial del supervisor siga siendo coherente?

3.6Hazlo tú

Andamiaje decreciente: primero añades un worker con esqueleto dado, luego rediseñas un reparto sin esqueleto.

Ejercicio A — un tercer worker (esqueleto dado)

El encargo tiene un tercer subtema. Añade un worker_c al grafo. El nodo lo tienes; el brief está en blanco.

1def worker_c(state: MessagesState) -> Command:
2    # ... mismo patrón que worker_explorador: buscar + leer en ventana propia
3    return Command(goto="supervisor", update={...}, graph=Command.PARENT)
4
5# Tu tarea: escribe el BRIEF_C con los 4 elementos para el subtema "financiación".
6BRIEF_C = """\
7OBJETIVO:  ___
8FORMATO DE SALIDA:  ___
9TOOLS/FUENTES:  ___
10LÍMITES:  ___
11"""
12
13# Y regístralo en el supervisor:
14supervisor_graph = create_supervisor(
15    [worker_a, worker_b, worker_c],   # <- añade worker_c
16    model=modelo,
17    prompt="...",
18    tools=[escribir_seccion],
19    output_mode="last_message",
20)

Rellena BRIEF_C con los cuatro elementos para el subtema "financiación". Recuerda los límites: que no se solape con los subtemas de A y B, que no exceda llamadas, y que NO escriba.

Ejercicio B — el reparto que se solapa (sin esqueleto)

Dos briefs reales se solapan: el de worker_a dice "investiga la ruta y su financiación" y el de worker_c dice "investiga la financiación de la expedición". Los dos workers leen los mismos documentos de financiación. Resultado: lecturas duplicadas y un coste que no compra calidad.

Rediseña el reparto de subtemas y los límites de cada brief para que no haya solape. No hay esqueleto: defines tú las fronteras de cada subtema.

Elaborative interrogation — antes de rediseñar, predice: ¿qué partida del presupuesto del SUPERVISOR sube cuando dos workers leen los mismos documentos?

Normaliza el error aquí. El fallo nº1 al delegar es el brief vago —sin objetivo claro, los workers improvisan y duplican. El nº2 es no fijar el formato de salida: recibes destilados de 10K tokens que reinflan el contexto del supervisor y borran la ventaja del aislamiento. Los dos se evitan con los cuatro elementos.

3.7Comprueba

Sin pistas. Gate de maestría: diagnosticar un brief defectuoso, predecir su fallo y reescribirlo.

El supervisor de un compañero delega con este brief. Tiene defectos que lo invalidan.

1BRIEF_DEFECTUOSO = """\
2Investiga el subtema 3 y devuelve lo que encuentres.
3"""

1. Identifica qué elementos del brief faltan (de los cuatro de Anthropic).
2. Predice el fallo esperable de cada omisión.
3. Reescribe el brief completo.
4. Verifica en una traza Langfuse que ningún contenido del worker contaminó el contexto del supervisor: ¿qué buscarías en la traza?

1BRIEF_REESCRITO = """\
2OBJETIVO: investiga el subtema «tripulación de la expedición», nada más.
3FORMATO DE SALIDA: claims accionables + el doc_id de cada uno. Máximo 2.000 tokens.
4TOOLS/FUENTES: usa buscar() y leer() solo sobre el corpus del encargo. No inventes doc_id.
5LÍMITES: no te salgas del subtema; máximo 10 llamadas a tools; NO escribas el informe.
6"""

3.8Conecta

Acabas de montar la orquestación. Con esto, dos dimensiones de la rúbrica C4 quedan cubiertas.

La dim 2 (aislamiento real) la cierran los workers de ventana propia. Cada uno explora con decenas de miles de tokens y al supervisor solo le cruza el destilado, como viste en la traza. La dim 3 (handoffs completos) la cierran los briefs con los cuatro elementos. Sin objetivo, formato, tools y límites, el sistema duplica trabajo y deja huecos —y ya sabes diagnosticar ese fallo.

La frontera read/write no fue un capricho. Es la lección de Cognition aplicada: paralelizas las lecturas, que no se pisan, y centralizas la escritura, donde las decisiones en conflicto producirían un informe inconsistente. Por eso escribir_seccion vive solo en el orquestador.

Cierra el arco de 3.1: empezaste con un worker manual y un brief de una línea. Ahora tienes un grafo supervisor que reparte con briefs completos, aísla las lecturas y centraliza la escritura. Lo que falta es integrarlo con las palancas de N1-N3 y medirlo contra el monolítico de N0.

Eso es L4 (/cursos/context-engineering/aislamiento/el-checkpoint-macro), el cuerpo del checkpoint macro. Integra la compaction en el hilo del orquestador (N1), el informe y las notas como artefactos externos (N2), y el toolset por rol que ya empezaste aquí (N3). Y ejecuta la comparativa final N0-vs-N4 con los costes medidos.

3.9Reflexiona

Tómate un minuto. Responder esto por escrito consolida lo aprendido mejor que releer.

• ¿Qué aprendiste? Resume en una frase por qué el brief de delegación —y no el código del grafo— es lo que decide la calidad del sistema orquestado.
• ¿Qué sigue sin estar claro? ¿Tienes clara la diferencia entre output_mode="last_message" y "full_history", y por qué la elección afecta al context budget? Si no, vuelve a 3.5, el supervisor.
• ¿Qué harías distinto? La próxima vez que delegues una tarea —a un agente o a una persona—, ¿qué cuatro elementos te asegurarías de incluir antes de soltar el trabajo?

Esto requiere práctica. La intuición de "qué tiene que llevar un brief para que no haya que rehacer el trabajo" llega diseñando handoffs reales y leyendo sus trazas, no memorizando los cuatro elementos.