Prompt orquestador-enrutador: descompón y enruta en vez de una sola llamada sobrecargada

Un prompt que "lo hace todo" parece eficiente y se va pudriendo en silencio a medida que la tarea crece. Le metes la especificación, el código, los datos, tres restricciones medio inconexas y una lista de herramientas en una sola llamada, y el modelo tiene que razonar sobre todo eso de golpe. La calidad se cae en el medio de los contextos largos, las instrucciones compiten entre sí, y un error en el primer paso contamina todos los pasos que vienen después. El patrón detrás de Agent Orchestra tiene la forma contraria: un orquestador ligero que no carga con ningún conocimiento de dominio, descompone la petición y manda cada pieza a un especialista que solo ve la parte que le toca. Esta página te entrega ese prompt de orquestador, listo para pegar, más las variables que tienes que rellenar, variantes para trabajo secuencial y paralelo, un esquema de cómo conectarlo y los modos de fallo que, sin que te des cuenta, vuelven a convertir un enrutador en un bloque monolítico.

01 · Por qué se degrada un solo prompt grande

Querer mantener todo en una sola llamada es razonable: es más simple, no tienes que armar nada alrededor, y las tareas pequeñas de verdad no necesitan más. El problema aparece cuando escalas, y es algo mecánico, no una cuestión de pulir el prompt.

• Dilución del contexto. Un modelo presta más atención al inicio y al final de su contexto. Entierra una restricción clave en medio de un documento de 30k tokens y va a quedar subponderada sin que te enteres. Más contexto no es más atención.
• Instrucciones que compiten. "Sé conciso", "explica tu razonamiento", "respeta este esquema" y "usa estas herramientas", todas en el mismo prompt, tiran cada una para su lado. El modelo termina a medio camino entre todas y no cumple ninguna del todo.
• Propagación del error. En una sola cadena de razonamiento larga, una suposición equivocada en el primer movimiento se arrastra en silencio hacia todo lo que viene después. No hay punto de control, no hay una frontera limpia donde una instancia nueva pudiera atraparla.
• Cero reutilización. Un monolito está hecho a la medida de una sola tarea. No puedes reutilizar la parte de "escribe el SQL" en otra petición sin arrastrar todo lo demás contigo.

La descomposición arregla las cuatro cosas a la vez. Cada especialista razona sobre un contexto pequeño y enfocado. Las instrucciones no chocan porque cada rol tiene un solo trabajo. La frontera entre subtareas es un punto de control natural. Y un especialista que defines una vez lo reutilizas en cada petición que lo necesite.

02 · El prompt del orquestador

Aquí tienes la plantilla. Es deliberadamente estricta en una cosa: el orquestador no resuelve la tarea. Planifica y enruta, emite un plan estructurado y se detiene. Pégala como system prompt de tu rol planificador, rellena el registro de especialistas y pásale la petición del usuario como primer mensaje.

Eres un ORQUESTADOR. NO resuelves la tarea tú. Planificas y enrutas.
Si en algún momento empiezas a producir la solución real, detente — ese no es tu trabajo.

ESPECIALISTAS DISPONIBLES (solo puedes enrutar a estos):
{{specialists}}
  # un bloque por especialista, exactamente:
  # - id: <id-corto>
  #   scope: <una línea — en qué es bueno y qué NO debe hacer>
  #   tools: <las herramientas/datos a los que puede acceder>
  #   accepts: <la forma de entrada que espera>

Sigue estos pasos:

1. REPLANTEA la petición en una frase para anclar tu descomposición a ella.

2. DESCOMPÓN en las subtareas INDEPENDIENTES más pequeñas. Una subtarea es
   independiente si, en principio, podrías entregársela a alguien que no ha
   visto las demás. No partas trabajo que un único especialista solo puede
   hacer coherente en una sola pasada.

3. Para cada subtarea, ASIGNA exactamente UN especialista por id y di en una
   línea POR QUÉ ese especialista (qué parte de su scope encaja). Una subtarea,
   un dueño.

4. Declara DEPENDENCIAS: para cada subtarea, lista los ids de las subtareas que
   deben terminar antes de que pueda empezar. Las subtareas sin dependencias
   pueden correr en paralelo.

5. Indica los INSUMOS que necesita cada subtarea: qué recibe y de quién (del
   usuario, o de la salida de una subtarea anterior por su id).

Si ningún especialista encaja en una subtarea, ponla bajo UNROUTED con una
razón en una línea. NO fuerces una mala asignación. Una subtarea sin enrutar
es un resultado real y aceptable.

DEVUELVE solo esto, como objeto JSON, nada más:
{
  "restatement": "<una frase>",
  "plan": [
    {
      "id": "s1",
      "subtask": "<qué hacer>",
      "specialist": "<id-del-especialista>",
      "why": "<una línea>",
      "depends_on": [],
      "inputs": "<qué necesita y de dónde>"
    }
  ],
  "unrouted": [ { "subtask": "<...>", "reason": "<...>" } ]
}

No escribas ninguna solución, código ni prosa fuera de este JSON.

Tres decisiones cargan con todo el peso:

• "NO resuelves la tarea tú", repetido, más la instrucción de detenerse. Sin eso, el orquestador "ayuda" y escribe el SQL que se suponía que debía enrutar. Esa frontera es justo de lo que se trata todo.
• La salida solo-JSON. Un plan que puedes parsear es un plan que tu runtime puede ejecutar: recorre plan, resuelve depends_on y despacha cada subtarea al especialista que le toca. Los planes en prosa te obligan a volver a interpretar la intención a mano en el código.
• La válvula de escape «unrouted». Sin una forma válida de decir "no encaja nada", el modelo se inventa una asignación forzada. Sacar el hueco a la luz es más útil que un enrutamiento equivocado dicho con toda seguridad.

03 · Rellenar el registro de especialistas

En el registro es donde vive casi toda la calidad. El orquestador solo puede enrutar a roles que conoce, y enruta bien únicamente cuando el scope de cada rol está bien afilado. Un registro vago produce planes vagos.

Cómo luce un buen bloque de especialista

Cada entrada necesita cuatro cosas: un id estable, un scope que diga tanto lo que hace como lo que no debe hacer, las tools a las que llega y la forma de entrada que espera. La mitad negativa del scope importa tanto como la positiva, es lo que evita que el orquestador le cargue de más a un especialista muy solicitado.

- id: sql-author
  scope: escribe y explica SQL de solo lectura contra el esquema de analítica;
         NO debe correr migraciones, escribir datos ni diseñar esquema
  tools: postgres-read-replica (solo lectura), schema-docs
  accepts: una pregunta en lenguaje natural + los nombres de tablas relevantes

- id: api-integrator
  scope: escribe código cliente que llama APIs HTTP externas; NO debe guardar
         secretos en el código ni inventar endpoints que no estén en el contrato
  tools: http-fetch (en sandbox), la spec OpenAPI del servicio destino
  accepts: un contrato de API + el comportamiento a implementar

- id: writer
  scope: convierte un resultado terminado en prosa clara para una audiencia dada;
         NO debe hacer análisis ni inventar datos que no estén en su entrada
  tools: ninguna
  accepts: un artefacto terminado + la audiencia destino

Mantén tonto al orquestador a propósito

Aguanta las ganas de darle al orquestador conocimiento de dominio o herramientas propias. En el momento en que pueda leer la base de datos, le va a entrar la tentación de responder la pregunta en lugar de enrutarla. Un enrutador sin herramientas, físicamente, no puede resolver la tarea, y esa restricción es una virtud, no un estorbo. Deja toda la capacidad en los especialistas; deja todo el criterio sobre quién hace qué en el orquestador.

04 · Conectar el plan a un runtime

El orquestador emite un plan; tu código lo ejecuta. El loop es pequeño: parsea el JSON, corre las subtareas cuyas dependencias ya están satisfechas (en paralelo cuando hay más de una), pásale a cada especialista solo los insumos que tiene declarados y repite hasta terminar el plan. Lo clave: cada especialista corre en su propia llamada con su propio contexto, ese aislamiento es justo lo que te da todo el patrón.

import Anthropic from "@anthropic-ai/sdk"

const client = new Anthropic()

type Step = {
  id: string
  subtask: string
  specialist: string
  depends_on: string[]
  inputs: string
}

// 1) Plan: el orquestador corre barato — solo enruta, nunca razona hondo.
async function plan(request: string): Promise<Step[]> {
  const res = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 2000,
    system: ORCHESTRATOR_PROMPT, // template de la sección 02, con el registro lleno
    messages: [{ role: "user", content: request }],
  })
  const text = res.content.find((b) => b.type === "text")?.text ?? "{}"
  return JSON.parse(text).plan as Step[]
}

// 2) Ejecutar: cada especialista recibe SOLO sus insumos, en su propio contexto.
async function run(steps: Step[], outputs: Record<string, string> = {}) {
  const done = new Set(Object.keys(outputs))
  while (done.size < steps.length) {
    const ready = steps.filter(
      (s) => !done.has(s.id) && s.depends_on.every((d) => done.has(d)),
    )
    if (ready.length === 0) throw new Error("ciclo de dependencias en el plan")
    await Promise.all(
      ready.map(async (s) => {
        outputs[s.id] = await runSpecialist(s, outputs) // una llamada por rol
        done.add(s.id)
      }),
    )
  }
  return outputs
}

Un ajuste que vale la pena: corre el orquestador barato (un modelo de gama media, sin extended thinking) porque enrutar es una decisión superficial, y gasta tu presupuesto de tokens en los especialistas, que es donde pasa el trabajo de verdad. La misma lógica que en un equipo: el que despacha es rápido y barato; donde pagas es en los expertos.

05 · Variantes

El esqueleto es fijo; lo amoldas según el uso.

Pipeline estrictamente secuencial. Cuando cada paso alimenta al siguiente (extraer → transformar → resumir), olvídate del paralelismo y deja que depends_on forme una línea recta. Lo valioso aquí no es la concurrencia, es el traspaso limpio, donde cada etapa recibe un artefacto terminado y no un revoltijo en bruto con instrucciones encima.

Fan-out / fan-in (map-reduce). Descompón en N subtareas independientes del mismo tipo, revisar diez archivos, resumir doce documentos, enruta cada una al mismo id de especialista y luego agrega una subtarea final de síntesis que dependa de las N. El trabajo del orquestador es solo armar la forma de dependencias correcta; tu runtime las abre en abanico y la síntesis las vuelve a juntar.

Con un verificador en el loop. Agrega un especialista verificador y enruta una subtarea de verificación que dependa del productor. Cuando el veredicto sale negativo, tu runtime devuelve los defectos para una reescritura. (Esto lo combinamos con el prompt de verificador adversarial en ThinkTank AI, el orquestador enruta el trabajo, el verificador ataca el resultado.)

Enrutamiento de decisión / negociación (lo que armamos en Proyección): los especialistas pasan a ser perspectivas (el analista de tu lado, el modelo del oponente, el que revisa los riesgos) y el orquestador enruta la misma decisión a cada uno, y después a una síntesis que los pondera. El mismo esqueleto de planificar-y-enrutar, pero apuntado a una deliberación en vez de a una construcción.

06 · Trampas que convierten un enrutador de vuelta en un bloque

Cada una de estas es fácil de pasar por alto y cada una reconstruye en silencio el monolito que querías evitar.

1. El orquestador termina resolviendo la tarea igual. El fallo más común. "Ayuda" escribiendo la respuesta en vez del plan. Mantén la línea con el repetido "NO la resuelvas tú", el formato solo-JSON y, lo que de verdad lo frena, no darle al orquestador ni herramientas ni contexto de dominio con qué resolver.

2. Sobre-descomposición. Partir un trabajo coherente en cinco subtareas diminutas agrega sobrecarga de traspasos y pierde el contexto que lo hacía coherente. Si un solo especialista haría una subtarea mejor en una pasada que tres subtareas en tres, no la partas. La unidad independiente más pequeña, no la unidad más pequeña posible.

3. Filtrar el contexto completo a cada especialista. Si le pasas la petición original completa a cada rol "por si acaso", reconstruiste el problema del prompt grande dentro de cada llamada. Pasa solo los insumos declarados. La gracia de enrutar es que el autor del SQL nunca vea las instrucciones de redacción.

4. Un registro con solapes. Dos especialistas que podrían encargarse de la misma subtarea vuelven el enrutamiento no determinista: la misma petición se enruta distinto de una ejecución a otra. Afila los scopes hasta que cada subtarea tenga un dueño evidente.

5. Confiar en el plan como si fuera código. El plan es salida del modelo, no un contrato. Valídalo: que cada id de especialista exista, que no haya ciclos de dependencias, que ninguna subtarea dependa de sí misma. Un plan que referencia a un especialista que borraste va a fallar al despachar si no chequeas antes.

6. Enrutar tareas triviales. Si toda la petición entra en un prompt enfocado, un enrutador es pura sobrecarga: una llamada de más, latencia de más, más superficie donde algo puede fallar. Echa mano del orquestador cuando los sub-trabajos sean realmente distintos, no por defecto.

Córrelo con disciplina y la ganancia no es que una respuesta suelta se vuelva más inteligente. Es que la calidad deja de derrumbarse a medida que crece el alcance, porque nadie razona nunca sobre todo a la vez. El orquestador te da un plan parseable sobre el que ramificar, los especialistas te dan trabajo enfocado, y la frontera entre ellos es justo la estructura que deja crecer al sistema sin que se desarme.