Módulo 1: Por qué multi-agente (y cuándo no)

Descripción

Esta es la guía de orquestación multi-agente — la continuación directa de agent-fundamentals-and-tool-calling-guide. Ahí construiste un agente: un modelo con tools, un bucle que pide-despacha-alimenta-repite, y hasta cuatro herramientas disponibles a la vez que el modelo aprendió a elegir. Ese agente ya resuelve tareas de varios pasos, con tools que se combinan, y con una respuesta final anclada en lo que las tools realmente devolvieron. La pregunta que abre esta guía es la que ese agente deja pendiente: ¿qué pasa cuando una tarea es demasiado grande, o demasiado distinta en sus partes, para un solo agente?

La respuesta obvia —"agregar más agentes"— es también la más peligrosa si se toma sin medir. Coordinar varios agentes no es gratis: cada agente adicional es un modelo más al que hay que pedirle una decisión, un mensaje más que pasar, un punto más donde algo puede salir mal. Este módulo completo —los ocho que siguen construyen los patrones; este primero construye el criterio— existe para responder una sola pregunta antes de escribir una sola línea de orquestación: ¿esta tarea de verdad necesita varios agentes, o un solo agente con las tools correctas ya alcanza? Vas a medir esa pregunta, no solo discutirla: vas a correr la MISMA tarea de Reservo con un agente y con un sistema de dos agentes, contar las llamadas al modelo y los mensajes entre ellos de cada camino, y ver con números reales cuál cuesta más.

Regla dura de esta guía (léela antes de seguir)

Se mantiene la misma línea de agent-fundamentals: la decisión de cada agente —qué tool llamar, a quién delegar, 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: el runner de cada agente (reusado sin cambios de agent-fundamentals M4/M5), el paso de mensajes entre agentes, y —el corazón de este módulo— el conteo real de cuántas llamadas y cuántos mensajes le toma a cada camino resolver la misma tarea. Nada de LangChain ni LangGraph: todo a mano, stdlib, determinista (sin random ni datetime.now()).

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)  ← ESTÁS AQUÍ
│   → El criterio de decisión, medido con números reales
├── Módulo 2: El patrón supervisor/router
├── 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

Cada "agente" de esta guía es un agente de agent-fundamentals: mismo runner, mismo protocolo tool_use/tool_result, mismas tools canónicas. Lo que cambia es la escala: en vez de un agente con cuatro tools eligiendo cuál usar, vas a tener varios agentes —cada uno con un set de tools más angosto y un rol más especializado— eligiendo entre sí. No se re-explica el while del loop ni el contrato de una tool; se asume construido y se reusa tal cual.

Analogía: armar un equipo de personas

Imagina que tienes una tarea de trabajo. Si es chica —redactar un correo, calcular un total—, la haces tú mismo, sin pedirle ayuda a nadie: pedir ayuda ahí solo suma una reunión para explicar la tarea, esperar a que la otra persona la entienda y la resuelva, y después juntar su resultado con el tuyo. Ninguna de esas tres cosas hace que el correo se redacte más rápido.

Pero si la tarea es genuinamente grande —organizar un evento con catering, logística y invitaciones— un solo empleado sin experiencia en ninguna de las tres áreas tarda mucho más, y comete más errores, que tres especialistas trabajando cada uno en lo suyo. La diferencia no es "más gente siempre ayuda" ni "menos gente siempre es más simple" — es si la tarea se separa en partes genuinamente distintas, cada una con una experticia que la otra no tiene.

Un sistema multi-agente es exactamente ese equipo. Sirve cuando el trabajo es genuinamente separable y cada especialista aporta algo que los demás no tienen. Para una tarea que una persona —o un agente con las tools adecuadas— ya resuelve bien, sumar más gente solo agrega reuniones (coordinación) sin terminar antes. Este módulo entero es aprender a distinguir cuándo estás frente a un evento con catering y logística, y cuándo estás frente a un correo.

El caso que acompaña la guía: el sistema multi-agente de Reservo

agent-fundamentals construyó un agente único con cuatro tools canónicas —list_rooms, get_quote, book_room, cancel_booking— sobre el mismo Reservo, el sistema de reservas de salas de coworking de todo el ecosistema. Esta guía toma ese agente y, donde de verdad hace falta, lo reparte en tres especialistas:

booking_agent — las cuatro tools canónicas, sin cambios. Cotiza, reserva, cancela.
policy_agent — una tool nueva, search_docs(query) -> str, un stub mínimo (2-3 entradas fijas por palabra clave, con los mismos nombres de documento —no-show-policy, cancellation-policy— que el índice real de production-rag-and-document-ingestion-guide, sin reconstruir ese índice completo). Responde preguntas de política.
pricing_agent — sin tool nueva: compone get_quote de booking_agent para comparar el costo de varias salas o tiers en una sola respuesta. Es el ejemplo de un especialista cuyo "expertise" es una forma distinta de usar una tool que ya existe, no una tool nueva.

Las anclas de siempre no cambian: Focus básico 3h = 7500 / Focus pro 3h = 6000 (descuento pro 20% entero, * 80 // 100), salas Focus 2500 / Studio 4000 / Boardroom 8000 por hora, dinero siempre en centavos (int). Vas a verlas reaparecer en cada lección de este módulo.

Frontera con `building-ai-agents-guide` Módulo 8

Antes de seguir, una aclaración que evita una confusión real: building-ai-agents-guide —otra guía del ecosistema, ya publicada— tiene un Módulo 8 que también se llama "Multi-Agent Orchestration" y también enseña Supervisor, Handoffs, Subagents y Router. Si ya cursaste esa guía, el vocabulario te va a sonar conocido. La diferencia de fondo:

	`building-ai-agents-guide` M08	Esta guía (las 8 completas)
Framework	LangGraph/LangChain (requiere API real)	Ninguno — Python 3.14 stdlib, $0
Caso	Research Agent genérico (Supervisor/Researcher/Analyst/Writer)	Reservo: `booking_agent`/`policy_agent`/`pricing_agent`, expertise real
Extensión	5 lecciones de un módulo de un proyecto de 80	Guía completa de 8 módulos, un patrón por módulo
El eje	"Aquí están los patrones, impleméntalos"	"¿Hace falta un patrón, o no?" — este módulo entero
Costo de coordinar	Un párrafo de encuadre	Medido, ejecutado, con números reales (lección 05)

No vas a re-aprender qué es un agente ni el protocolo tool_use/tool_result —eso ya lo construiste en agent-fundamentals, la base de todo el ecosistema, no de esa guía—. Y no vas a usar LangGraph aquí: cada patrón se construye a mano, para que entiendas qué hace un framework de orquestación por debajo antes de decidir si adoptar uno. La lección 07 retoma esta frontera con más detalle, patrón por patrón.

Prerequisitos

Conocimiento requerido:

✅ agent-fundamentals-and-tool-calling-guide completa: el contrato de una tool, el protocolo tool_use/tool_result, el while del bucle, multi-tool y selección, tool calls en paralelo con concurrent.futures, grounding.
✅ Python: dataclasses, diccionarios, funciones, concurrent.futures a nivel de uso (no hace falta reconstruirlo).

NO requerido:

❌ No necesitas una API key ni conexión a internet: la decisión de cada agente es concepto, escrita a mano.
❌ No necesitas conocer LangChain, LangGraph, CrewAI ni ningún framework de orquestación — esta guía construye los patrones desde cero, a propósito.

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 criterio de decisión, el caso Reservo con sus tres especialistas, y la frontera con building-ai-agents-guide M08.

Lección 02 — Qué es un sistema multi-agente

Varios agentes que colaboran, cada uno con su propio loop y sus propias tools — la definición formal, contrastada con un agente único que solo tiene más tools.

Lección 03 — El costo de la coordinación

Más agentes significa más llamadas al modelo, más pasos, más superficie de error. Medido con una fórmula ejecutada, no con intuición.

Lección 04 — Un agente con muchas tools vs. muchos agentes

El árbitro entre dos formas de crecer: un set de tools cada vez más grande (con su costo ya medido en agent-fundamentals M5) vs. repartir esas tools entre varios agentes especializados.

Lección 05 — La comparación ejecutada

La pieza central del módulo: la MISMA tarea de Reservo resuelta por un agente y por un sistema de dos agentes, con las llamadas y los mensajes contados de verdad.

Lección 06 — Cuándo multi-agente SÍ ayuda

El otro lado de la balanza: tareas genuinamente separables, tools que colisionan si se juntan, y contextos que conviene aislar.

Lección 07 — Preview de los patrones

Un mapa de los cinco patrones que construyen los módulos 2 a 6 — qué resuelve cada uno y cuándo usarlo — más el detalle de la frontera con building-ai-agents-guide M08.

Lección 08 — Mini-proyecto: decide single o multi

Aplicas el criterio completo del módulo a varios escenarios nuevos, con una función de decisión que tú mismo ejecutas y luego cuestionas.

Mapa de progresión

Lección 01 (esta)  → El criterio, el caso, la frontera
Lección 02         → Qué es (y qué no es) un sistema multi-agente
Lección 03         → El costo de coordinar, medido
Lección 04         → Un agente con más tools vs. repartir tools
Lección 05         → La comparación ejecutada (la pieza dura)
Lección 06         → Cuándo multi-agente SÍ se justifica
Lección 07         → Los cinco patrones que vienen
Lección 08         → Proyecto: decidir con criterio

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

Qué lograrás en este módulo

Al completar las 8 lecciones, podrás:

Definir un sistema multi-agente y distinguirlo con precisión de un agente único con varias tools.
Cuantificar el costo de coordinar —llamadas al modelo, mensajes entre agentes, superficie de error— en vez de asumirlo o ignorarlo.
Elegir entre crecer un solo agente o repartir tools entre varios, con el costo de cada camino medido, no adivinado.
Ejecutar y comparar, con números reales de tu propia terminal, la misma tarea resuelta por un agente y por un sistema de dos agentes.
Reconocer las tres señales que sí justifican multi-agente: separabilidad genuina, expertise distinto, necesidad de aislar contexto.
Ubicar los cinco patrones que vienen (supervisor, pipeline, fan-out, handoff, blackboard) y saber, a grandes rasgos, cuándo usar cada uno.
Aplicar el criterio completo a un escenario nuevo y justificar la decisión con evidencia, no con intuición.

El antes y después

ANTES del módulo:
→ "Más agentes siempre resuelve más rápido y mejor"
→ "Si un agente hace mucho, la solución es dividirlo en varios"
→ "Coordinar varios agentes no tiene costo real, solo más capacidad"
→ "Los roles (supervisor, investigador, crítico) siempre ayudan a pensar mejor"

DESPUÉS del módulo:
→ Multi-agente ayuda SOLO cuando la tarea es genuinamente separable
→ Un agente con las tools correctas resuelve mejor una tarea NO separable
→ Coordinar cuesta: más llamadas, más mensajes, más superficie de error -- MEDIDO
→ Un rol sin una tool o expertise real detrás es decoración, no arquitectura

Trampas a evitar al cursar este módulo

1. "Un sistema con 3 agentes es más sofisticado que uno con 1"

No. Sofisticado no es sinónimo de mejor. Un sistema de 3 agentes que resuelve en 8 llamadas lo que un agente resuelve en 3 no es sofisticado — es más costoso, más lento y con más puntos de falla, para el mismo resultado. La lección 05 lo mide.

2. "Roles como CEO, investigador o crítico dan estructura al razonamiento"

A veces. Pero un rol sin una tool o un dominio de datos que lo distinga de los demás es teatro, no arquitectura — cuesta lo mismo en llamadas y mensajes que un rol real, sin aportar ninguna capacidad nueva. La lección 06 muestra la diferencia con un ejemplo medido.

3. "Este módulo ya me enseña a construir el supervisor"

No todavía. Este módulo mide si hace falta un patrón — el supervisor completo, con su enrutamiento por reglas y por decisión del modelo, es el Módulo 2. Aquí construyes el criterio que vas a aplicar en cada módulo siguiente.

4. "Si `building-ai-agents-guide` ya cubrió esto, esta guía es redundante"

No. Esa guía enseña los patrones con LangGraph, sobre un caso de investigación genérico, en 5 lecciones de un módulo. Esta guía los construye sin framework, sobre Reservo, con el costo de cada decisión medido — un nivel de profundidad que esa guía no tiene espacio para dar.

5. "La decisión de a qué agente delegar se está ejecutando de verdad"

No. Regla dura: qué hace cada agente y a quién delega es concepto (claude-sonnet-5). Lo que se ejecuta es el runner de cada agente, el paso de mensajes entre ellos, y el conteo de ese costo.

Cómo trabajar este módulo

Corre la comparación de la lección 05 tú mismo. Es la pieza que sostiene todo el módulo — verla con tus propios números, no solo leerla, es lo que hace que el criterio se sienta real.
No asumas que multi-agente es "más avanzado" o "mejor arquitectura". Cada lección te pide justificar con una señal concreta (separabilidad, expertise, aislamiento), no con intuición.
El mini-proyecto es la síntesis. La lección 08 te da escenarios nuevos y una función de decisión — practicar con ella antes del Módulo 2 hace que cada patrón que sigue se sienta justificado, no arbitrario.

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         →  35 min + correr la demo (la más densa del módulo)
Lección 06         →  25 min + correr la demo
Lección 07         →  20 min lectura
Lección 08         →  30 min + aplicar el criterio

Total: ~3.2 horas

Evidencia de éxito

Antes de avanzar al Módulo 2 (El patrón supervisor/router), deberías poder:

✅ Explicar qué es un sistema multi-agente con tus propias palabras, sin confundirlo con un agente de varias tools.
✅ Citar de memoria el resultado de la comparación ejecutada de la lección 05: cuántas llamadas y mensajes de más cuesta el sistema de dos agentes frente al agente único, para la misma tarea.
✅ Nombrar las tres señales que justifican multi-agente, y dar un ejemplo de Reservo para cada una.
✅ Ubicar cuál de los cinco patrones (supervisor, pipeline, fan-out, handoff, blackboard) aplica a un escenario nuevo, a grandes rasgos.
✅ Aplicar el criterio del módulo a un escenario que no viste antes, y justificar la decisión con evidencia.

Resumen

Esta guía orquesta varios agentes de Reservo —cada uno el mismo tipo de agente que construiste en agent-fundamentals, con un rol más angosto— para resolver tareas que un solo agente no resuelve bien.
El Módulo 1 no construye ningún patrón todavía: construye el criterio para decidir si hace falta uno, y lo mide con números reales, no con intuición.
Regla dura: la decisión de cada agente sigue siendo concepto (claude-sonnet-5); el runner de cada agente, el paso de mensajes y el conteo del costo de coordinar se ejecutan de verdad con Python 3.14.
El caso son tres especialistas de Reservo —booking_agent, policy_agent, pricing_agent— con expertise genuinamente distinto, no roles decorativos.
Frontera clara con building-ai-agents-guide M08: mismo vocabulario de patrones, profundidad y enfoque completamente distintos — sin framework, con el costo de cada decisión medido.

Siguiente lección: 02 — Qué es un sistema multi-agente. Definimos con precisión qué distingue a varios agentes colaborando de un agente único con más tools, y por qué esa distinción importa antes de construir nada.

Recursos adicionales

Anthropic — Building effective agents — El principio de empezar con la solución más simple y sumar complejidad (más tools, más agentes) solo cuando la tarea lo exige; el eje de todo este módulo.
Anthropic — Multi-agent research system — Un caso real de Anthropic sobre cuándo un sistema multi-agente se justificó y qué costo de coordinación tuvieron que resolver.
Anthropic — Tool use (function calling) overview — El protocolo que cada agente de esta guía sigue usando, sin cambios, para sus propias tools.
Python 3.14 — What's New — La versión con la que se ejecuta toda la orquestación de esta guía.

Siguiente →Qué es un sistema multi-agente