Módulo 7: Orchestrating The Full Reservo System

Introducción al Módulo 7: combinar los patrones sobre una petición real

Descripción

Los cinco módulos anteriores construyeron cinco piezas, cada una por separado, cada una sobre su propia petición de ejemplo: un supervisor que decide a quién delegar (Módulo 2), un pipeline de etapas fijas donde el resultado de una alimenta a la siguiente (Módulo 3), un fan-out que reparte sub-tareas independientes y las corre a la vez (Módulo 4), un handoff donde un agente ya en curso cede el turno a mitad de camino (Módulo 5), y un blackboard que varios agentes leen y escriben sin pasarse mensajes directos (Módulo 6).

Este módulo no agrega un sexto patrón. Toma los cinco que ya construiste, exactamente como están —mismas funciones, mismas estructuras, sin un solo cambio de firma— y los hace trabajar juntos sobre una sola petición de Reservo lo bastante real como para necesitar más de uno a la vez. La pregunta que responde este módulo no es "¿cómo construyo un patrón nuevo?" — es "¿cuándo combino cuáles, y cómo decido qué parte de una petición le toca a cada uno?".

Como en toda esta guía, la regla dura de ejecución no cambia: la orquestación —el plan del supervisor traducido a tracks, el pipeline, el fan-out, el handoff, las lecturas y escrituras del blackboard— se ejecuta de verdad con Python 3.14, y su salida real se cita en cada lección. La decisión de cada agente sobre qué responder sigue siendo concepto, con guiones realistas de claude-sonnet-5 — nunca una llamada real a la API.

Conexión con el módulo

Cada lección de este módulo reusa código de un módulo anterior sin modificarlo: run_pipeline (03) sigue siendo la misma función de tres líneas que ya conoces; run_agent_with_handoff (05) sigue deteniéndose exactamente igual cuando reconoce handoff_to_specialist; Blackboard.write (06) sigue sin recibir ningún destinatario. Lo único genuinamente nuevo en todo el módulo es una capa delgada de composición —una forma de anotar qué patrón resuelve cada parte de una petición, y un mecanismo para correr esas partes juntas— que construyes en las lecciones 02 y 04. El Módulo 8 retoma esta misma corrida compuesta como el capstone de la guía: un sistema completo, entregado, con una demo de al menos dos peticiones de forma distinta.

Analogía: el turno más ocupado del restaurante, con los cinco roles trabajando a la vez

No hace falta una analogía nueva para este módulo — las cinco que ya construiste, juntas en una sola escena, alcanzan y sobran.

Es la noche más ocupada del restaurante de la lección 01 del Módulo 1. El maître (supervisor) recibe a un grupo grande y, mirando lo que piden, decide qué necesita cada parte del pedido: un plato que exige pasar por la línea de montaje completa —cortar, cocinar, emplatar, con una verificación obligatoria de alergias antes de servir— (pipeline); dos preguntas sueltas del cliente que dos mozos distintos pueden responder al mismo tiempo, sin esperarse el uno al otro (fan-out); un mozo que, a mitad de tomar un pedido, se da cuenta de que una pregunta sobre el vino no es lo suyo y llama al sommelier ahí mismo, sin volver a preguntarle al maître (handoff); y, por encima de todo eso, la pizarra de la cocina, donde cualquiera de ellos anota o consulta el estado de la mesa —quién pidió qué, si ya se confirmó— sin tener que interrumpir a nadie para enterarse (blackboard).

Ningún mozo, ningún cocinero, ningún sommelier cambia de trabajo esta noche. Lo único distinto es que, por primera vez, todos están en el mismo turno, resolviendo partes distintas del mismo pedido grande, al mismo tiempo.

La petición que atraviesa todo el módulo

Cada lección de los Módulos 2 a 6 usó su propia petición de ejemplo, aislada, para mostrar un patrón a la vez. Este módulo usa una sola petición, compuesta, desde la lección 02 hasta la 07 —cada lección le agrega una pieza de la solución, sin repetir lo que la anterior ya resolvió—:

Ana (equipo de diseño): cotiza y reserva Focus pro 3h para el lanzamiento, validando la
política de cancelación antes de confirmar. Aparte, compara Studio y Boardroom pro 3h por
si necesitamos más espacio, y de paso cotiza el Boardroom pro 2h para la reunión de cierre
-- dime también qué pasa si alguien del equipo no llega a esa reunión.

Léela con calma — no hace falta ejecutar nada todavía, la lección 02 se encarga de eso. Fíjate en que contiene, sin que lo hayas buscado a propósito, tres formas de trabajo completamente distintas:

"cotiza y reserva Focus pro 3h... validando la política antes de confirmar" — un orden fijo, obligatorio, donde el paso 2 (la política) tiene que resolverse antes que el paso 3 (la confirmación). Eso es exactamente lo que un pipeline (Módulo 3) resuelve.
"compara Studio y Boardroom pro 3h" — una pregunta que no depende de nada más en la petición: se puede responder sin esperar a que la reserva de Focus esté confirmada. Eso es lo que un fan-out (Módulo 4) resuelve.
"cotiza el Boardroom pro 2h... dime qué pasa si alguien no llega" — una sub-tarea que empieza en el dominio de booking_agent (cotizar) pero, a mitad de camino, se topa con una pregunta que vive en el dominio de policy_agent. Eso es lo que un handoff (Módulo 5) resuelve.

Y por encima de las tres, un blackboard (Módulo 6) compartido guarda quién es el socio y cuál fue la reserva real que terminó confirmándose — el único hecho de esta petición que otra parte del sistema, en una corrida más grande, podría necesitar después.

Lo que este módulo NO hace

Vale la pena ser preciso sobre el límite, porque es fácil confundir "combinar patrones" con "construir algo nuevo":

No inventa un sexto patrón. Cada pieza de la corrida compuesta es, sin excepción, supervisor, pipeline, fan-out, handoff o blackboard — los cinco que ya construiste. Si en algún momento de este módulo ves una función que no reconoces del todo, es casi seguro una generalización mínima de una que ya existe (la lección 04 construye exactamente una de esas, explicada con cuidado), nunca un mecanismo de coordinación nuevo.
No mide el costo de coordinación con números. Los Módulos 2, 3, 4 y 5 ya midieron, cada uno, el costo de su propio patrón (llamadas al modelo, rondas, bytes de contexto). Este módulo no repite esa cuenta — se concentra en el criterio de cuándo combinar cuáles, no en cuantificar cuánto cuesta hacerlo.
No entrega el sistema completo como proyecto final. Eso es el Módulo 8: el capstone que construye el sistema multi-agente completo de Reservo —supervisor + los tres especialistas, sobre un blackboard compartido, con una demo de al menos dos peticiones de forma distinta y el conteo de costo de cada una—. Este módulo es la práctica que hace posible ese capstone; el capstone en sí vive en el Módulo 8.

Las seis lecciones, en orden

02 -- Anatomía de una petición compuesta: qué patrón resuelve cada parte
      (el criterio de decisión, aplicado a la petición de arriba, SIN ejecutar
      todavía ningún agente -- solo la descomposición).

03 -- El supervisor decide, el pipeline valida antes de reservar
      (M2 + M3: la primera sub-tarea, resuelta con run_pipeline sin cambios).

04 -- Las preguntas independientes corren en fan-out mientras el pipeline resuelve
      (M2 + M3 + M4: se agrega la segunda sub-tarea, y las dos corren A LA VEZ con
      un ThreadPoolExecutor generalizado a "cualquier callable", no solo agentes).

05 -- Un agente hace handoff a mitad de una rama del fan-out
      (M5 se agrega: la tercera sub-tarea empieza en booking_agent y cede el turno
      a policy_agent, SIN que el fan-out que la contiene se entere de nada distinto).

06 -- Un blackboard, compartido por los tres patrones a la vez
      (M6 se agrega: el supervisor escribe ANTES de abrir los tracks paralelos,
      booking_agent escribe DESPUÉS de que el pool se cierra -- nunca durante).

07 -- La corrida completa, ejecutada de punta a punta
      (las cinco piezas juntas, de una sola vez: la petición completa resuelta,
      con la respuesta final compuesta y el resumen de qué patrón resolvió qué).

La lección 08 es el mini-proyecto: aplicas exactamente este mismo criterio a tres peticiones de Reservo nuevas, con formas distintas entre sí —una que necesita los tres patrones, una que necesita solo dos, y una que necesita solo uno—, para confirmar que el criterio de la lección 02 generaliza más allá de la petición de Ana.

Errores comunes

Buscar un patrón nuevo en este módulo. Si una función te resulta desconocida, revisa primero si es una generalización mínima de una que ya conoces (la lección 04 tiene exactamente una: run_tracks_parallel) antes de asumir que este módulo introduce un mecanismo de coordinación distinto a los cinco de M2-M6.
Pensar que "petición compuesta" significa "usa los cinco patrones siempre". La petición de Ana usa tres (pipeline, fan-out, handoff) más el blackboard como sustrato compartido — no hay ningún router determinista puro ni ninguna decisión de supervisor entre varios especialistas completos, como sí había en el Módulo 2 aislado. El mini-proyecto de la lección 08 incluye a propósito un escenario que necesita solo dos patrones y otro que necesita solo uno.
Confundir "el supervisor decide el plan" con "el supervisor ejecuta el plan". El supervisor (concepto) decide QUÉ patrón le corresponde a cada parte de la petición — la EJECUCIÓN de cada parte la hace el mecanismo real (run_pipeline, run_tracks_parallel, run_with_handoff), no el supervisor mismo.
Esperar que este módulo mida costo de coordinación con números, como los Módulos 2-5. No lo hace — ese conteo específico de esta corrida compuesta es tarea del Módulo 8, sobre el sistema completo entregado como capstone.

Ejercicios

Ejercicio 1: Identifica los tres patrones en la petición de Ana, sin ejecutar nada (Fácil)

Vuelve a leer la petición de Ana de esta lección, línea por línea, y para cada una de las tres partes que identifica esta lección (la reserva de Focus, la comparación de salas, el Boardroom para el cierre), escribe en una frase por qué esa parte específica encaja con el patrón que se le asignó y no con otro de los cuatro restantes.

Ver solución

"Cotiza y reserva Focus pro 3h... validando la política antes de confirmar" → pipeline, no fan-out. No es fan-out porque el orden importa: la política tiene que validarse ANTES de confirmar, no al mismo tiempo — si corrieran en paralelo, la reserva podría confirmarse antes de saber si había algún impedimento. No es handoff porque el flujo completo (cotizar, validar, confirmar) se sabe de antemano, no aparece a mitad de una tarea que empezó siendo otra cosa.

"Compara Studio y Boardroom pro 3h" → fan-out, no pipeline. No es pipeline porque no depende de ningún otro paso — no necesita el resultado de la reserva de Focus ni de nada más en la petición. No es handoff porque no empieza en el dominio de un agente para después descubrir que necesita otro — nace, desde el principio, como una pregunta de pricing_agent.

"Cotiza el Boardroom pro 2h... qué pasa si no llega" → handoff, no fan-out plano. Empieza siendo una tarea de booking_agent (cotizar) y, a mitad de camino, se topa con una pregunta que vive en policy_agent (no-presentación) — el propio agente que ya está trabajando reconoce el límite de su expertise y cede el turno, sin que nadie lo haya anticipado desde el principio del plan.

Ejercicio 2: Construye tu propia petición compuesta de dos patrones (Medio)

Escribe, en una sola frase de Reservo, una petición que combine SOLO dos de los cinco patrones —tú eliges cuáles— y explica, sin ejecutar código, qué parte de tu frase le corresponde a cada uno.

Ver solución

No hay una única "solución de código" para este ejercicio — es un ejercicio de diseño. Un ejemplo válido: "Marta: reserva el Studio pro 2h para el taller, validando la política de cancelación antes de confirmar. Aparte, ¿qué política aplica para grupos de más de diez personas?" — la primera parte es un pipeline (cotizar → validar → confirmar, orden fijo); la segunda es fan-out plano (una pregunta de política que nace, desde el principio, en policy_agent, sin depender de la reserva ni requerir ningún handoff). No hay handoff en esta frase porque ningún agente cede el turno a mitad de una tarea — el supervisor ya sabe, desde el principio, que la segunda pregunta es de policy_agent.

Ejercicio 3: ¿Por qué el blackboard no es "un sexto patrón que se agrega al final"? (Difícil)

Sin ejecutar código, explica por qué el Blackboard de este módulo no es una sub-tarea más de la petición de Ana —como sí lo son el pipeline, el fan-out y el handoff— sino algo de una naturaleza distinta que atraviesa a las tres.

Ver solución

El pipeline, el fan-out y el handoff son, cada uno, una forma de resolver una parte concreta de la petición de Ana —tienen una entrada (una sub-tarea) y una salida (una respuesta)—. El Blackboard, en cambio, no resuelve ninguna parte de la petición por sí solo: es el lugar donde los hechos que esas tres partes producen (o necesitan) quedan disponibles para el resto de la corrida, sin que nadie tenga que pasárselos directamente. Por eso el Módulo 6 lo llamó "estado compartido" y no "un patrón de resolución" — no compite con el pipeline, el fan-out o el handoff por resolver la misma sub-tarea; vive en una capa distinta, disponible para cualquiera de los tres al mismo tiempo. La lección 06 de este módulo lo confirma ejecutando: el supervisor escribe en el Blackboard ANTES de que exista ningún track, y booking_agent escribe DESPUÉS de que los tres terminaron — el Blackboard no es una sub-tarea con su propio turno, es el sustrato que las rodea.

Resumen y siguiente paso

Este módulo combina, sin inventar ninguno nuevo, los cinco patrones de los Módulos 2-6: supervisor (M2), pipeline (M3), fan-out (M4), handoff (M5) y blackboard (M6).
Una sola petición compuesta de Ana atraviesa las lecciones 02 a 07 — cada lección le agrega una pieza, sin repetir la anterior, hasta la corrida completa de la lección 07.
La pregunta central del módulo no es "¿cómo construyo X?" (eso ya lo sabes) — es "¿cuándo combino cuáles, y qué parte de una petición le toca a cada patrón?".
El capstone que entrega el sistema completo, con su propia demo y su propio conteo de costo, es el Módulo 8 — este módulo es la práctica que lo hace posible.

Siguiente lección: 02 — Anatomía de una petición compuesta. Descomponemos, sin ejecutar todavía ningún agente, la petición de Ana en las partes que cada patrón va a resolver.

Recursos adicionales

Anthropic — Building effective agents — El principio de componer mecanismos simples en vez de diseñar uno nuevo cada vez que la tarea crece — la idea central de todo este módulo.
Anthropic — Multi-agent research system — Un sistema real donde varios mecanismos de coordinación —no uno solo— conviven sobre la misma tarea, exactamente el tipo de composición que este módulo construye con Reservo.
Python — concurrent.futures — El módulo detrás de ThreadPoolExecutor, reusado en las lecciones 04 a 07 para correr sub-tareas de forma distinta (una llamada suelta, un pipeline, una cadena de handoff) a la vez.
Anthropic — Agent SDK overview — Cómo se ve, en código de producción, un sistema que combina varios de estos patrones sobre una misma tarea — el destino final del Módulo 8 de esta guía.

← AnteriorMini-proyecto: el Blackboard de Reservo Siguiente →Anatomía de una petición compuesta