Módulo 10: Multi-Agent Systems

Introducción: De Un Agente a Muchos

Siguiente →

Descripción

Tu AI Research Assistant es supervisado. Tiene retry con backoff, búsqueda paralela, memoria persistente, time-travel debugging, long-term memory, multi-usuario, y aprobaciones humanas antes de acciones costosas. Lo construiste a lo largo de los Módulos 6-9. Es un agente de producción.

Pero hace todo.

Busca información. Analiza los resultados. Genera el reporte. Decide el formato. Selecciona las fuentes. Maneja errores. Un solo agente con un system prompt de 1800 tokens, 10 tools, y la esperanza de que el LLM elija correctamente cada vez.

Imagina este escenario: le pides "investiga el impacto de AI en finanzas, analiza los datos y genera un reporte ejecutivo." Tu agente tiene que ser buen investigador, buen analista, Y buen escritor. Con un solo system prompt. Con un solo modelo.

Ahora imagina esto: un agente investigador experto en buscar fuentes (3 tools de búsqueda, modelo barato y rápido). Un agente analista experto en encontrar patrones (1 tool de análisis, modelo potente). Un agente escritor experto en redacción ejecutiva (sin tools, modelo creativo). Y un supervisor que coordina quién trabaja cuándo.

Mismo problema. Mejor resultado. Más fácil de debuggear. Más barato de operar.

Eso es multi-agent: dividir una tarea compleja entre agentes especializados que hacen su parte mejor que un generalista.

Pero — y esto es crítico — multi-agent no es siempre mejor. Un solo agente con buenas tools es más simple, más rápido, y más fácil de mantener. Multi-agent se justifica solo cuando la complejidad lo requiere. Este módulo te da el criterio para decidir cuándo usarlo y cuándo no.

¿Dónde estamos en la guía?

Este es el Módulo 10 de la guía LangChain & LangGraph: From Chains to Agents. Es el último módulo del Bloque 3 (LangGraph Avanzado).

Bloque 1: LangChain Core (Módulos 1-4)           ✅ Completado
Bloque 2: LangGraph Fundamentals (Módulos 5-7)   ✅ Completado
Bloque 3: LangGraph Avanzado (Módulos 8-10)      ← ESTÁS AQUÍ (Módulo 10)
Bloque 4: Producción (Módulos 11-12)

Tu progreso:

Bloque 1 — LangChain Core                   ✅ Completado
    │
    │  Módulo 1: Modelos y Proveedores       ✅
    │  Módulo 2: Tools y Tool Calling        ✅
    │  Módulo 3: Agents (create_agent)       ✅
    │  Módulo 4: Middleware y Customización   ✅
    │
    ▼
Bloque 2 — LangGraph Fundamentals           ✅ Completado
    │
    │  Módulo 5: Introducción a LangGraph    ✅
    │  Módulo 6: Functional API              ✅
    │  Módulo 7: Flujos Avanzados            ✅
    │
    ▼
Bloque 3 — LangGraph Avanzado
    │
    │  Módulo 8: Memoria y Persistencia      ✅ Completado
    │  Módulo 9: Human-in-the-Loop           ✅ Completado
    │  Módulo 10: Multi-Agent Systems        ← ESTÁS AQUÍ
    │
    ▼
Bloque 4 — Producción                       🔒
    │
    │  Módulo 11: Deep Agents                🔒
    │  Módulo 12: LangSmith y Producción     🔒

Este módulo cierra el Bloque 3. Después de aquí, entiendes los tres niveles de abstracción para construir agentes: create_agent (un agente simple), LangGraph (un agente con workflow custom), y multi-agent (múltiples agentes coordinados). El Bloque 4 agrega producción: Deep Agents (M11) y LangSmith (M12).

El puente desde el Módulo 9

Lo que ya tienes

Tu Research Agent v4 es un sistema supervisado:

  • ✅ Retry con backoff exponencial y graceful degradation
  • ✅ Búsqueda paralela en múltiples fuentes
  • ✅ Checkpointing, crash recovery, y time-travel debugging
  • ✅ Long-term memory y multi-usuario con thread_id
  • ✅ Approval gates antes de acciones costosas
  • ✅ Review del plan de investigación antes de ejecutar
  • ✅ Feedback para redirigir la investigación a mitad de camino
  • ✅ State edit para corregir datos antes del reporte final

La pregunta que falta

Tu agente es capaz, robusto, persistente, y supervisado. Pero hace todo con un solo system prompt y un solo modelo.

Tu Research Agent v4 recibe: "Investiga AI en finanzas, analiza tendencias, genera reporte"

Un solo agente hace TODO:
  → Busca en 3 fuentes (necesita ser buen buscador)
  → Analiza los resultados (necesita ser buen analista)
  → Genera el reporte (necesita ser buen escritor)
  → Decide el formato (necesita entender presentación)

Problema:
  ❌ El system prompt intenta cubrir 4 roles diferentes
  ❌ 10+ tools — el agente se confunde sobre cuál usar
  ❌ Un solo modelo para todo (gpt-4.1 para búsqueda es caro e innecesario)
  ❌ Si el reporte sale mal, ¿fue la búsqueda, el análisis, o la redacción?

La solución no es un agente más inteligente. Es dividir el trabajo.

Cuándo UN agente NO es suficiente

No todo problema necesita multi-agent. Estos son los señales concretas de que tu agente único está llegando a su límite:

Señal 1: El system prompt supera 2000 tokens

Si tu prompt intenta cubrir búsqueda, análisis, escritura, formato, y manejo de errores — está intentando ser todo. Un prompt que es todo no es nada.

Señal 2: Más de 8 tools

Cuando un agente tiene 10-15 tools, empieza a confundirse sobre cuál usar. Un investigador con web_search, arxiv_search, y scholar_search es claro. Un agente con esas 3 más analyze_data, create_chart, write_report, send_email, format_table, translate, y summarize tiene demasiadas opciones.

Señal 3: Diferentes tareas necesitan diferentes modelos

Buscar en la web es una tarea simple — gpt-4.1-mini es suficiente y cuesta 10x menos. Analizar patrones complejos requiere gpt-4.1. Generar texto creativo funciona mejor con ciertos modelos. Un solo agente usa un solo modelo para todo.

Señal 4: Debugging es difícil porque no puedes aislar el problema

"El reporte salió mal." ¿Fue porque la búsqueda encontró fuentes malas? ¿El análisis interpretó mal los datos? ¿La redacción fue pobre? Con un solo agente, no puedes aislar qué parte falló.

Señal 5: Quieres paralelismo real

Un agente procesa secuencialmente. Con multi-agent, puedes buscar en 3 fuentes en paralelo mientras otro agente prepara el template del reporte.

Beneficios de multi-agent

Especialización

Cada agente es experto en UNA cosa. Un researcher con 3 tools de búsqueda produce mejores resultados que un agente generalista con 15 tools. Es el Single Responsibility Principle aplicado a agentes.

Paralelización

Agentes pueden trabajar simultáneamente. El researcher busca mientras el analyst prepara su framework de análisis.

Separación de concerns

Si el reporte sale mal, sabes exactamente qué agente falló. Puedes mejorar el researcher sin tocar al analyst. Puedes testear cada agente independientemente.

Optimización de modelos

Usa el modelo correcto (y más barato) para cada tarea:

Researcher: gpt-4.1-mini  → $0.40/M input  (buscar es simple)
Analyst:    gpt-4.1        → $2.00/M input  (analizar es complejo)
Writer:     gpt-4.1-mini  → $0.40/M input  (redactar con buen prompt es simple)

vs.

Agente único: gpt-4.1     → $2.00/M input para TODO (incluido búsqueda simple)

Los 4 patrones de multi-agent

Existen cuatro arquitecturas principales. Las verás en detalle en las cápsulas técnicas:

1. Supervisor

Un agente central recibe la consulta, decide qué agente debe trabajar, delega, recibe resultados, y decide los siguientes pasos. Es el patrón más común.

                 ┌──────────┐
                 │Supervisor│
                 └────┬─────┘
              ┌───────┼───────┐
              ▼       ▼       ▼
         ┌────────┐┌───────┐┌──────┐
         │Research││Analyst││Writer│
         └────────┘└───────┘└──────┘

2. Handoffs

Un agente transfiere el control directamente a otro agente. No hay supervisor central — los agentes se pasan el trabajo entre sí como una cadena de relevos.

         ┌────────┐    ┌───────┐    ┌──────┐
         │Research│ ──▶│Analyst│ ──▶│Writer│
         └────────┘    └───────┘    └──────┘

3. Subagents (jerárquico)

Un agente invoca a otros como "subcontratistas." El agente principal mantiene el control total — los subagents son como tools que resultan ser agentes completos.

         ┌──────────────────┐
         │   Main Agent     │
         │  ┌──────┐        │
         │  │Sub A │        │
         │  └──────┘        │
         │  ┌──────┐        │
         │  │Sub B │        │
         │  └──────┘        │
         └──────────────────┘

4. Router

Un componente ligero (puede ser un LLM o reglas simples) clasifica la consulta entrante y la envía al agente correcto. Solo un agente procesa cada consulta.

         ┌──────┐     ┌────────┐
         │Router│ ──▶ │Agent A │  (si es búsqueda)
         │      │ ──▶ │Agent B │  (si es análisis)
         │      │ ──▶ │Agent C │  (si es escritura)
         └──────┘     └────────┘

La analogía con microservicios

Si vienes de software engineering, la analogía es directa:

Monolito → MicroserviciosAgente único → Multi-agent
Una aplicación hace todoUn agente hace todo
Cada servicio tiene una responsabilidadCada agente tiene una especialidad
Los servicios se comunican via APIsLos agentes se comunican via estado compartido
Un API gateway routea las requestsUn supervisor routea las tareas
Cada servicio se escala independientementeCada agente usa el modelo óptimo
Debugging: logs por servicioDebugging: tracing por agente

La misma regla aplica: no dividas en microservicios un monolito que funciona bien. Solo divide cuando la complejidad lo justifica.

Cuándo NO usar multi-agent

Esto es tan importante como saber cuándo usarlo:

Simple Q&A → un solo agente

Si tu agente responde preguntas usando 2-3 tools, multi-agent es over-engineering. create_agent con un buen prompt es suficiente.

Pipeline lineal sin branching → un solo agente o Functional API

Si el flujo es siempre "buscar → analizar → escribir" sin variaciones, no necesitas un supervisor que decida. Un StateGraph lineal o @entrypoint + @task hace lo mismo con menos complejidad.

Presupuesto limitado → menos agentes = menos API calls

Cada agente adicional es al menos una llamada extra al LLM. Un supervisor con 3 workers puede generar 5-10 llamadas LLM por consulta. Si el costo importa, un solo agente bien diseñado es más eficiente.

Latencia crítica → menos agentes = menos overhead

Cada handoff entre agentes agrega latencia. Para aplicaciones que necesitan respuesta en <2 segundos, multi-agent puede ser demasiado lento.

Regla de oro

Empieza con un solo agente. Solo escala a multi-agent cuando las señales de la sección anterior sean claras. "Premature multi-agent is the root of all evil" — la misma regla que aplica a microservicios aplica aquí.

Mapa del módulo

#CápsulaQué aprenderásTipo
01Introducción (esta)Cuándo y por qué usar multi-agent, los 4 patrones, cuándo NO usarloIntro
02Pattern SupervisorSupervisor como coordinador, workers especializados, create_supervisorTécnica
03Pattern HandoffsTransferencia directa entre agentes, handoff tools, flujo sin supervisorTécnica
04Estado compartido vs aisladoDiseño de estado en multi-agent, shared vs isolated, contratos entre agentesTécnica
05Comunicación entre agentesCómo los agentes pasan información, message history management, contextTécnica
06HITL en multi-agentSupervisión humana en sistemas multi-agente, quién aprueba quéTécnica
07Debugging y observabilidadLogging por agente, tracing del flujo, identificar qué agente fallóTécnica
08Proyecto: Research TeamResearch Agent v5: researcher + analyst + writer + supervisorProyecto

Flujo de aprendizaje

Empiezas con el patrón Supervisor (cápsula 02) — la arquitectura más común y el punto de partida natural. Luego aprendes Handoffs (cápsula 03) — transferencia directa entre agentes sin supervisor central. Con eso dominado, abordas estado compartido vs aislado (cápsula 04) — el problema de diseño más difícil de multi-agent: qué ve cada agente y cómo se previenen conflictos. La cápsula 05 (comunicación entre agentes) cubre cómo fluye la información entre agentes. La cápsula 06 (HITL en multi-agent) aplica los patrones del M9 a nivel de sistema. La cápsula 07 (debugging) te enseña a identificar qué agente causó un problema — esencial para producción. Finalmente, integras todo en el Research Agent v5 (cápsula 08).

La progresión es: supervisor → handoffs → estado → comunicación → HITL → debugging → proyecto.

Conexión con el proyecto

Research Agent v5: el equipo de investigación

Tu Research Agent se transforma en un sistema multi-agente con especialización:

v1 (Módulo 6): Funcional pero frágil
    ↓
v2 (Módulo 7): Robusto (retry, branching, error handling)
    ↓
v3 (Módulo 8): Persistente (checkpointing, memoria, multi-usuario)
    ↓
v4 (Módulo 9): Supervisado (approval gates, review, feedback, state edit)
    ↓
v5 (Este módulo): Multi-agent
    │
    │  🔍 Research Agent:  busca en múltiples fuentes (web, papers, docs)
    │  📊 Analysis Agent:  analiza, sintetiza, identifica patrones
    │  ✍️  Writer Agent:    genera el reporte final
    │  🎯 Supervisor:      coordina el flujo entre los tres
    │
    ▼
v6 (Módulo 11): + Deep Agent (planning automático, virtual filesystem)

La transición es natural: lo que antes era un solo agente haciendo todo, ahora son 3 agentes especializados + 1 supervisor. El resultado: reportes de mayor calidad, procesamiento más rápido (paralelismo), optimización de costos (modelos diferentes por agente), y un sistema más fácil de debuggear.

La prueba de éxito: ejecutas una investigación compleja, y puedes ver en el log qué agente hizo qué, cuánto costó cada uno, y si alguno falló — sin que el resto del sistema se vea afectado.

Conexión con el Módulo 11: Deep Agents

El Módulo 10 te enseña a construir multi-agent manualmente: tú diseñas los agentes, defines los handoffs, y configuras el supervisor. El Módulo 11 introduce la capa "batteries-included": planning automático con write_todos, virtual filesystem, subagent spawning, y long-term memory con backends pluggable. Reimplementarás el Research Agent como Deep Agent para ver cómo el framework provee out-of-the-box lo que construiste manualmente.

Conexión con el Módulo 12: LangSmith y Producción

Cuando tienes 4 agentes generando 10+ llamadas LLM por consulta, la observabilidad se vuelve crítica. LangSmith te da tracing end-to-end del flujo entre agentes, costos por agente, latencia por paso, y métricas de calidad. Lo que aprendes de debugging en la cápsula 07 se profesionaliza con LangSmith en el M12.

Qué NO cubre este módulo

  • ❌ Deep Agents — Planning automático, virtual filesystem, y subagent spawning son del Módulo 11. Aquí construyes multi-agent desde los primitivos
  • ❌ LangSmith tracing — La observabilidad profesional con LangSmith es del Módulo 12. Aquí implementas logging y debugging básico por agente
  • ❌ Deployment de multi-agent — Cómo desplegar un sistema multi-agente con LangGraph Cloud es del Módulo 12
  • ❌ RAG multi-agente — No construimos un sistema RAG con múltiples agentes. El enfoque es el Research Assistant
  • ❌ Agent-to-agent communication protocols — Protocolos como A2A (Agent-to-Agent) de Google o MCP son temas de interoperabilidad que van más allá del scope de este módulo

Setup técnico

Prerequisitos

  • ✅ Módulo 9 completado — tienes un Research Agent v4 con HITL
  • ✅ Python 3.11+ instalado
  • ✅ Al menos una API key de un proveedor (OpenAI recomendado)
  • ✅ Checkpointer funcionando — ya usas MemorySaver desde el M8

Instalación

Un paquete nuevo para el patrón Supervisor:

pip install langgraph langchain-openai python-dotenv langgraph-supervisor

Verifica las importaciones:

from langchain.agents import create_agent
from langgraph_supervisor import create_supervisor
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.checkpoint.memory import MemorySaver

print("create_agent disponible")
print("create_supervisor disponible")
print("StateGraph disponible")
# Output esperado:
# create_agent disponible
# create_supervisor disponible
# StateGraph disponible

Variables de entorno

Tu .env del Módulo 9 sigue funcionando:

# .env
OPENAI_API_KEY=sk-...

Verificación rápida: multi-agent básico

Ejecuta este script para verificar que el patrón supervisor funciona. Usa un supervisor manual (sin LLM) para que no necesites API key todavía:

from langgraph.graph import StateGraph, START, END
from typing import TypedDict


class TeamState(TypedDict):
    query: str
    research: str
    analysis: str
    current_agent: str
    step: int


def supervisor(state: TeamState) -> dict:
    step = state.get("step", 0)
    if step == 0:
        return {"current_agent": "researcher", "step": 1}
    elif step == 1:
        return {"current_agent": "analyst", "step": 2}
    return {"current_agent": "done", "step": 3}


def researcher(state: TeamState) -> dict:
    return {"research": f"5 fuentes encontradas para: '{state['query']}'"}


def analyst(state: TeamState) -> dict:
    return {"analysis": f"3 patrones en: {state['research'][:40]}..."}


def route(state: TeamState) -> str:
    return state["current_agent"]


builder = StateGraph(TeamState)
builder.add_node("supervisor", supervisor)
builder.add_node("researcher", researcher)
builder.add_node("analyst", analyst)

builder.add_edge(START, "supervisor")
builder.add_conditional_edges("supervisor", route, {
    "researcher": "researcher",
    "analyst": "analyst",
    "done": END,
})
builder.add_edge("researcher", "supervisor")
builder.add_edge("analyst", "supervisor")

graph = builder.compile()

result = graph.invoke({
    "query": "Estado del arte en RAG 2025",
    "research": "", "analysis": "",
    "current_agent": "", "step": 0,
})

print(f"Research: {result['research']}")
print(f"Analysis: {result['analysis']}")
print(f"Steps: {result['step']}")
# Output esperado:
# Research: 5 fuentes encontradas para: 'Estado del arte en RAG 2025'
# Analysis: 3 patrones en: 5 fuentes encontradas para: 'Estado de...
# Steps: 3

Si ves el research y el analysis completados, y 3 steps, el patrón supervisor funciona: el supervisor delegó al researcher, recibió el resultado, delegó al analyst, recibió el resultado, y terminó.

Evidencia de éxito

Al terminar este módulo, sabrás que tuviste éxito si:

  • ✅ Puedes diseñar un sistema multi-agente con el patrón Supervisor usando create_supervisor
  • ✅ Implementas handoffs entre agentes — un agente delega trabajo a otro y recibe el resultado
  • ✅ Creas agentes especializados con tools, prompts, y modelos propios
  • ✅ Manejas estado compartido vs aislado entre agentes
  • ✅ Sabes decidir cuándo un solo agente es suficiente vs cuándo necesitas multi-agent
  • ✅ Tu Research Agent v5 tiene 3 agentes especializados + 1 supervisor que produce mejores resultados que el v4

Test de autoevaluación

Si puedes responder estas preguntas, vas por buen camino:

  1. ¿Cuándo un solo agente con buenas tools es mejor que multi-agent?
  2. ¿Cuál es la diferencia entre el patrón Supervisor y el patrón Handoffs?
  3. Si tu supervisor usa gpt-4.1 para decidir a quién delegar, ¿es necesario? ¿Qué alternativa más barata existe?
  4. ¿Cómo decides si dos agentes deben compartir estado o tener estado aislado?
  5. Si tu sistema tiene 8 agentes especializados, ¿es un buen diseño? ¿Por qué?

Resumen

  • Tu Research Agent v4 es capaz pero hace todo con un solo agente: búsqueda, análisis, redacción. Cuando el system prompt supera 2000 tokens, tienes más de 8 tools, o necesitas diferentes modelos por tarea — es momento de considerar multi-agent
  • Multi-agent no es siempre mejor. Un solo agente con buenas tools es más simple, más rápido, y más fácil de debuggear. Multi-agent se justifica cuando hay especialización real, prompts demasiado largos, diferentes modelos por subtarea, o necesidad de separar concerns
  • Cuatro patrones: Supervisor (coordinador central), Handoffs (transferencia directa), Subagents (jerárquico), Router (clasificación). El Supervisor es el más común y el punto de partida
  • La analogía con microservicios es directa: no dividas un monolito que funciona bien. Empieza simple, escala cuando sea necesario
  • 3-4 agentes es el sweet spot. El Research Agent se transforma en: researcher (búsqueda), analyst (análisis), writer (redacción), supervisor (coordinación)
  • Especialización produce mejores resultados que un generalista. Un researcher con 3 tools de búsqueda es mejor buscando que un agente con 15 tools que hace de todo. Single Responsibility Principle aplicado a agentes

Recursos adicionales

  1. LangGraph — Multi-Agent Systems — Documentación oficial sobre patrones multi-agent: supervisor, handoffs, subagents
  2. LangGraph Supervisor — Repositorio oficial del paquete langgraph-supervisor con ejemplos y API reference
  3. How to build a multi-agent supervisor — Guía práctica paso a paso para implementar el patrón supervisor
  4. How to implement handoffs — Guía para transferencia directa de control entre agentes
  5. Multi-Agent Architectures — LangChain Blog — Análisis de patrones multi-agent con comparaciones y trade-offs
  6. Microservices Pattern — Martin Fowler — La analogía que usamos en este módulo: cuándo dividir un monolito y cuándo no

Módulo 10 — LangChain & LangGraph: From Chains to Agents

Siguiente cápsula: Pattern Supervisor — aprenderás cómo un agente supervisor coordina workers especializados, la diferencia entre routing simple y routing con LLM, y cómo usar create_supervisor para construir tu primer sistema multi-agente.

← AnteriorProyecto Evolutivo: Aprobaciones Humanas (v4)Siguiente →Pattern Supervisor