Módulo 6: Estado compartido y el patrón blackboard

Descripción

El Módulo 5 construyó el handoff: un agente que ya está trabajando se da cuenta, a mitad de tarea, de que necesita a otro especialista, y le transfiere el control con un paquete mínimo —quién envía, a quién, la tarea, el payload justo que el receptor necesita—. Es un mensaje punto a punto: alguien lo arma a mano, pensando explícitamente en quién lo va a leer.

Este módulo construye la alternativa a esa disciplina. En vez de que cada agente arme un paquete distinto para cada destinatario, los agentes de este módulo leen y escriben un espacio de estado común durante una misma corrida: un Blackboard compartido. Nadie arma un paquete pensando "esto es para policy_agent" — booking_agent simplemente escribe lo que produjo (room, price_cents, booking_id), y cualquier agente que después necesite esos datos los lee directamente, sin que booking_agent haya sabido de antemano quién los iba a leer, ni cuándo. Vas a construir ese Blackboard para Reservo —member, la cotización, el booking_id, y un log de quién escribió qué— y vas a correr sobre él a los tres especialistas y al supervisor, todos compartiendo el mismo objeto durante una corrida completa.

Ninguna de las dos formas es "mejor" en abstracto. Este módulo entero es aprender su trade-off real, medido, no solo enunciado.

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

Se mantiene la misma línea de los Módulos 1 a 5: 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 el Blackboard completo: la estructura de datos, el método write que registra quién escribió qué campo y en qué orden (con itertools.count, nunca datetime.now()), las lecturas que cada especialista hace de él, y la corrida de punta a punta donde el supervisor y los tres especialistas comparten un solo objeto. Nada de LangChain ni LangGraph: todo a mano, stdlib, determinista.

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  (completo)
│   → El segundo patrón: orden fijo, sin ninguna decisión de ruteo
├── Módulo 4: Fan-out paralelo y agregación  (completo)
│   → El tercer patrón: sub-tareas independientes, repartidas y agregadas
├── Módulo 5: Handoff y delegación  (completo)
│   → El cuarto patrón: un agente en curso cede el control a mitad de tarea
├── Módulo 6: Estado compartido y el patrón blackboard  ← ESTÁS AQUÍ
│   → El quinto patrón: una pizarra común, en vez de mensajes punto a punto
├── 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 el handoff (M5) — lo reusa como el contraste exacto que le da sentido al blackboard: un handoff es un mensaje dirigido, armado por quien lo envía, pensando en quién lo va a recibir; un blackboard es un estado sin dirección, donde cualquiera que tenga una referencia al objeto puede leer o escribir, sin que el que escribió tuviera que pensar en quién iba a leer después.

Analogía: la pizarra de la sala de guardia, contra la nota que se pasa de mano en mano

Piensa en dos formas de coordinar un turno en una sala de guardia con varios médicos. La primera: cada médico que termina algo relevante para un colega específico le escribe una nota —a mano, con el nombre del colega, con solo el dato que ese colega necesita— y se la entrega en persona. Es preciso: nada llega a quien no lo necesita. Pero exige que quien escribe la nota sepa, en el momento de escribirla, exactamente quién la va a leer y qué necesita saber.

La segunda forma: una pizarra en la pared común de la sala. Cualquier médico que atiende a un paciente escribe ahí lo que hizo —qué diagnosticó, qué medicó, en qué cama—. No sabe quién la va a leer después, ni cuándo. Un médico que entra en su turno de la mañana lee la pizarra entera y encuentra lo que necesita, sin que nadie tuviera que anticiparle nada. Es más simple de coordinar —nadie tiene que decidir a quién dirigir cada dato— pero también más ruidosa: ese médico ve todo lo que está en la pizarra, no solo lo que le importa a él. Y si alguien escribe algo mal, cualquiera que lea después hereda el error, sin saber de dónde vino a menos que exista un registro de quién escribió qué.

Ese es exactamente el trade-off de este módulo. La nota de mano en mano es el handoff del Módulo 5. La pizarra común es el Blackboard que construyes aquí.

El caso que acompaña el módulo: el `Blackboard` de Reservo

Los cuatro módulos anteriores dejaron el registro completo de especialistas —booking_agent, policy_agent, pricing_agent— y el supervisor que los coordina. Este módulo no agrega ningún especialista nuevo: agrega la estructura que los tres, más el supervisor, van a compartir durante una misma corrida.

Blackboard
├── member       -- quién es el socio (lo escribe el supervisor)
├── room          -- qué sala se cotizó/reservó (lo escribe booking_agent)
├── tier          -- básico o pro (lo escribe booking_agent)
├── hours         -- cuántas horas (lo escribe booking_agent)
├── price_cents   -- el precio cotizado, en centavos (lo escribe booking_agent)
├── booking_id    -- el número de confirmación, si ya se reservó (lo escribe booking_agent)
└── log           -- quién escribió qué campo, con qué valor, en qué orden

policy_agent no necesita que nadie le diga el booking_id de la reserva sobre la que está respondiendo — lo lee directamente del Blackboard. pricing_agent puede reusar el tier y las hours que booking_agent ya cotizó, sin que el socio tenga que repetirlos. Y el log —quién escribió cada campo, y cuándo— es lo que permite, después de una corrida, auditar exactamente qué agente puso qué valor: la pieza que un handoff punto a punto, por diseño, no necesita (cada paquete ya dice explícitamente quién lo armó).

El trade-off central del módulo (adelantado, se mide en las lecciones 03 a 06)

	Blackboard (este módulo)	Mensajes punto a punto (Módulo 5)
Coordinar	Simple: escribir un campo, sin pensar en quién lo lee	Exige diseñar, cada vez, qué va en el paquete
Visibilidad	Cualquier agente con acceso al objeto ve todos los campos	Cada agente recibe solo lo que el paquete incluyó
Ruido	Alto: un agente puede leer campos que no necesita para su tarea	Bajo: el paquete se diseñó a la medida del receptor
Auditoría	El log responde "¿quién escribió esto, y cuándo?"	Cada paquete ya lleva su propio remitente, sin necesitar un log aparte
Superficie de error	Un valor mal escrito lo hereda cualquiera que lo lea después	Un error queda contenido al receptor de ESE paquete

La fila de "ruido" tiene nombre propio en el ecosistema: cuánto entra en la ventana de contexto de cada agente —qué tan lleno o vacío llega el system/messages de su próxima llamada— es terreno de context-engineering-guide. Ese ruido no se mide con una unidad abstracta: la lección 06 lo cuenta, campo por campo, comparando lo que un agente ve contra lo que su tarea necesita.

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

Con los cuatro patrones anteriores frescos, el mapa completo queda así:

Un supervisor (M2) decide QUIÉN trabaja, leyendo la petición cada vez.
Un pipeline (M3) fija el ORDEN, sin decidir nada en cada corrida.
Un fan-out (M4) reparte trabajo SIMULTÁNEO entre sub-tareas independientes.
Un handoff (M5) es un agente EN CURSO que cede el control a mitad de tarea, con un paquete dirigido.
Un blackboard (este módulo) es un estado SIN DIRECCIÓN, que cualquier agente de la corrida puede leer o escribir, sin coordinar explícitamente con nadie más.

Y hacia adelante: combinar varios de estos cinco patrones sobre una misma petición compleja —un supervisor que enruta, con algunas sub-tareas en pipeline y otras en fan-out, sobre un blackboard compartido— es el Módulo 7. Este módulo no lo adelanta: construye el blackboard solo, hasta dominarlo, antes de combinarlo con nada.

Dos superficies que este módulo NOMBRA, sin construir

Dos preguntas que un Blackboard real plantea, y que esta guía no resuelve aquí a propósito:

¿Qué pasa si el proceso termina? El Blackboard de este módulo vive en memoria, durante una corrida. Cuando el sistema multi-agente termina de responder, el objeto desaparece con el proceso. Si esos datos necesitaran sobrevivir —que Ana vuelva mañana y el sistema todavía recuerde su reserva de hoy— hace falta un mecanismo de persistencia (un store en disco, leer, escribir, expirar). Ese mecanismo es terreno de agent-memory-and-state-guide; se nombra aquí, nunca se construye.
¿Qué pasa si un agente escribe algo que no debería? Nada en el Blackboard de este módulo impide que un agente —por un bug, o por una instrucción maliciosa incrustada en algo que leyó— escriba un valor falso que otro agente, más adelante en la misma corrida, lea y confíe ciegamente. Esa superficie —un blackboard envenenado— es terreno de agent-security-and-sandboxing-guide; se nombra en la lección 06, nunca se defiende aquí.

Prerequisitos

Conocimiento requerido:

✅ Módulos 1 a 4 completos de esta guía: el criterio de decisión, SPECIALISTS/run_specialist, la distinción entre decidir (supervisor), encadenar (pipeline) y repartir (fan-out).
✅ Módulo 5 completo: la forma de un mensaje punto a punto —el contraste directo de este módulo—.
✅ agent-fundamentals-and-tool-calling-guide: el protocolo tool_use/tool_result, run_agent_parallel, dispatch_parallel.
✅ Python: dataclasses (incluyendo default_factory), itertools.count, ast.literal_eval.

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 ningún framework de orquestación ni una base de datos real — el Blackboard de este módulo es un objeto de Python en memoria, nada más.

Entorno:

✅ Python 3.14.0 con su librería estándar (dataclasses, itertools, ast, concurrent.futures). Nada que instalar.

Roadmap del módulo

Lección 01 — Introducción al módulo (esta)

El patrón blackboard, la analogía de la pizarra común, y el trade-off central frente al handoff (M5).

Lección 02 — Anatomía del Blackboard

Blackboard y WriteLogEntry, ejecutados: la estructura completa, con su primer write.

Lección 03 — Escribiendo en el Blackboard

booking_agent corre de verdad y escribe sus resultados —cotización, booking_id— a medida que los produce, anclado en el tool_result real.

Lección 04 — Leyendo del Blackboard

policy_agent responde una pregunta sobre una reserva sin que nadie se la nombre — leyendo el booking_id directamente del Blackboard.

Lección 05 — El log de escritura

Quién escribió qué, y en qué orden — con una corrección real a mitad de corrida que el log deja visible aunque el estado actual ya la haya tapado.

Lección 06 — El trade-off medido: visibilidad contra aislamiento

Cuánto "ruido" ve cada agente leyendo el Blackboard completo, contra cuánto necesitaría un paquete de handoff diseñado a su medida — contado, campo por campo.

Lección 07 — La corrida completa: supervisor y tres especialistas comparten un `Blackboard`

La pieza central del módulo: una petición compuesta que atraviesa al supervisor y a los tres especialistas, todos leyendo y escribiendo el mismo objeto, con el log final citado.

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

Tres escenarios nuevos, incluyendo el error más común de este patrón —reusar un Blackboard entre dos socios distintos— resuelto con el Blackboard correcto.

Mapa de progresión

Lección 01 (esta)  → El patrón, la analogía, el trade-off adelantado
Lección 02         → Blackboard y WriteLogEntry, el primer write
Lección 03         → booking_agent escribe, anclado en el tool_result real
Lección 04         → policy_agent lee, sin que nadie se lo diga
Lección 05         → El log de escritura, con una corrección real
Lección 06         → El ruido medido, contra un paquete a medida
Lección 07         → La corrida completa: 4 roles, 1 Blackboard
Lección 08         → Proyecto: 3 escenarios, incluido el error típico

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

Qué lograrás en este módulo

Al completar las 8 lecciones, podrás:

Explicar la diferencia de fondo entre un mensaje punto a punto (M5) y un estado compartido sin dirección (este módulo), con un ejemplo de Reservo para cada uno.
Construir Blackboard y WriteLogEntry, con un método write que registra quién escribió cada campo y en qué orden, usando itertools.count — nunca datetime.now().
Escribir al Blackboard anclado en datos reales —el tool_result de una tool, no el texto libre del modelo— con el mismo principio que ya usaste en el Módulo 3.
Leer del Blackboard sin que nadie te lo indique explícitamente — la forma en que un especialista aprovecha lo que otro ya escribió, sin coordinación directa entre ellos.
Auditar una corrida completa con el log — reconstruir quién escribió qué, incluso cuando un valor se corrigió a mitad de camino.
Medir el ruido real que un Blackboard compartido le expone a cada agente, comparado con lo mínimo que un paquete de handoff a medida necesitaría.
Reconocer el error más común del patrón — reusar un Blackboard entre corridas o entre socios distintos — y corregirlo.

El antes y después

ANTES del módulo:
→ "Compartir estado entre agentes" es simplemente "una variable global que todos pueden tocar"
→ Un blackboard es "más simple" que un mensaje dirigido, sin ningún costo a cambio
→ Si un agente necesita un dato, alguien tiene que pasárselo explícitamente, siempre
→ No hay forma de saber, después de una corrida, quién escribió cada valor

DESPUÉS del módulo:
→ Un Blackboard tiene una estructura clara -- campos con nombre, un log de escritura -- no es
  "una variable global sin reglas"
→ Simple de coordinar SÍ, pero con un costo real: ruido, medido en campos que el agente ve y no
  necesita -- nunca gratis
→ Un agente puede leer lo que otro ya escribió, sin que nadie se lo haya "pasado" explícitamente
→ El log responde "quién escribió esto, y cuándo" -- incluso si el valor se corrigió después

Trampas a evitar al cursar este módulo

1. "Un `Blackboard` es solo un diccionario compartido, sin más"

No exactamente. Un diccionario compartido sin log no responde "¿quién puso este valor?" después de una corrida — la parte que hace útil al Blackboard de este módulo, más allá de guardar datos, es que registra cada escritura con su autor y su orden. La lección 02 lo construye completo.

2. "El Blackboard reemplaza al handoff del Módulo 5 — ahora es mejor"

No. Son dos herramientas para preguntas de diseño distintas. Un handoff sigue siendo la opción correcta cuando el dato que se pasa es sensible o específico de una sola transferencia, y quieres control total sobre qué ve el receptor. Un blackboard es mejor cuando varios agentes, potencialmente en momentos distintos, necesitan leer o escribir el mismo estado común, sin que armar un paquete distinto para cada uno valga la pena.

3. "Si un Blackboard es compartido, sirve para compartir estado entre corridas distintas"

No — y este es el error central que el mini-proyecto de la lección 08 corrige con un caso real. Un Blackboard vive una corrida. Reusarlo para la siguiente petición de otro socio —o de otra sesión del mismo socio— mezcla datos que no deberían estar juntos.

4. "El log de escritura es solo un detalle de implementación, no importa para el diseño"

Al revés — sin el log, un Blackboard es una caja negra: no hay forma de depurar por qué un especialista respondió con un dato incorrecto, ni de saber si otro agente sobrescribió algo antes. La lección 05 lo demuestra con una corrección real que el log deja completamente visible.

Cómo trabajar este módulo

Ejecuta la lección 07 tú mismo, con atención al orden de los print. Es la pieza central del módulo — ver, con tus propios ojos, a cuatro roles compartiendo un mismo objeto durante una corrida completa, es lo que hace que el patrón se sienta real y no solo teórico.
No te saltes la lección 06 pensando "ya sé que hay más ruido en un blackboard". La lección cuenta ese ruido, campo por campo, con números — la intuición sin el conteo real es exactamente el tipo de afirmación que esta guía evita.
El mini-proyecto (lección 08) incluye a propósito un escenario "mal hecho". No lo saltees pensando que es solo el escenario "positivo" que importa — reconocer el error de reusar un Blackboard entre socios es tan parte del criterio de este módulo como saber construirlo bien.

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

Total: ~3.2 horas

Evidencia de éxito

Antes de avanzar al Módulo 7 (Orquestando el sistema completo de Reservo), deberías poder:

✅ Explicar, con tus propias palabras, la diferencia entre un mensaje punto a punto (M5) y un Blackboard compartido, con un ejemplo de Reservo para cada uno.
✅ Construir Blackboard y WriteLogEntry, y hacer que tres especialistas y un supervisor compartan el mismo objeto en una corrida.
✅ Leer el log de una corrida y responder, sin ejecutar nada de nuevo, "¿quién escribió el booking_id, y en qué paso?".
✅ Citar de memoria el resultado de la lección 06: cuántos campos de ruido ve cada especialista leyendo el Blackboard completo, contra lo mínimo que necesitaría.
✅ Reconocer y corregir el error de reusar un Blackboard entre corridas o socios distintos.

Resumen

Este módulo construye el quinto patrón de los cinco que anticipó el Módulo 1: estado compartido / blackboard — una pizarra común que cualquier agente de la corrida puede leer o escribir, sin coordinar explícitamente con nadie más.
Regla dura: la decisión de cada agente sigue siendo concepto (claude-sonnet-5); el Blackboard completo —estructura, escritura, lectura, log, la corrida de cuatro roles— se ejecuta de verdad con Python 3.14.
El trade-off central, que se mide con números en las lecciones que siguen: un blackboard es simple de coordinar pero ruidoso (cualquiera ve todo); un mensaje punto a punto (M5) es limpio pero exige diseñar, cada vez, qué va en el paquete.
Dos superficies se nombran sin construirse: la persistencia entre sesiones (agent-memory-and-state-guide) y un blackboard envenenado por un agente que escribe algo que no debería (agent-security-and-sandboxing-guide).
Combinar este patrón con los cuatro anteriores sobre el sistema completo de Reservo es el Módulo 7 — nombrado aquí, construido ahí.

Siguiente lección: 02 — Anatomía del Blackboard. Construimos Blackboard y WriteLogEntry desde cero, y ejecutamos el primer write de la guía.

Recursos adicionales

Anthropic — Multi-agent research system — Un sistema real donde varios sub-agentes leen y escriben resultados compartidos que otros agentes consumen después, sin coordinación punto a punto directa.
Anthropic — Building effective agents — El principio de mantener el estado y el contexto lo más simple posible antes de sumar complejidad de coordinación — el eje del trade-off de este módulo.
Python — dataclasses — El módulo detrás de Blackboard y WriteLogEntry, con default_factory para el campo log.
Python — itertools.count — La fuente determinista de los números de secuencia del log de escritura, la misma disciplina que ya usan production-rag-and-document-ingestion-guide y mcp-deep-dive-guide para IDs.

← AnteriorMini-proyecto: handoffs en Reservo Siguiente →Anatomía del Blackboard