Módulo 8: Project The Reservo Multi Agent System

Introducción al Módulo 8: el capstone — el sistema completo de Reservo

Descripción

Siete módulos te trajeron hasta acá. El Módulo 1 midió, con números, cuándo coordinar varios agentes vale la pena y cuándo no. Los Módulos 2 a 6 construyeron, uno a la vez, los cinco mecanismos de coordinación: el supervisor/router que decide a quién delegar (M2), el pipeline de orden fijo (M3), el fan-out que reparte sub-tareas independientes (M4), el handoff donde un agente cede el turno a mitad de camino (M5), y el blackboard que varios agentes leen y escriben sin pasarse mensajes directos (M6). El Módulo 7 combinó los cinco sobre una sola petición real de Reservo, con el criterio de las tres preguntas para decidir cuándo combinar cuáles.

Este es el último módulo de la guía. No agrega un sexto patrón — ensambla los cinco en un sistema entregado: booking_agent, policy_agent y pricing_agent, coordinados por un supervisor, sobre un blackboard compartido, capaz de resolver una petición de Reservo con cualquier combinación de pipeline, fan-out y handoff que necesite. Y hace algo que ningún módulo anterior hizo todavía: cuenta, con números reales, cuánto cuesta coordinar cada tipo de petición — el conteo que el Módulo 1 prometió y que M7 explícitamente dejó pendiente para acá.

Al terminar este módulo vas a tener, ejecutado y citado: el sistema completo funcionando, una demo con al menos dos peticiones de forma distinta (una que dispara solo pipeline, otra que dispara solo fan-out, y una tercera que combina los tres patrones a la vez), y el costo de coordinación —llamadas al modelo, hops entre agentes, rondas— de cada una.

Conexión con el módulo

Cada pieza de este módulo es código que ya conoces, sin cambios: dispatch_parallel y run_agent_parallel (el runner base), SPECIALISTS y run_specialist (M2), run_pipeline (M3), run_tracks_parallel (M4/M7), run_with_handoff (M5), Blackboard (M6), Track (M7). Las lecciones 02 a 06 las reensamblan, una por una, confirmando que cada una sigue funcionando igual dentro del sistema completo. La lección 07 construye la única pieza genuinamente nueva de todo el módulo: coordination_cost, una función que generaliza las tres fórmulas de costo que ya mediste por separado (M3 L05, M4 L07, M5 L07) para que funcionen sobre una petición con cualquier combinación de tracks. La lección 08 —el proyecto— junta todo en un solo sistema, corre la demo completa, y cierra la guía.

Analogía: el restaurante, entregado como negocio funcionando

Las siete analogías anteriores de esta guía construyeron, una parte a la vez, un restaurante: el maître que decide (M2), la línea de montaje con su orden fijo (M3), los mozos que resuelven preguntas sueltas al mismo tiempo (M4), el mozo que llama al sommelier a mitad de un pedido (M5), la pizarra de la cocina (M6), y una noche completa donde las cinco piezas trabajaron juntas (M7).

Este módulo no agrega un rol nuevo al restaurante. Es el día en que el dueño entrega las llaves a un socio inversionista: no solo tiene que demostrar que la cocina funciona — tiene que mostrar, con el libro de cuentas en la mano, cuánto cuesta atender cada tipo de mesa. Una mesa que solo pide el menú fijo (pipeline) cuesta un número de pasos. Una mesa con dos pedidos sueltos que se pueden preparar a la vez (fan-out) cuesta otro. Y una mesa grande, con un poco de cada cosa, cuesta la suma de las dos, más la coordinación de servirlas juntas. Ese libro de cuentas —no la cocina en sí, que ya está construida— es lo único genuinamente nuevo de este último módulo.

Lo que este módulo entrega, exactamente

EL SISTEMA (lecciones 02-06, código ya conocido, reensamblado):
  - SPECIALISTS: booking_agent, policy_agent, pricing_agent (M2)
  - run_pipeline: para sub-tareas de orden fijo (M3)
  - run_tracks_parallel: para sub-tareas independientes (M4/M7)
  - run_with_handoff: para cuando un agente cede el turno a mitad de tarea (M5)
  - Blackboard: el estado compartido de la corrida (M6)

EL CONTEO (lección 07, la ÚNICA pieza nueva):
  - coordination_cost: llamadas al modelo, tool calls, hops entre agentes,
    y rondas de coordinación (secuencial vs. paralelo), para CUALQUIER
    combinación de tracks -- generaliza M3 L05, M4 L07 y M5 L07 en una
    sola función.

LA DEMO (lección 08, el proyecto):
  - Demo A: una petición que dispara SOLO pipeline (Luis)
  - Demo B: una petición que dispara SOLO fan-out (Marta)
  - Demo C: una petición compuesta que dispara los tres patrones a la vez,
    sobre el blackboard compartido (Valentina)
  - El costo de coordinación de cada una, medido y comparado

Como en toda la guía, la regla dura de ejecución no cambia: la orquestación se ejecuta de verdad con Python 3.14 (el registro de especialistas, el dispatcher, el pipeline, el fan-out, el handoff, el blackboard, el conteo de costo) 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. Sin random, sin datetime.now(), sin uuid4() — los booking_id siguen saliendo de itertools.count, como en cada módulo anterior.

Lo que este módulo NO hace

No inventa un sexto patrón de coordinación. Todo lo que ves en las lecciones 02 a 06 es supervisor, pipeline, fan-out, handoff o blackboard — los cinco de M2-M6, sin ningún mecanismo nuevo.
No repite la petición de Ana de M7. Las tres demos de este módulo —Luis, Marta y Valentina— son peticiones nuevas, elegidas a propósito para que cada una dispare una combinación distinta de patrones, y así el conteo de costo de la lección 07 tenga algo genuinamente distinto que medir en cada caso.
No construye LangGraph, CrewAI, ni el protocolo A2A. La lección 08 los nombra, al cierre de la guía, como el paso siguiente si este sistema tuviera que llegar a producción real — nunca se implementan acá. Sigue siendo, hasta la última línea de esta guía, framework-free y $0.
No mide latencia de reloj real. Como en M4 L07, "rondas" es un conteo de pasos de coordinación, nunca time.time() ni segundos reales — no hay red ni llamadas reales al modelo en ningún punto de esta guía.

Las seis lecciones, en orden

02 -- Ensamblando el supervisor y los especialistas
      (M2, sin cambios: SPECIALISTS, run_specialist, dos smoke tests que
      confirman que el registro sigue funcionando dentro del sistema).

03 -- Conectando el pipeline al sistema
      (M3, sin cambios: run_pipeline resuelve la primera demo, Luis --
      una petición que necesita SOLO orden fijo).

04 -- Conectando el fan-out al sistema
      (M4/M7, sin cambios: run_tracks_parallel resuelve la segunda demo,
      Marta -- dos sub-preguntas independientes, sin ninguna reserva).

05 -- Conectando un handoff al sistema
      (M5, sin cambios: run_with_handoff resuelve, en aislado, la pieza
      de handoff que la Demo C va a necesitar en la lección 08).

06 -- Un blackboard para todo el sistema
      (M6, sin cambios: booking_agent escribe cuando confirma una reserva
      real; pricing_agent y un handoff de solo-cotización NO escriben --
      la misma regla de M6, confirmada sobre tres socios nuevos).

07 -- Midiendo el costo de coordinación del sistema completo
      (la ÚNICA pieza nueva del módulo: coordination_cost, generalizando
      las fórmulas de M3, M4 y M5 en una función que funciona sobre
      cualquier PLAN de tracks, probada contra las Demos A y B).

La lección 08 es el proyecto final: ensambla las seis piezas en un solo sistema, agrega una tercera demo (Valentina, los tres patrones combinados) y presenta el conteo comparado de las tres. Cierra con el resumen de toda la guía y a dónde seguir.

Errores comunes

Buscar un patrón de coordinación nuevo en este módulo. No hay ninguno. Si una función te resulta desconocida en las lecciones 02 a 06, es literalmente la misma que ya viste en M2-M6 — compáralas si tienes dudas, línea por línea, deberían ser idénticas.
Pensar que coordination_cost (lección 07) reemplaza las fórmulas de M3/M4/M5. No las reemplaza — las generaliza. Cuando coordination_cost recibe un PLAN con un solo track de pipeline, sus números no son exactamente iguales a los de M3 L05 (la lección 07 explica por qué, con la comparación hecha, no solo afirmada).
Ejecutar las lecciones de este módulo en un orden distinto y esperar los mismos booking_id. Como en cada módulo anterior, el booking_id depende del orden real de ejecución dentro del proceso — Luis reserva antes que Valentina en la demo completa de la lección 08 porque el guion los corre en ese orden, no por ninguna otra razón.
Confundir "el sistema está completo" con "el sistema está listo para producción". Este capstone demuestra la orquestación de punta a punta con decisiones concepto — la lección 08 nombra, al cierre, todo lo que falta para producción real (memoria persistente, presupuesto de contexto, seguridad, evaluación) sin construir ninguna de esas piezas acá.

Ejercicios

Ejercicio 1: Predice qué patrón dispara cada petición, antes de leer las lecciones (Fácil)

Sin adelantarte a las lecciones 03, 04 y 05, lee estas tres peticiones y decide, aplicando el criterio de las tres preguntas de M7 L02, qué patrón (pipeline, fan-out u handoff) le corresponde a cada una: (a) "Reserva el Focus basic 2h para la llamada de las 3, validando la política antes de confirmar." (b) "¿Cuánto cuesta el Boardroom pro 4h? Y aparte, ¿cuánto cuesta el Studio pro 4h?" (c) "Cotiza el Focus pro 1h para una llamada rápida -- ah, y de paso, ¿qué pasa si nadie se presenta?"

Ver solución

(a) Pipeline. La política tiene que validarse ANTES de confirmar — un orden fijo, conocido de antemano. Es exactamente la forma de la Demo A de este módulo (lección 03).

(b) Fan-out. Dos preguntas de precio, ninguna depende de la otra — se pueden resolver a la vez. Es la forma de la primera mitad de la Demo B de este módulo (lección 04).

(c) Handoff. La tarea empieza siendo una cotización de booking_agent y, a mitad de camino, aparece una pregunta que vive en el dominio de policy_agent — nadie lo anticipó desde el principio del plan. Es la forma de la pieza que construye la lección 05.

Ejercicio 2: ¿Por qué la lección 07 necesita ejecutar las Demos A y B, y no solo describir la fórmula? (Medio)

Sin leer todavía la lección 07, explica por qué —siguiendo la regla dura de ejecución de esta guía— no alcanzaría con escribir la fórmula de coordination_cost en prosa y afirmar cuánto daría para la Demo A y la Demo B.

Ver solución

Porque la regla dura de esta guía exige que la ORQUESTACIÓN —y el conteo de su costo es parte de la orquestación, no de la decisión de cada agente— se ejecute de verdad y se cite su salida real, no una estimación de prosa. Una fórmula descrita en texto puede tener un error de conteo (un +1 de más o de menos en algún término) que solo aparece al correr el código sobre datos reales — es exactamente el mismo principio que ya viste en M1 L05, M3 L05, M4 L07 y M5 L07: el número sale de count_model_calls/count_tool_calls corriendo sobre un history real, nunca de una cuenta mental. La lección 07 ejecuta coordination_cost sobre los resultados reales de correr la Demo A y la Demo B, y solo después de ver la salida real explica de dónde sale cada número.

Ejercicio 3: ¿Cuántos tracks esperarías que tenga la Demo C, antes de leer la lección 08? (Difícil)

El resumen de este módulo dice que la Demo C "combina los tres patrones a la vez". Sin leer la lección 08 todavía, ¿cuántos Track esperarías que tenga su PLAN, como mínimo? Justifica tu respuesta usando la definición de Track de M7 (lección 02 de ese módulo).

Ver solución

Al menos 3. Cada Track de M7 representa una sub-tarea de la petición con un patrón asignado — y si la Demo C necesita "los tres patrones a la vez" (pipeline, fan-out y handoff), hace falta, como mínimo, un track por cada patrón distinto: uno resuelto en pipeline, uno resuelto en fan-out, y uno resuelto con un handoff a mitad de camino. Podría tener más de tres si, por ejemplo, hubiera dos sub-preguntas de fan-out en vez de una — pero no podría tener menos de tres y seguir cumpliendo la promesa de "los tres patrones a la vez", porque cada patrón necesita, como mínimo, su propio track para aparecer en el PLAN.

Resumen y siguiente paso

Este es el último módulo de la guía: ensambla, sin inventar ningún patrón nuevo, los cinco mecanismos de coordinación de M2-M6 en un sistema entregado.
Lo único genuinamente nuevo es el conteo de costo de coordinación (lección 07) — el número que el Módulo 1 prometió medir y que este módulo finalmente entrega, generalizado a cualquier combinación de patrones.
El proyecto final (lección 08) corre tres demos de forma distinta —pipeline puro, fan-out puro, y los tres patrones combinados— y mide el costo de coordinación de cada una.

Siguiente lección: 02 — Ensamblando el supervisor y los especialistas. Empezamos por la base: confirmar que SPECIALISTS y run_specialist, sin ningún cambio, siguen siendo el punto de entrada de todo el sistema.

Recursos adicionales

Anthropic — Building effective agents — El principio de componer mecanismos simples ya probados en vez de inventar uno nuevo, la idea que sostiene todo este módulo de cierre.
Anthropic — Multi-agent research system — Un sistema real de Anthropic donde varios mecanismos de coordinación conviven sobre la misma tarea — la forma general que este capstone entrega a mano, sin framework.
Anthropic — Messages API reference — La forma exacta de tool_use/tool_result/stop_reason que cada agente del sistema completo sigue respetando, sin cambios, en los cinco patrones a la vez.
Python — concurrent.futures — El módulo detrás de run_tracks_parallel, reusado sin cambios en todo este módulo para correr cualquier combinación de tracks a la vez.

← AnteriorMini-proyecto: tres peticiones compuestas para Reservo Siguiente →Ensamblando el supervisor y los especialistas