Diseñar un sistema multiagente que no se derrumbe

Los sistemas multiagente fallan de una forma muy predecible: alguien parte un trabajo en cinco agentes porque suena sofisticado, y de pronto tiene cinco lugares por donde se le fuga el contexto, cinco prompts que mantener sincronizados y un bucle donde dos agentes se dan la razón con toda educación hasta que se acaba el presupuesto. Esta guía es el antídoto. Al terminar vas a saber decidir si de verdad necesitas varios agentes, elegir una topología, conectar los agentes con contratos tipados para que se mantengan coordinados y agregar los topes de turnos, los desempates y los presupuestos que evitan que todo se venga abajo bajo su propio peso. Los ejemplos están en TypeScript y el modelo mental es el que usamos al construir ThinkTank AI y Agent Orchestra, pero los principios aplican a cualquier stack.

01 · Decide si de verdad necesitas más de un agente

Lo más sensato por defecto es un solo agente con buenas herramientas. Un agente que puede buscar, leer, escribir y llamar a tu API resuelve la inmensa mayoría del trabajo real, y es muchísimo más fácil de entender, de registrar y de asegurar. Cada agente de más es una nueva frontera de contexto, un nuevo prompt que mantener y una nueva forma de que el sistema se contradiga a sí mismo.

Echa mano de varios agentes solo cuando el trabajo se divide limpiamente por alguna de estas líneas:

• Contexto distinto. Un rol necesita todo el historial de la conversación y la intención del usuario; otro solo necesita una porción acotada y se distraería (o se sesgaría) con el resto. Separarlos mantiene cada prompt enfocado y más barato.
• Herramientas o permisos distintos. Un "investigador" que puede leer la web no debería tener además acceso de escritura a tu base de datos. Dividir los roles te deja acotar las credenciales por agente, la misma lógica de mínimo privilegio de cualquier modelo de amenazas.
• Razonamiento genuinamente independiente. Quieres que un agente no quede anclado al encuadre de otro: un crítico que nunca vio la cadena de pensamiento del proponente, para que pueda atacar la conclusión desde cero.

Si nada de eso aplica, no tienes un problema multiagente. Tienes un solo agente con un prompt que hay que afilar.

02 · Elige una topología antes de escribir código

La forma en que se conectan los agentes determina casi todo lo que viene después: cómo lo logueas, cómo falla, cuánto cuesta. Elige a conciencia. Tres topologías cubren la mayoría de los casos.

Orquestador-trabajador

Un agente planificador decide qué hay que hacer y delega en trabajadores especialistas. El orquestador lleva la meta y el plan; cada trabajador hace una tarea acotada y reporta de vuelta. Es la topología más fácil de entender y de registrar, porque hay un único decisor y un árbol de llamadas claro. Calza directo con los subagentes de Claude Code, y es por donde la mayoría de los equipos debería empezar cuando un solo agente de verdad no da abasto.

Debate / crítica

Dos o más agentes discuten para llegar a una decisión: uno propone, otro ataca, un tercero (o el mismo crítico en una segunda pasada) verifica. El valor no está en la discusión en sí, sino en que el crítico nunca se casó con la propuesta, así que pesca fallas que el proponente no ve. Es la columna vertebral de la deliberación en ThinkTank AI. Es la herramienta correcta cuando una decisión es ambigua y sale cara si te equivocas, y la incorrecta para cualquier cosa que un solo prompt con un chequeo de verificación ya resuelve.

Pipeline

Cada agente se hace cargo de una etapa y le pasa salida estructurada a la siguiente: extraer, luego transformar, luego validar, luego formatear. Lineal, predecible, fácil de testear etapa por etapa. Úsalo cuando el trabajo tiene etapas secuenciales reales y cada una necesita un razonamiento distinto, no cuando solo estás encadenando transformaciones que un solo agente haría de una sola pasada.

03 · Conecta los agentes con contratos tipados, no con estado compartido

Lo único que mata los sistemas multiagente es el estado mutable compartido. Cuando cada agente lee y escribe sobre un mismo bloque grande de contexto, te queda lo peor de todos los mundos: los agentes se pisan las suposiciones entre ellos, el contexto se filtra entre roles que se suponían independientes y ya no hay forma de saber qué agente provocó qué cambio. Depurar se vuelve arqueología.

La solución es darle a cada agente un contrato tipado acotado de lo que recibe y de lo que devuelve. La interfaz de un agente es su tipo de entrada y su tipo de salida; nada más cruza la frontera. Esto no es más que buen diseño de módulos aplicado a componentes no deterministas.

type AgentRole = "planner" | "researcher" | "critic" | "decider"

type AgentTurn = {
  role: AgentRole
  input: string
  output: string
  citations: string[]
}

// Cada agente es una función pura sobre su contrato: in -> out.
// Nada más se comparte. El orquestador es dueño de la transcripción;
// los agentes nunca meten mano en el estado interno de otro.
type Agent = (input: string, ctx: ReadonlyContext) => Promise<AgentTurn>

Dos reglas hacen que esto se sostenga en la práctica:

1. El contexto que recibe un agente es de solo lectura. Los agentes devuelven su resultado; el orquestador decide qué fusionar en la transcripción compartida, si es que algo. Ningún agente muta el contexto que otro está leyendo.
2. Pasa lo mínimo. Un crítico no necesita todo el rastro de razonamiento del planificador; muchas veces no debería verlo, porque se ancla en el mismo encuadre y la independencia que buscabas se te evapora. Dale a cada agente la porción que su rol requiere y nada más.

Esta disciplina, de paso, te regala la traza. Como cada turno es un registro tipado, la transcripción de una corrida es apenas un arreglo de valores «AgentTurn» que puedes registrar, reproducir y verificar en tus evals.

04 · Detén el bucle: topes de turnos, desempates y un decisor

Aquí va la falla que sorprende a todos la primera vez: los agentes se quedan en bucle dándose la razón hasta el infinito. Dos agentes a los que les pides llegar a un consenso van a seguir encontrando pequeños matices en los que coincidir, quemando tokens y latencia mientras no convergen en nada accionable. Sin un límite, un debate no termina: solo se pone cada vez más caro.

Esto se previene con tres mecanismos, ninguno opcional en producción:

• Un tope duro de turnos. Fija un máximo de intercambios, normalmente dos o tres para un debate, y hazlo cumplir en el código, no en el prompt. El modelo no va a contar sus propios turnos de forma confiable.
• Un desempate. Decide de antemano qué pasa cuando los agentes no convergen. Por defecto, la opción más segura; por defecto, el humano; por defecto, "sin decisión", pero decídelo, para que el sistema tenga una salida determinista.
• Un decisor. Un solo agente (o una regla determinista) que lee la transcripción una vez y cierra. Un decisor que lee y cierra siempre le gana al consenso infinito, porque su trabajo es terminar la deliberación, no estirarla.

const MAX_TURNS = 3

async function deliberar(pregunta: string): Promise<Decision> {
  const transcripcion: AgentTurn[] = []

  for (let turno = 0; turno < MAX_TURNS; turno++) {
    const propuesta = await proponer(pregunta, transcripcion)
    const critica = await criticar(pregunta, propuesta) // nunca ve el razonamiento del proponente
    transcripcion.push(propuesta, critica)
    if (critica.output === "sin objeciones") break
  }

  // El decisor lee la transcripción UNA VEZ y cierra. No hay más rondas.
  return decidir(pregunta, transcripcion)
}

Fíjate en que el decisor está fuera del bucle. El trabajo del bucle es sacar el desacuerdo a la luz; el del decisor es ponerle fin. Mezclar esos dos roles, dejar que lo mismo que discute decida también cuándo parar, es justo la receta para terminar con un panel que nunca aterriza.

05 · Ponle presupuesto a cada corrida y contén el fallo parcial

Una corrida multiagente es un árbol de llamadas al modelo, y un árbol se abre en abanico. Una pregunta ambigua puede generar propuestas, cada una genera críticas y cada una genera una pasada de verificación, hasta que una sola petición del usuario se convierte sin hacer ruido en treinta llamadas al modelo antes de que nadie note la factura. Acota el gasto de forma explícita.

• Presupuestos de tokens y de tiempo real por corrida. Envuelve toda la deliberación en un techo. Cuando lo alcances, detente y devuelve la mejor respuesta verificada que tengas, o escala; no sigas gastando al vacío.
• Timeouts por agente. Toda llamada al modelo se puede colgar. Decide qué pasa cuando un trabajador hace timeout antes de que te toque resolverlo a las 3 de la mañana: sigue con los candidatos que tengas y registra el hueco. Un panel de dos sobrevivientes le gana a una petición que se queda colgada para siempre.
• Escrituras idempotentes. Si un agente llama a una herramienta de escritura y el turno se reintenta, esa escritura puede dispararse dos veces. Haz idempotentes las operaciones destructivas (acepta una clave que provea el cliente o revisa el estado antes de actuar) para que un reintento no le cobre doble a un cliente.

Un ejemplo concreto para aterrizarlo. Supongamos que estás construyendo una funcionalidad de revisión de contratos. Un solo agente lee la cláusula y marca los riesgos: está bien para una primera pasada. Pero el riesgo es real (una cláusula que se te escapa le cuesta caro a un cliente), así que agregas un debate: un proponente lista los riesgos, un crítico (que nunca ve el razonamiento del proponente) argumenta que cada riesgo marcado en realidad es inofensivo y saca a la luz los riesgos que el proponente no vio, y un decisor lee a ambos y produce la lista final. Limitas el debate a dos rondas, le pones a toda la corrida un presupuesto de, digamos, un techo fijo de tokens y veinte segundos, y si el decisor no puede verificar una lista con confianza, la escala a un revisor humano en lugar de adivinar. Esa rama de escalación no es un plan B: es la funcionalidad. Un honesto "no pude verificar esta cláusula" manda el caso difícil al único lugar que se puede hacer cargo de él.

El hilo conductor de las cinco secciones es la mesura. Los sistemas multiagente valen la pena cuando el trabajo se divide en roles con nombre que necesitan otro contexto, otras herramientas u otro razonamiento, y solo entonces. Empieza con un agente, dale buenas herramientas y divídelo solo cuando puedas decir el segundo rol en voz alta. Cuando lo dividas, acota las fronteras con contratos, limita el bucle, nombra un decisor y ponle presupuesto a la corrida. Hazlo y tu panel se coordina en vez de discutir en círculos; sáltatelo y habrás construido una forma cara de que un modelo se dé la razón a sí mismo.