Orquestación multiagente

Qué cubre esta sesión

Un solo agent tiene un techo. Pídele a uno "escribe esto, luego critícalo, luego reescríbelo, y también verifica los datos, y mantén el tono amigable" y las instrucciones empiezan a pelearse entre sí — el modelo solo puede sostener cierta cantidad de roles a la vez. La respuesta multiagente es dividir el trabajo: dale a cada rol su propio agent con su propio prompt estrecho, y pasa el trabajo entre ellos. Un writer que solo escribe y un critic que solo critica le ganan a un solo agent haciendo ambos, por la misma razón por la que un equipo le gana a una sola persona usando todos los sombreros.

Lo importante de ver esta semana es que la orquestación no es un framework — es control flow. Pasar la salida de un agent a otro es una llamada a función. Un router es un if sobre una clasificación. Un debate son tres llamadas y una comparación. Los frameworks te dan retries, tracing, y paralelismo, que son comodidades reales, pero el núcleo es Python que puedes leer, y construirlo a mano es como aprendes qué están haciendo de verdad los frameworks.

OpenAI

Cada agent es un system prompt con un solo trabajo. La estrechez es toda la ventaja — un rol que puedes enunciar en una oración es un rol que el modelo desempeña bien.

# Each agent is just a system prompt with one job. The narrowness is the point —
# a role you can state in a sentence is a role the model does well.
WRITER = "You are a concise technical writer. Write a short, clear explanation for a beginner."
CRITIC = ("You are a sharp editor. List 2-3 specific, actionable problems with the draft "
          "(accuracy, clarity, or missing context). If it's already excellent, say so briefly.")

La orquestación es solo Python moviendo texto entre ellos: draft, critica el draft, reescribe atendiendo la crítica. Puedes ver exactamente qué recibió cada agent, que es por lo que la orquestación hecha a mano es más fácil de debuggear que el paso de mensajes escondido de un framework.

# Orchestration is just Python passing outputs between agents. Here: draft, then
# critique the draft, then rewrite addressing the critique. No framework — the
# control flow IS the orchestration, and you can see exactly what each agent saw.
def collaborate(task: str) -> tuple[str, str, str]:
    draft = agent(WRITER, task)
    critique = agent(CRITIC, f"TASK: {task}\n\nDRAFT:\n{draft}")
    final = agent(WRITER, f"TASK: {task}\n\nYour draft was critiqued:\n{critique}\n\n"
                          f"Rewrite the explanation, fixing every issue raised.")
    return draft, critique, final

Gemini

Mismo equipo, mismo control flow, las llamadas de Gemini. El patrón no depende del proveedor porque el patrón es solo composición.

def collaborate(task: str) -> tuple[str, str, str]:
    draft = agent(WRITER, task)
    critique = agent(CRITIC, f"TASK: {task}\n\nDRAFT:\n{draft}")
    final = agent(WRITER, f"TASK: {task}\n\nYour draft was critiqued:\n{critique}\n\n"
                          f"Rewrite the explanation, fixing every issue raised.")
    return draft, critique, final

Una palabra de realismo antes de que construyas un swarm. Más agents significa más llamadas, más latencia, y más costo — un pipeline de tres agents es tres veces la cuenta de API de uno — así que echa mano de múltiples agents cuando la ganancia de calidad lo valga, no por defecto. Y los sistemas multiagente fallan de una forma nueva: agents que se hablan sin escucharse, un critic que el writer ignora, un router que manda todo a "general". El mismo harness de evaluación de la semana 15 es como atrapas eso — califica la salida final, no tu fe en la arquitectura.

Ponlo a trabajar

Tres apps de docker-compose bajo code/showcase/<slug>/, cada una una forma clásica multiagente. Misma rutina: bash bootstrap-secrets.sh, docker compose up --build, http://localhost:3000.

Showcase 1 — Writer + critic

El patrón de pipeline: draft, critica, revisa, con las tres etapas mostradas para que veas la mejora que compró el critic. Este es el movimiento multiagente que más confiablemente rinde — un critic dedicado atrapa lo que un writer que se autocritica se convence de dejar pasar.

Showcase 2 — Router

El patrón de routing: un agent clasificador barato elige a un especialista, y el especialista responde. Es como escalas un bot de soporte o un asistente a través de dominios sin un solo prompt inflado que es mediocre en todo. La respuesta nombra al especialista para que veas la decisión de routing.

Showcase 3 — Debate

El patrón adversarial: a favor, en contra, y un juez. El desacuerdo es el punto — dos agents empujando en direcciones opuestas sacan a la luz tradeoffs que un solo agent suaviza, y el juez fuerza una decisión en lugar de un encogimiento de hombros.

Pipeline, router, debate — tres formas de componer agents, todas solo control flow sobre prompts de un solo trabajo.

Córrelo

El README de esta carpeta tiene la versión de Python, la línea de instalación, las dos variables de entorno, y los comandos exactos. Las keys vienen del .env sin trackear en la raíz del curso. Los scripts básicos imprimen cada etapa para que veas a los agents hacer el relevo.

Lo que te llevas

Cuando un agent pega en su techo, divide los roles: la orquestación multiagente es solo agents enfocados de un solo trabajo compuestos con control flow simple — un pipeline son llamadas a función, un router es un if, un debate son tres llamadas y una comparación, y los frameworks solo agregan comodidad encima de eso. Los patrones que vale la pena conocer son el pipeline (draft/critica/revisa), el router (clasifica luego despacha a un especialista), y el panel adversarial (a favor/en contra/juez). Paga por los agents extra solo cuando la calidad valga las llamadas y la latencia extra, y evalúa la salida final en lugar de confiar en la arquitectura, porque el nuevo modo de falla son los agents comunicándose mal. La próxima semana juntamos el curso entero en una sola aplicación de proyecto final.