Phase 16 - Lesson 04

El Modelo de Primitivas Multiagente

Cada framework multiagente lanzado en 2026 — AutoGen, LangGraph, CrewAI, OpenAI Agents SDK, Microsoft Agent Framework — es un punto en un espacio de diseño tetradimensional. Cuatro primitivas, nada más: el agente, o handoff (transferencia), el estado compartido y el orquestador. Esta lección los construye desde cero, ejecuta un sistema experimental en los cuatro y luego mapea cada framework principal en los mismos ejes para que puedas entender cualquier nuevo lanzamiento en un solo párrafo.

Tipo: Aprender Lenguajes: Python (stdlib) Prerrequisitos: Fase 14 (Ingeniería de Agentes), Fase 16 · 01 (Por qué Multiagente) Tiempo: ~60 minutos

El Problema

Cada seis meses se lanza un nuevo framework multiagente. AutoGen en 2023. CrewAI en 2024. LangGraph y OpenAI Swarm en 2024. Google ADK en abril de 2025. Microsoft Agent Framework RC en febrero de 2026. Cada comunicado de prensa afirma ser "la abstracción correcta".

Si intentas aprenderlos uno a la vez, terminarás exhausto (burnout). Las API se ven diferentes. La documentación no se pone de acuerdo sobre qué es un "agente". Un framework llama a su memoria compartida "blackboard" (pizarra), otro la llama "message pool" (grupo de mensajes) y un tercero la llama "StateGraph". Empiezas a sospechar que el campo solo está dando vueltas sobre lo mismo.

No es así. Detrás del marketing, las cuatro primitivas son estables. Apréndelas una vez y entenderás cualquier framework nuevo en un solo párrafo.

Concepto

Las cuatro primitivas

  1. Agente — un prompt del sistema más una lista de herramientas. Sin estado (stateless); cada ejecución comienza desde su prompt del sistema y el historial de mensajes actual.
  2. Handoff — una transferencia estructurada de control de un agente a otro. Mecánicamente, una llamada a una herramienta que devuelve un nuevo agente o una arista del grafo que sigue una condición.
  3. Estado compartido — cualquier estructura de datos que más de un agente pueda leer (y a veces escribir). Pool de mensajes, blackboard, almacenamiento de clave-valor, memoria vectorial.
  4. Orquestador — quien decide quién habla a continuación. Opciones: un grafo explícito (determinista), un seleccionador de orador basado en LLM (suave/soft), la llamada de handoff del último orador (OpenAI Swarm) o un planificador sobre una cola (arquitectura swarm).

Ese es todo el espacio de diseño. Cada framework elige valores predeterminados para cada eje; el resto es sintaxis superficial.

Cómo se mapea cada framework de 2026 a él

Framework Agente Handoff Estado compartido Orquestador
OpenAI Swarm / Agents SDK Agent(instructions, tools) la herramienta devuelve Agent problema del llamador la próxima llamada de handoff de la LLM
AutoGen v0.4 / AG2 ConversableAgent selector de orador en GroupChat pool de mensajes función de selección (LLM o round-robin)
CrewAI Agent(role, goal, backstory) Process.Sequential / Hierarchical salidas de Task encadenadas LLM gerente u orden estático
LangGraph función de nodo arista de grafo + condición reductor de StateGraph el grafo, determinista
Microsoft Agent Framework agente + patrones de orquestación específico del patrón hilo / contexto específico del patrón
Google ADK agente + tarjeta A2A tarea A2A artefactos A2A el host decide

Las diferencias superficiales parecen enormes. Por debajo: las mismas cuatro perillas de control.

Por qué es importante

Una vez que ves las primitivas, la comparación de frameworks se convierte en una lista de verificación corta:

  • ¿El orquestador confía en la LLM para enrutar (Swarm) o fija el enrutamiento en el código (LangGraph)?
  • ¿El estado compartido es de historial completo (GroupChat) o proyectado (reductor de StateGraph)?
  • ¿Pueden los agentes modificar los prompts de los demás (gerente de CrewAI) o solo transferir el control con un handoff (Swarm)?

Esas tres preguntas responden al 80% de qué framework se adapta mejor a un problema determinado. Dejas de buscar "el mejor framework multiagente" y comienzas a diseñar para el eje que realmente te interesa.

La perspectiva de la ausencia de estado

Cada primitiva, excepto el estado compartido, es stateless (sin estado). El Agente es una función de (prompt, herramientas). El Handoff es una llamada a una función. El Orquestador es un planificador. Lo único que tiene estado en el sistema es el estado compartido. Ahí es donde viven todos los errores interesantes: envenenamiento de memoria (Lección 15), ordenamiento de mensajes, control de versiones, contención de escritura.

Los frameworks que ocultan el estado compartido (Swarm) trasladan el problema al llamador. Los frameworks que lo centralizan (checkpoint de LangGraph, pool de AutoGen) lo hacen inspeccionable pero trasladan el costo de coordinación a la implementación del estado compartido.

Anatomía de una sola primitiva

Agente

Agent = (system_prompt, tools, model, optional_name)

Sin memoria. Sin estado. Dos agentes con el mismo prompt del sistema y las mismas herramientas son intercambiables. Todo lo que parece un estado por agente está en realidad en el estado compartido o en el protocolo de handoff.

Handoff

Handoff = (from_agent, to_agent, reason, payload)

Dominan tres implementaciones:

  • Retorno de función — la herramienta devuelve el siguiente agente. Este es el patrón de OpenAI Swarm. Los agentes llevan el enrutamiento en sus esquemas de herramientas.
  • Arista del grafo — LangGraph. Las aristas son declarativas. La LLM produce un valor; una condición selecciona el siguiente nodo.
  • Selección de orador — AutoGen GroupChat. Una función selectora (a veces una llamada a una LLM en sí misma) lee el pool y elige quién habla a continuación.

Estado compartido

SharedState = { messages: [], artifacts: {}, context: {} }

Como mínimo, una lista de mensajes. A menudo más: artefactos estructurados (salidas de Task de CrewAI), contexto tipado (reductores de LangGraph), memoria externa (MCP, base de datos vectorial).

Dos topologías: pool completo (cada agente ve cada mensaje) y proyectado (los agentes ven una vista delimitada por rol). Los pools completos son simples y escalan mal. Los pools proyectados escalan pero requieren un diseño de esquema previo.

Orquestador

Orchestrator = ({state, last_speaker}) -> next_agent

Cuatro variantes:

  • Estático — el grafo se fija en el momento de la construcción (LangGraph determinista, CrewAI Sequential).
  • Selecionado por LLM — una LLM lee el pool y elige al siguiente orador (AutoGen, CrewAI Hierarchical).
  • Dirigido por handoff — el agente actual decide llamando a una herramienta de handoff (Swarm).
  • Dirigido por cola — los workers obtienen tareas de una cola compartida; no hay un orador explícito siguiente (arquitecturas de swarm, Matrix).

Qué cambia entre frameworks

Una vez fijadas las primitivas, las decisiones de diseño restantes son:

  • Estrategia de memoria — checkpointing efímero frente a duradero (checkpointer de LangGraph).
  • Límite de seguridad — quién puede aprobar un handoff (humano en el bucle / human-in-the-loop).
  • Contabilidad de costos — presupuestos de tokens por agente.
  • Observabilidad — seguimiento (tracing) de handoffs, persistencia del estado para reproducción (replay).

Todo implementable sobre las primitivas. Ninguna de ellas es una nueva primitiva.

Constrúyelo

code/main.py implementa las cuatro primitivas en aproximadamente 150 líneas de Python stdlib. Sin LLM real: cada agente es una política escrita en código (scripted) para que el enfoque permanezca en la estructura de coordinación.

El archivo exporta:

  • Agent — una dataclass de nombre, prompt del sistema, herramientas, función de política.
  • Handoff — una función que devuelve un nuevo agente.
  • SharedState — un pool de mensajes seguro para hilos (thread-safe).
  • Orchestrator — tres variantes: StaticOrchestrator, HandoffOrchestrator, LLMSelectorOrchestrator (simulado).

La demostración ejecuta el mismo flujo de tres agentes (investigación → escritura → revisión) a través de los tres tipos de orquestador e imprime el pool de mensajes al final. Puedes ver que los resultados difieren solo en quién elige al siguiente; los agentes y el estado compartido son idénticos en todas las ejecuciones.

Ejecútalo:

python3 code/main.py

Resultado esperado: tres ejecuciones del orquestador, una por patrón. Cada una imprime el pool de mensajes final. La ejecución dirigida por handoff llega a menos agentes si el investigador decide que terminó antes de tiempo: ese es el compromiso (trade-off) del enrutamiento por LLM en miniatura.

Úsalo

outputs/skill-primitive-mapper.md es una habilidad (skill) que lee cualquier base de código o documentación de framework multiagente y devuelve el mapeo de cuatro primitivas. Ejecútalo en el lanzamiento de un nuevo framework para obtener una comprensión de un solo párrafo antes de leer la documentación en profundidad.

Ponlo en Producción

Antes de adoptar un nuevo framework, escribe el mapeo de primitivas para él. Si no puedes, la documentación está incompleta o el framework está inventando una quinta primitiva (raro: busca una variante de estado compartido que no hayas visto antes).

Fija el mapeo en tu documento de arquitectura. Cuando se una un nuevo miembro al equipo, envíale el mapeo antes de la documentación de la API. Cuando cambien las versiones del framework, compara (diff) el mapeo, no el registro de cambios (changelog).

Ejercicios

  1. Ejecuta code/main.py tres veces con diferentes políticas de agentes. Observa cómo la elección del orquestador cambia qué agentes se ejecutan.
  2. Implementa un cuarto tipo de orquestador: uno dirigido por cola donde los agentes consultas (poll) el estado compartido en busca de trabajo. ¿Qué bloqueo mutuo (deadlock) puede ocurrir y cómo lo detectas?
  3. Toma la guía de inicio rápido de LangGraph (https://docs.langchain.com/oss/python/langgraph/workflows-agents) y reescríbela como las cuatro primitivas. ¿Cuáles de las abstracciones de LangGraph se mapean 1:1 y cuáles son wrappers de conveniencia?
  4. Lee el cookbook de OpenAI Swarm (https://developers.openai.com/cookbook/examples/orchestrating_agents). Identifica cuál de las cuatro primitivas hace que Swarm sea más ergonómico y cuál delega al llamador.
  5. Encuentra un framework en esta tabla que oculte el estado compartido por completo. Explica qué se rompe cuando los agentes necesitan coordinarse a través de handoffs sin volver a leer el historial.

Términos Clave

Término Lo que la gente dice Lo que realmente significa
Agente "Una LLM con herramientas" Una tupla triple (system_prompt, tools, model). Stateless.
Handoff "Transferencia de control" Una llamada estructurada que especifica el siguiente agente y un payload opcional. Tres implementaciones: retorno de función, arista del grafo, selección de orador.
Estado compartido "Memoria" / "contexto" La única parte con estado de un sistema multiagente. Pool de mensajes o blackboard.
Orquestador "Coordinador" Quien decida qué agente se ejecuta a continuación. Grafo estático, selector por LLM, dirigido por handoff o dirigido por cola.
Primitiva "Abstracción" Uno de los cuatro ejes que cada framework parametriza. Not una característica del framework.
Pool de mensajes "Historial de chat compartido" Estado compartido de historial completo. Fácil de razonar, escala mal.
Estado proyectado "Vista con alcance" Vista específica del rol dentro del estado compartido. Escala, requiere diseño de esquema.
Selección de orador "Quién habla a continuación" Patrón de orquestador en el que una función (a menudo una LLM) elige al siguiente agente de un grupo.

Lecturas Adicionales

0 lifetime access. Curriculum based on AI Engineering from Scratch by Rohit Ghumare (MIT, used under attribution).