Módulo 3: Pipelines secuenciales

Descripción

El Módulo 2 construyó un supervisor que decide: lee cada petición y elige, entre tres especialistas, cuál debe resolverla. Ese "decidir" tiene un costo —una llamada de ruteo, un punto donde algo puede salir mal— y ese costo se justifica cuando la petición puede pedir cosas distintas cada vez. Este módulo construye el patrón contrario: qué hacer cuando la tarea siempre necesita los mismos pasos, en el mismo orden, sin importar qué dijo exactamente el socio. Ahí no hace falta decidir nada — hace falta encadenar.

El caso que abre el módulo es el mismo que la lección 06 del Módulo 1 ya señaló, sin construirlo: reservar una sala de Reservo no es solo cotizar y reservar —el Módulo 1, lección 05, ya midió ese camino de dos pasos—. El proceso real de Reservo agrega un tercer paso obligatorio en el medio: antes de confirmar cualquier reserva, hay que validar la política de cancelación con el socio. Ese paso siempre va ahí, entre cotizar y confirmar, nunca antes, nunca después, nunca opcional. Vas a construir el runner que encadena tres agentes —booking_agent, policy_agent, booking_agent otra vez— pasando el dato de una etapa a la siguiente, ejecutado de punta a punta, y vas a medir, con números reales, cuánto ahorra ese orden fijo frente a un supervisor que tuviera que decidir en cada uno de los tres pasos.

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

Se mantiene la misma línea de los Módulos 1 y 2: la decisión de cada agente —qué tool llamar, qué responder— no se ejecuta. Sigue siendo un guion escrito a mano, rotulado como concepto (claude-sonnet-5). Lo que sí se ejecuta, de verdad, con Python 3.14 y su librería estándar, es la orquestación completa del pipeline: el runner de cada especialista (reusado sin cambios de agent-fundamentals y de este mismo guía, Módulo 2), la construcción de la tarea de cada etapa a partir de lo que dejaron las etapas anteriores, la extracción del dato real que la siguiente etapa necesita, y el conteo del costo de coordinación de todo el pipeline. La novedad de este módulo, a diferencia del Módulo 2, es que ninguna de esas piezas ejecutadas incluye una decisión de a quién delegar — el orden ya está fijo antes de que llegue ninguna petición.

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  (completo)
│   → Ruteo determinista vs. ruteo por decisión del modelo
├── Módulo 3: Pipelines secuenciales  ← ESTÁS AQUÍ
│   → El segundo patrón: orden fijo, sin ninguna decisión de ruteo
├── 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 qué es un supervisor, ni cómo funciona el ruteo determinista o por decisión del modelo —se asumen dominados—. Lo nuevo acá es un patrón que no tiene Paso 2 (decidir): la secuencia de especialistas está fija desde el diseño del sistema, no desde una llamada al modelo.

Analogía: la receta, no la recepción

El Módulo 2 usó la recepción de un edificio: alguien —un cartel o una persona— tenía que leer cada visitante y decidir a qué piso mandarlo. Este módulo usa una analogía distinta: una receta de cocina. Para hacer un pastel, siempre picas, mezclas, horneas — en ese orden, sin excepción, sin importar qué pastel específico estés horneando. Nadie "decide" picar antes que mezclar cada vez que cocina; el orden está fijo en la receta misma, escrito una sola vez, antes de que exista ningún pastel concreto.

La diferencia con la recepción es exactamente la diferencia entre supervisor y pipeline: la recepción lee cada visitante para decidir su piso —el visitante podría, en teoría, necesitar cualquiera de los tres—; la receta nunca lee nada para decidir el próximo paso —siempre es el mismo, para cualquier pastel que se hornee con ella—. Reservar una sala con Reservo, cuando el proceso exige validar la política de cancelación antes de confirmar, es una receta: cotizar, validar, confirmar, siempre en ese orden, para cualquier socio y cualquier sala.

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

El Módulo 2 dejó tres especialistas terminados y probados: booking_agent (cotizar, reservar, cancelar), policy_agent (search_docs, el stub de política), y pricing_agent (comparar precios). Este módulo no agrega ningún especialista nuevo — reusa exactamente los mismos tres, sin tocar una línea de sus tools ni de su runner. Lo que agrega es una forma distinta de encadenarlos:

Etapa 1: cotizar                          -> booking_agent
Etapa 2: validar la política de cancelación -> policy_agent
Etapa 3: confirmar la reserva              -> booking_agent (de nuevo)

Fíjate en algo importante desde ya: booking_agent aparece dos veces en el pipeline —cotiza en la etapa 1 y confirma en la etapa 3—, con policy_agent en el medio. En el Módulo 2, SPECIALISTS identificaba a cada especialista por su nombre —un diccionario, SPECIALISTS["booking_agent"]—, porque el supervisor solo necesitaba saber "a quién" delegar. Acá eso no alcanza: lo que identifica cada etapa no es solo el especialista que la resuelve, es el rol que cumple en la secuencia — la lección 02 formaliza exactamente esa diferencia.

El dato viaja de etapa en etapa: el precio que cotiza la etapa 1 tiene que llegar, sin volver a calcularse, a la etapa 3, que reserva exactamente esa combinación de sala/tier/horas. La política que valida la etapa 2 tiene que confirmar, antes de que la etapa 3 corra, que no hay ningún impedimento para reservar. Esa transferencia de datos —la salida de una etapa convertida en la entrada de la siguiente— es el mecanismo central que este módulo construye y ejecuta, empezando por la lección 03.

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

Con el supervisor del Módulo 2 fresco, la distinción de fondo queda concreta:

Un supervisor decide. Cada vez que llega una petición, alguien —una función de reglas o el modelo— la lee y elige a quién delegar. La decisión puede cambiar de una petición a la siguiente: "cotiza y reserva" va a booking_agent; "¿cuál es la política?" va a policy_agent. El Módulo 2 entero mide el costo de esa decisión y cuándo se justifica.
Un pipeline no decide nada. El orden de las etapas está fijo en el diseño del sistema, escrito una sola vez, antes de que exista ninguna petición concreta. Toda reserva que pasa por el pipeline de este módulo cotiza, valida y confirma, en ese orden exacto — nunca al revés, nunca saltándose un paso.

Y hacia adelante, una distinción que este módulo deja pendiente a propósito:

Cuando los pasos NO dependen entre sí y pueden correr al mismo tiempo —por ejemplo, si validar la política no necesitara nada de la cotización, las dos etapas podrían despacharse juntas, en paralelo, en vez de una después de la otra— eso es fan-out, y lo construye el Módulo 4. La lección 07 de este módulo vuelve sobre esta pregunta exacta, aplicada al propio pipeline de Reservo, como el puente natural hacia ese módulo.

Con esto, los tres primeros patrones de los cinco que anticipó el Módulo 1 quedan distinguibles sin confundirlos: supervisor decide quién trabaja (M2); pipeline fija el orden, sin decidir nada (M3, este módulo); fan-out reparte el trabajo simultáneo entre etapas que ya sabes que son independientes (M4).

Prerequisitos

Conocimiento requerido:

✅ Módulo 1 completo de esta guía: la definición de sistema multi-agente, el costo de coordinar medido, y el mapa de los cinco patrones.
✅ Módulo 2 completo de esta guía: SPECIALISTS, run_specialist, y los tres especialistas de Reservo —booking_agent, policy_agent, pricing_agent— terminados y probados.
✅ 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 pipeline, la analogía de la receta, y la frontera con supervisor (M2) y fan-out (M4).

Lección 02 — La anatomía de una etapa

PipelineStage, PIPELINE_STAGES, y por qué una etapa se identifica por su rol —no solo por el especialista que la resuelve—. Un primer paso ejecutado, con el payload armado a mano.

Lección 03 — Encadenando el dato entre etapas

El mecanismo central: build_stage_task y extract_payload, generalizados en run_pipeline. Un pipeline pequeño de dos etapas, ejecutado, con el dato viajando de una a la otra sin volver a preguntarle nada al socio.

Lección 04 — El pipeline de Reservo, ejecutado de punta a punta

La pieza central del módulo: las tres etapas completas —cotizar, validar, confirmar— corriendo con run_pipeline, con el historial completo de cada etapa impreso y el payload final citado.

Lección 05 — Midiendo el costo de coordinación de un pipeline

La comparación que el módulo prometió desde la lección 01: la MISMA tarea de tres etapas, resuelta por el pipeline de este módulo y por un supervisor que tuviera que decidir en cada paso — con las llamadas y los hops de cada camino contados y citados.

Lección 06 — Cuándo una etapa falla

La fragilidad propia de un pipeline: sin ninguna decisión en el medio, ¿qué pasa cuando una etapa devuelve un resultado que no alcanza para seguir? Una guarda que detiene el pipeline, ejecutada, antes de confirmar sobre datos sin validar.

Lección 07 — Eligiendo pipeline o supervisor

El criterio completo, con una pregunta final que ya no puedes evitar: ¿de verdad todas las etapas de este pipeline dependen entre sí? El puente ejecutado hacia el Módulo 4.

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

Tres escenarios nuevos —dos que completan el pipeline entero, uno que activa la guarda de la lección 06— corridos de punta a punta.

Mapa de progresión

Lección 01 (esta)  → El patrón, la analogía, la frontera con M2/M4
Lección 02         → Anatomía de una etapa: PipelineStage, PIPELINE_STAGES
Lección 03         → El mecanismo de encadenar: build_stage_task, extract_payload
Lección 04         → El pipeline completo, ejecutado (la pieza dura)
Lección 05         → Costo de coordinación medido, comparado contra M2
Lección 06         → Cuándo una etapa falla, y cómo detener el pipeline a tiempo
Lección 07         → Pipeline vs. supervisor, puente hacia fan-out (M4)
Lección 08         → Proyecto: el pipeline completo de Reservo

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

Qué lograrás en este módulo

Al completar las 8 lecciones, podrás:

Distinguir con precisión un pipeline de un supervisor: el pipeline nunca decide a quién delegar — el orden ya está fijo antes de la primera petición.
Construir PipelineStage y PIPELINE_STAGES, identificando cada etapa por su rol, no solo por el especialista que la resuelve.
Encadenar N agentes con run_pipeline, pasando el dato real —no el texto libre del modelo— de una etapa a la siguiente.
Ejecutar el pipeline completo de Reservo —cotizar, validar, confirmar— de punta a punta, y citar su historial completo.
Medir el costo de coordinación de un pipeline frente a un supervisor sobre la MISMA tarea, con números reales, no estimados.
Reconocer cuándo una etapa falla sin lanzar una excepción —un resultado que no alcanza para seguir— y detener el pipeline antes de actuar sobre datos sin validar.
Reconocer los límites del patrón: cuándo el orden fijo es una dependencia real de datos, y cuándo es apenas una decisión de proceso que podría, en realidad, correr en paralelo (M4).

El antes y después

ANTES del módulo:
→ "Encadenar agentes" es simplemente "llamar a uno después del otro"
→ Un pipeline y un supervisor que siempre delega igual son lo mismo
→ El dato entre etapas se pasa "como sea" -- un string armado a mano alcanza
→ Un pipeline nunca puede fallar a mitad de camino, porque no decide nada

DESPUÉS del módulo:
→ Un pipeline es MÁS BARATO que un supervisor para la MISMA tarea de N etapas -- ahorra
  exactamente una llamada de ruteo por etapa, porque nunca decide
→ Pipeline y supervisor-que-siempre-delega-igual se DISTINGUEN por diseño, no por resultado:
  uno tiene una decisión de por medio (aunque termine siempre igual), el otro no tiene ninguna
→ El dato entre etapas se ancla en el resultado REAL de una tool -- nunca en lo que el texto
  libre del modelo dice haber hecho
→ Un pipeline SÍ puede fallar a mitad de camino -- no por una decisión que salió mal, sino por
  una etapa que no encuentra lo que necesita para que la siguiente continúe con seguridad

Trampas a evitar al cursar este módulo

1. "Un pipeline es solo un supervisor que siempre delega en el mismo orden"

No — la lección 07 lo desarrolla con cuidado: la diferencia no es el resultado final (a veces coinciden), es que un supervisor evalúa una decisión en cada paso, aunque termine siempre igual; un pipeline nunca evalúa nada — el orden está en el código, no en ninguna llamada.

2. "Menos decisiones significa que un pipeline nunca puede salir mal"

Al revés: la lección 06 mide exactamente el riesgo contrario. Sin ninguna decisión en el medio, un pipeline no tiene ningún punto natural donde notar que algo no alcanza para seguir — hay que construirlo a propósito, con una guarda explícita.

3. "Todas las etapas de un pipeline dependen genuinamente entre sí"

No siempre. La lección 07 examina el propio pipeline de este módulo y confirma, ejecutando el código, que dos de las tres etapas no necesitan el resultado de la otra — un hallazgo que motiva directamente el Módulo 4.

4. "El payload que viaja entre etapas puede ser el texto libre que dice el modelo"

No — la lección 03 construye el mecanismo con una regla dura: el payload se ancla en el resultado real de la tool (ast.literal_eval sobre el tool_result), nunca en la frase que el modelo redactó, porque esa frase es concepto, no un dato confiable para que la siguiente etapa actúe.

Cómo trabajar este módulo

Ejecuta la lección 04 tú mismo. Es la pieza central del módulo: las tres etapas completas, con el dato viajando de una a otra y el historial de cada especialista impreso.
Presta atención a la lección 06. No es un caso de borde decorativo — es la propiedad más importante que distingue "encadenar" de "confiar a ciegas": un pipeline necesita guardas propias, porque no tiene el "no sé" honesto que sí tenía el router del Módulo 2.
La lección 07 cierra el criterio. Practicarla antes del Módulo 4 hace que fan-out se sienta como la continuación natural de una pregunta que ya te hiciste, 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         →  30 min + correr la demo (la más densa del módulo)
Lección 05         →  25 min + correr la demo
Lección 06         →  25 min + correr la demo
Lección 07         →  25 min + correr la demo
Lección 08         →  30 min + aplicar el pipeline completo

Total: ~3.3 horas

Evidencia de éxito

Antes de avanzar al Módulo 4 (Fan-out paralelo y agregación), deberías poder:

✅ Explicar, con tus propias palabras, por qué un pipeline no tiene Paso 2 (decidir) —a diferencia del supervisor del Módulo 2.
✅ Construir PipelineStage/PIPELINE_STAGES y run_pipeline, encadenando al menos tres agentes con el dato real viajando entre ellos.
✅ Citar de memoria el resultado de la lección 05: cuántas llamadas al modelo y cuántos hops ahorra el pipeline de este módulo frente a un supervisor que decidiera en cada una de las tres etapas.
✅ Reconocer cuándo una etapa "falló" sin lanzar ninguna excepción, y por qué eso exige una guarda explícita que un pipeline no tiene gratis.
✅ Identificar, en un pipeline concreto, qué etapas dependen genuinamente de la anterior y cuáles podrían, en realidad, correr en paralelo.

Resumen

Este módulo construye el segundo patrón de los cinco que anticipó el Módulo 1: pipeline secuencial — la salida de una etapa es la entrada de la siguiente, en un orden fijo, sin ninguna decisión de ruteo en el medio.
Regla dura: la decisión de cada agente sigue siendo concepto (claude-sonnet-5); el encadenamiento de etapas, el traspaso de datos entre ellas y el conteo del costo de coordinación se ejecutan de verdad con Python 3.14.
El caso reusa, sin cambios, los tres especialistas del Módulo 2 —booking_agent (dos veces), policy_agent— encadenados en el proceso real de reserva de Reservo: cotizar, validar la política de cancelación, confirmar.
Frontera clara con lo que ya viste y con lo que sigue: el supervisor (M2) decide quién trabaja; el pipeline (este módulo) fija el orden sin decidir nada; el fan-out (M4) reparte trabajo simultáneo entre etapas genuinamente independientes.

Siguiente lección: 02 — La anatomía de una etapa. Construimos PipelineStage y PIPELINE_STAGES, y ejecutamos la primera etapa del pipeline de Reservo.

Recursos adicionales

Anthropic — Building effective agents — El patrón de "prompt chaining" descrito ahí (un paso alimenta al siguiente, en una secuencia fija) es, con otro vocabulario, exactamente el pipeline de este módulo.
Anthropic — Multi-agent research system — Un flujo de trabajo real con etapas obligatorias en orden fijo antes de que un resultado se dé por confirmado.
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 — ast.literal_eval — La función que el mecanismo de encadenado de este módulo usa para anclar el payload en el resultado real de una tool, nunca en texto libre.

← AnteriorMini-proyecto: el supervisor de Reservo Siguiente →La anatomía de una etapa