Módulo 2: El patrón supervisor/router

Descripción

El Módulo 1 te dejó con un criterio, no con ningún mecanismo construido: definiste qué es un sistema multi-agente, mediste el costo real de coordinar (llamadas al modelo, hops), y confirmaste —con números, no con intuición— cuándo ese costo se justifica. La medición central del módulo anterior (lección 05) fue un supervisor que solo tenía un especialista posible al que delegar —booking_agent—, así que su única decisión real era "¿delego, o no?". Este módulo construye lo que ese supervisor todavía no sabía hacer: elegir entre varios especialistas, leyendo la petición para decidir cuál de los tres —booking_agent, policy_agent, pricing_agent— debe resolverla.

Este es el primero de los cinco patrones que anticipó la lección 07 del Módulo 1. Supervisor/ router: un coordinador central que recibe la petición, decide —por reglas o por el modelo— a qué especialista delegar, despacha la tarea, y agrega el resultado antes de responder. Vas a construir las dos formas de tomar esa decisión —determinista, con reglas de palabras clave que se ejecutan de verdad, y por decisión del modelo, concepto con un ejemplo realista— y vas a medir cuándo cada una alcanza. La pieza central del módulo (lección 06) es un dispatcher completo, ejecutado de punta a punta, enrutando tres peticiones distintas al agente correcto de cada una.

Regla dura de este módulo (léela antes de seguir)

Se mantiene exactamente la misma línea del Módulo 1: la decisión de cada agente —qué tool llamar, qué responder— no se ejecuta. Es un guion escrito a mano, rotulado como concepto (claude-sonnet-5), nunca una llamada real a una API. Lo que sí se ejecuta, de verdad, con Python 3.14 y su librería estándar, es la orquestación completa: el runner de cada agente (reusado sin cambios de agent-fundamentals M4/M5), el router determinista con sus reglas, el paso de mensajes entre supervisor y especialista, y el dispatcher de punta a punta. La única decisión que sí se ejecuta de verdad en este módulo es, precisamente, la del router determinista —no es una decisión del modelo, es una función de Python que compara palabras clave, así que no viola la regla: no hay ningún LLM detrás de esas líneas.

Dónde estamos en el ecosistema

agent-fundamentals-and-tool-calling-guide (ya completa)
  -> construyó UN agente: tools, protocolo, el bucle, multi-tool, memoria, robustez

multi-agent-orchestration-guide (esta guía)
├── Módulo 1: Por qué multi-agente (y cuándo no)  (completo)
│   → El criterio de decisión, medido con números reales
├── Módulo 2: El patrón supervisor/router  ← ESTÁS AQUÍ
│   → El primer patrón: ruteo determinista vs. ruteo por decisión del modelo
├── Módulo 3: Pipelines secuenciales
├── Módulo 4: Fan-out paralelo y agregación
├── Módulo 5: Handoff y delegación
├── Módulo 6: Estado compartido y el patrón blackboard
├── Módulo 7: Orquestando el sistema completo de Reservo
└── Módulo 8: Proyecto — el sistema multi-agente de Reservo

Este módulo no re-explica la definición de sistema multi-agente, ni el costo de coordinar, ni las tres señales de la lección 06 del Módulo 1 —se asumen dominadas—. Lo nuevo acá es exclusivamente el mecanismo de decisión: cómo el supervisor sabe, para una petición que nunca vio antes, a cuál de los tres especialistas mandarla.

Analogía: la recepción de un edificio de oficinas

Imagina la recepción de un edificio con tres departamentos: reservas, atención de políticas y comparación de tarifas. Un visitante llega y necesita que alguien lo dirija al piso correcto antes de que pueda resolver lo que vino a hacer.

Hay dos formas de que la recepción funcione. La primera es un cartel con reglas fijas: "si tu consulta incluye la palabra 'reserva', tercer piso; si incluye 'política', quinto piso; si incluye 'comparar', séptimo piso". Es rápida, gratuita, y funciona perfecto para el 80% de los visitantes que llegan con una consulta clara. Pero un visitante que dice "necesito cancelar porque no voy a poder venir mañana, ¿me cobran algo?" confunde al cartel: menciona "cancelar", que suena a reservas, pero en realidad quiere saber sobre un cargo —una pregunta de política—. El cartel, que solo lee palabras sueltas, lo manda al piso equivocado con total confianza.

La segunda forma es una recepcionista humana que escucha la frase completa, entiende la intención real —no solo las palabras que aparecen— y dirige al piso correcto incluso en los casos que el cartel no anticipó. Es más lenta y, en un sistema real, cuesta más (le pagas un sueldo; acá, consume una llamada al modelo). La pregunta que abre este módulo es exactamente esa: ¿cuándo alcanza el cartel, y cuándo hace falta la recepcionista? Vas a construir los dos, y vas a medir la diferencia con la misma petición ambigua que confunde al cartel.

El caso que acompaña el módulo: el supervisor de Reservo

agent-fundamentals construyó las cuatro tools canónicas de Reservo. El Módulo 1 de esta guía las repartió en tres especialistas —reusados sin ningún cambio de fondo:

booking_agent — las cuatro tools canónicas (list_rooms, get_quote, book_room, cancel_booking). Cotiza, reserva, cancela.
policy_agent — search_docs(query) -> str, el stub mínimo por palabra clave que ya construiste en el Módulo 1, lección 06 (no-show-policy, cancellation-policy).
pricing_agent — el Módulo 1 lo nombró y usó get_quote sin envolverlo en un agente completo. Este módulo lo construye, ejecutado, como un agente de verdad —con su propio runner corriendo sobre un guion propio, no solo una llamada suelta a get_quote— en la lección 05.

Lo nuevo de este módulo es el coordinador: un supervisor que recibe una petición cruda del socio, decide cuál de los tres especialistas debe resolverla, la despacha, y compone la respuesta final. Vas a construir esa decisión de dos formas —determinista (lección 03) y por decisión del modelo (lección 04)— y vas a verlas trabajar juntas, sobre los tres especialistas completos, en el dispatcher de la lección 06.

Frontera con lo que viene (y con lo que ya viste)

Una petición a la vez, un especialista a la vez —ese es el alcance de este módulo. Dos cosas que este módulo no cubre, a propósito, porque tienen su propio módulo dedicado:

Cuando la tarea SIEMPRE necesita los mismos pasos, en el mismo orden, sin ninguna decisión de ruteo —por ejemplo, cotizar, después validar la política de cancelación, después confirmar la reserva, siempre en ese orden, sin importar qué pidió el socio— eso es un pipeline, y lo verás en el Módulo 3. La diferencia de fondo: un supervisor decide a quién delegar, leyendo la petición; un pipeline no decide nada, el orden está fijo de antemano.
Cuando dos sub-tareas independientes se despachan al mismo tiempo, en paralelo real, y sus resultados se agregan —como "cotiza Focus pro 3h y dime la política de cancelación" del Módulo 1, lección 06— eso es fan-out, y lo profundiza el Módulo 4. Este módulo se queda con el caso de una decisión, un especialista elegido por vez.

Con esto claro, ya puedes distinguir los tres patrones sin confundirlos: supervisor decide quién trabaja (este módulo); pipeline fija el orden sin decidir nada (M3); fan-out reparte el trabajo simultáneo entre varios que ya sabes que necesitas (M4).

Prerequisitos

Conocimiento requerido:

✅ Módulo 1 completo de esta guía: la definición de sistema multi-agente, el costo de coordinar medido, las tres señales que justifican multi-agente, y el mapa de los cinco patrones.
✅ agent-fundamentals-and-tool-calling-guide: el contrato de una tool, el protocolo tool_use/tool_result, run_agent_parallel y dispatch_parallel.

NO requerido:

❌ No necesitas una API key ni conexión a internet: la decisión de cada agente sigue siendo concepto, escrita a mano.
❌ No necesitas LangChain, LangGraph, CrewAI ni ningún framework de orquestación.

Entorno:

✅ Python 3.14.0 con su librería estándar. Nada que instalar.

Roadmap del módulo

Lección 01 — Introducción al módulo (esta)

El patrón supervisor/router, la analogía de la recepción, y la frontera con pipeline (M3) y fan-out (M4).

Lección 02 — Qué hace un supervisor

La anatomía completa: recibir, decidir, despachar, agregar. El registro SPECIALISTS con los tres agentes y el wrapper run_specialist que envuelve el runner sin modificarlo.

Lección 03 — Ruteo determinista con reglas

Un router por palabras clave, ejecutado, sobre las tres peticiones de intención única. Dónde el router determinista acierta y dónde llega a su límite.

Lección 04 — Ruteo por decisión del modelo

La misma petición ambigua que el router determinista falló, resuelta por decisión del modelo (concepto), con la extracción de la decisión ejecutada de verdad.

Lección 05 — Construyendo pricing_agent

El tercer especialista, ejecutado por primera vez como agente completo: tres cotizaciones en el mismo turno, comparadas.

Lección 06 — El dispatcher ejecutado de punta a punta

La pieza central del módulo: las tres peticiones, ruteadas y despachadas a los tres especialistas, con el costo de cada camino medido.

Lección 07 — Eligiendo tu router

Determinista vs. modelo, comparados con números; un router híbrido que combina los dos, con sus límites reales, no idealizados.

Lección 08 — Mini-proyecto: el supervisor de Reservo

Cinco escenarios nuevos, ruteados y despachados con el router híbrido completo.

Mapa de progresión

Lección 01 (esta)  → El patrón, la analogía, la frontera con M3/M4
Lección 02         → Anatomía del supervisor: recibir, decidir, despachar, agregar
Lección 03         → Ruteo determinista, ejecutado
Lección 04         → Ruteo por decisión del modelo, concepto
Lección 05         → pricing_agent, construido y ejecutado
Lección 06         → El dispatcher completo, ejecutado (la pieza dura)
Lección 07         → Determinista vs. modelo, el router híbrido
Lección 08         → Proyecto: el supervisor completo de Reservo

Dificultad: ⭐⭐ ──────────────────▶ ⭐⭐⭐

Qué lograrás en este módulo

Al completar las 8 lecciones, podrás:

Construir un supervisor completo que recibe una petición, decide a quién delegar, despacha y agrega —las cuatro piezas de la definición formal del Módulo 1, esta vez implementadas.
Escribir un router determinista por palabras clave, y reconocer exactamente dónde llega a su límite: cobertura incompleta y confianza equivocada.
Reconocer cuándo hace falta la decisión del modelo para rutear, y extraer esa decisión de un turno de forma ejecutada, sin violar la regla de que la decisión en sí es concepto.
Construir un especialista nuevo (pricing_agent) desde cero, reusando el mismo runner sin modificarlo.
Ejecutar un dispatcher completo de tres especialistas y citar, con números reales, el costo de coordinar cada camino.
Diseñar un router híbrido que combina reglas y decisión del modelo, y explicar por qué ese híbrido no resuelve todos los casos —solo los que las reglas reconocen que no saben resolver.

El antes y después

ANTES del módulo:
→ "Enrutar" es simplemente "llamar al modelo y que decida"
→ Las reglas de palabras clave son un atajo poco serio, no un patrón real
→ Un router que funciona en las pruebas funciona siempre
→ El supervisor es solo un paso extra sin lógica propia

DESPUÉS del módulo:
→ El ruteo determinista es GRATIS (0 llamadas al modelo) y perfecto para vocabularios acotados
→ El ruteo por decisión del modelo cuesta una llamada real -- y a veces vale la pena pagarla
→ Un router determinista puede fallar CONFIADO, no solo devolver "no sé" -- una regla que matchea mal nunca activa un fallback simple
→ El supervisor tiene una anatomía de cuatro pasos: recibir, decidir, despachar, agregar

Trampas a evitar al cursar este módulo

1. "El ruteo determinista es un truco de principiante, la decisión del modelo siempre es mejor"

No. La lección 03 mide una cobertura del 100% sobre peticiones de intención clara, con costo cero. La lección 07 muestra el costo real de rutear TODO con el modelo, a distintos volúmenes diarios —el ahorro de las reglas, cuando alcanzan, no es despreciable.

2. "Si el router determinista no falla en mis pruebas, no falla nunca"

Es la trampa central de la lección 03: una regla puede matchear con total confianza y estar mal —no solo devolver None—. La lección 07 muestra en detalle por qué eso hace que un fallback ingenuo ("si es None, pregúntale al modelo") no alcance para todos los casos.

3. "Este módulo ya construye el sistema completo de Reservo"

No todavía. Este módulo se queda con una petición, un especialista elegido por vez. Las peticiones compuestas que necesitan dos especialistas a la vez son fan-out (Módulo 4); combinarlo todo en una corrida real es el Módulo 7.

4. "pricing_agent ya estaba completo desde el Módulo 1"

No. El Módulo 1 usó get_quote directamente, como una llamada suelta dentro del criterio de decisión. La lección 05 de este módulo lo construye por primera vez como agente real, con su propio runner y su propio guion.

Cómo trabajar este módulo

Ejecuta la lección 06 tú mismo. Es la pieza que sostiene todo el módulo —el dispatcher completo, con las tres peticiones ruteadas al agente correcto y su costo citado.
Presta atención a los casos donde el router determinista falla. No son casos raros armados para asustar: son el tipo exacto de ambigüedad que un vocabulario real produce todo el tiempo.
El mini-proyecto es la síntesis. La lección 08 te da escenarios nuevos con el router híbrido completo —practicarlo antes del Módulo 3 hace que el próximo patrón se sienta como una extensión natural, no como un tema nuevo.

Tiempo estimado:

Lección 01 (esta)  →  15 min lectura
Lección 02         →  20 min + correr la demo
Lección 03         →  25 min + correr la demo
Lección 04         →  25 min + correr la demo
Lección 05         →  20 min + correr la demo
Lección 06         →  35 min + correr la demo (la más densa del módulo)
Lección 07         →  25 min + correr la demo
Lección 08         →  30 min + aplicar el router completo

Total: ~3.3 horas

Evidencia de éxito

Antes de avanzar al Módulo 3 (Pipelines secuenciales), deberías poder:

✅ Explicar las cuatro piezas de un supervisor —recibir, decidir, despachar, agregar— con tus propias palabras.
✅ Escribir un router determinista por palabras clave y reconocer, con un ejemplo propio, dónde falla con confianza en vez de devolver None.
✅ Citar de memoria el resultado del dispatcher de la lección 06: cuántas llamadas al modelo costó cada una de las tres peticiones, y por qué el ruteo determinista ahorró una llamada frente al supervisor de un solo especialista del Módulo 1.
✅ Distinguir supervisor/router de pipeline y de fan-out, sin confundirlos.
✅ Diseñar un router híbrido, y explicar en qué casos concretos su fallback no alcanza.

Resumen

Este módulo construye el primer patrón de los cinco que anticipó el Módulo 1: supervisor/ router — un coordinador que recibe la petición, decide a quién delegar, despacha, y agrega.
Regla dura: la decisión de cada agente sigue siendo concepto (claude-sonnet-5); el router determinista, el runner de cada especialista, el paso de mensajes y el dispatcher completo se ejecutan de verdad con Python 3.14.
El caso son los tres especialistas de Reservo —booking_agent y policy_agent reusados sin cambios del Módulo 1, pricing_agent construido por primera vez como agente completo en la lección 05.
Frontera clara con lo que sigue: el orden SIEMPRE fijo, sin decisión de ruteo, es pipeline (M3); las sub-tareas independientes despachadas en paralelo son fan-out (M4). Este módulo se queda con una decisión, un especialista elegido por vez.

Siguiente lección: 02 — Qué hace un supervisor. Construimos la anatomía completa —recibir, decidir, despachar, agregar— con el primer ejemplo ejecutado de punta a punta.

Recursos adicionales

Anthropic — Building effective agents — El patrón de "routing" descrito ahí (clasificar una entrada y dirigirla a un flujo especializado) es, con otro vocabulario, exactamente el supervisor/router de este módulo.
Anthropic — Multi-agent research system — Un orquestador real decidiendo a qué sub-agente delegar cada parte de una tarea de investigación.
Anthropic — Tool use (function calling) overview — El protocolo que cada especialista de este módulo sigue usando, sin cambios, dentro de su propio loop.
Python 3.14 — What's New — La versión con la que se ejecuta toda la orquestación de este módulo.

← AnteriorMini-proyecto: decide single o multi Siguiente →Qué hace un supervisor