Underpass Choreographer es el motor de deliberación de la plataforma Underpass: convierte una reunión multiagente en una ceremonia declarativa, observable y operable sobre Kubernetes. Es open source.
Los agentes resuelven tareas: reciben contexto, usan herramientas, coordinan pasos y entregan un resultado.
Muchas veces, eso es justo lo que necesitamos.
La exigencia cambia cuando ese resultado se usa para decidir algo que después habrá que defender.
Si un sistema recomienda una arquitectura, prioriza trabajo, propone una operación o diseña un plan técnico, el resultado final no basta. Necesitamos saber cómo se llegó ahí.
Qué alternativas se consideraron. Quién las criticó. Qué cambió después de la crítica. Qué comprobó el validador. Qué puntuación recibió cada propuesta. Por qué una opción ganó y las demás no.
Ahí empieza la decisión: no la última frase del agente, sino el proceso por el que una opción gana frente a otras.
Choreographer nace de esa idea: una decisión multiagente no debería ser una caja negra ni una conversación efímera. Debería tener forma de ceremonia.
Una ceremonia tiene roles, fases, reglas y un rastro. Se puede declarar. Se puede ejecutar. Se puede observar. Se puede revisar después.
La decisión como artefacto
Gran parte del ecosistema de agentes se ha construido alrededor de una pregunta muy práctica:
¿cómo consigo que un modelo haga cosas?
De ahí salen bucles de tool-calling, cadenas de prompts, grafos de ejecución, memorias y conectores. Todo eso es útil. Pero cuando el sistema empieza a tomar decisiones que importan, aparece otra pregunta:
¿cómo defendemos lo que acaba de decidir?
Guardar solo el resultado final deja fuera lo más valioso: la historia de la elección. Necesitamos poder abrir esa decisión y entender cómo se formó.
Qué caminos se descartaron. Qué objeciones aparecieron. Qué propuesta sobrevivió a una revisión por pares. Qué criterio usó el juez. Dónde hubo empate. Dónde ganó una opción por calidad y no por orden de llegada.
En Choreographer, esa historia no queda fuera del sistema. Forma parte del modelo.
Una respuesta es texto.
Una decisión tiene alternativas, criterios, revisión y rastro.
Ceremonias, no chats
En Choreographer, una decisión compleja se modela como una ceremonia.
No es un chat con varios agentes improvisando. La ceremonia tiene una forma explícita: participantes, pasos, roles, condiciones de avance y resultado esperado.
El motor de ceremonias de Choreographer hace posible esa forma de trabajar. No es una reunión cerrada ni una secuencia fija de prompts. Es un sistema flexible para definir ceremonias por YAML: estados, pasos, roles, especialistas, número de participantes, rondas y condiciones de cierre.
El mismo motor puede ejecutar una revisión de arquitectura, una planificación de producto, una investigación de incidente o una deliberación técnica con varios especialistas. Cambia el YAML, cambia la ceremonia. El entorno de ejecución sigue siendo el mismo.
El YAML no es decoración. Es el contrato de cómo se va a decidir.
Un equipo puede revisar ese contrato antes de ejecutarlo. Puede cambiar fases. Puede ajustar especialistas. Puede hacer que una decisión de arquitectura pase primero por un rol de seguridad, después por un rol de coste, y finalmente por un responsable de programa.
La forma de decidir deja de estar enterrada dentro de una función o de un script. Pasa a ser una pieza que se puede leer, discutir, versionar y evolucionar.
Un fragmento recortado de la ceremonia real que veremos después (mismo esquema que ejecuta el motor; prompts abreviados):
states:
- id: BRIEFING
initial: true
- id: DESIGN
# … RISK_REVIEW, BUILD_PLAN …
- id: CLOSED
terminal: true
transitions:
- from: BRIEFING
to: DESIGN
trigger: mission_framed
guards:
- frame_mission_completed
steps:
- id: frame_mission
state: BRIEFING
handler: facilitation_prompt
config:
agent_kind: vllm
num_agents: 3
see_prior: false
prompt: "Eres el MISSION OWNER. Encuadra la misión: objetivo, criterios de éxito y la restricción innegociable…"
- id: design_approach
state: DESIGN
handler: progress_prompt
config:
agent_kind: vllm
num_agents: 3
see_prior: true
prompt: "Eres el SYSTEMS ARCHITECT. Propón la arquitectura y defiende tus dos decisiones más duras…"
Ese see_prior: true es el detalle que hace que la reunión no se reinicie en cada paso: el arquitecto lee lo que dejó el encuadre de misión. Y la transición con guard es la condición de avance: no se pasa a DESIGN hasta que el encuadre se completa.
El ejemplo es pequeño, pero enseña la idea central: cuando el modo de decidir se puede leer, también se puede discutir, versionar y gobernar.
La unidad mínima: deliberate
Debajo de una ceremonia hay una primitiva más pequeña: deliberate.
deliberate es la pieza mínima donde se decide algo. Recibe una tarea, un grupo de agentes, unas restricciones y una política de validación. Ese grupo de agentes es el council de esa deliberación: varios especialistas trabajando sobre el mismo problema desde perspectivas distintas.
A partir de ahí, Choreographer ejecuta un proceso explícito:
- Los agentes proponen.
- Otros agentes del mismo council critican esas propuestas.
- Las propuestas se revisan.
- Los validadores comprueban si cumplen los criterios definidos.
- Un juez puede puntuar la calidad relativa de cada propuesta.
- Se elige un ganador.
Un validador es cualquier comprobación que decide si una propuesta pasa un criterio: que no esté vacía, que cumpla un contrato JSON, que respete un esquema, o que pase una evaluación de un juez LLM.
El juez es un validador especial. No solo dice "pasa o no pasa"; también puede emitir una puntuación de calidad.
Y el proceso tampoco es un voto por mayoría: no se trata de preguntar a tres modelos y quedarse con la respuesta más repetida.
La diferencia es que la crítica forma parte del proceso, no de un comentario posterior. Cada propuesta entra en contacto con otra perspectiva antes de competir. La revisión queda ligada a la crítica. El juez no aparece como magia al final: emite un veredicto que se puede registrar, puntuar y observar.
En una ceremonia larga, cada paso puede ser una deliberación completa. El resultado ganador de una fase alimenta la siguiente. Así una reunión no se reinicia en cada paso: acumula contexto.
Una decisión técnica abierta
Probamos una reunión de diseño: planificar un dron de menos de 4.500 dólares, por debajo de 25 kg de MTOW, capaz de hacer una misión de unos 45 minutos para detectar árboles enfermos en copas mixtas.
En esta prueba concreta, todas las llamadas al modelo corrieron localmente con Gemma 4 servido por vLLM. Agentes, juez y deliberación no dependían de ningún proveedor en la nube.
Este tipo de decisión obliga a negociar. Más autonomía puede empeorar la seguridad eléctrica. Más sensor puede romper el presupuesto o el peso. Más procesamiento a bordo puede mejorar la precisión, pero también consumir energía, dinero y margen térmico.
La ceremonia se dividió en cuatro pasos:
-
frame_mission: encuadrar la misión y sus restricciones. -
design_approach: proponer una arquitectura técnica. -
review_risks: atacar los riesgos de seguridad y fiabilidad. -
build_plan: sintetizar una planificación final.
Cada paso fue una deliberación con tres propuestas. En total, la reunión produjo doce propuestas evaluadas por el juez.
No fue instantánea: duró unos 25 minutos. Ese dato también importa. Una decisión multiagente real consume tiempo, tokens, llamadas a proveedores y ciclos de validación. Si no puedes observar ese coste, no puedes operarla.
El punto no era conseguir un texto bonito sobre un dron. El punto era ver si el sistema podía sostener una estructura de decisión.
El primer paso fijó el contrato de misión. El segundo exploró la arquitectura. El tercero cambió el centro de gravedad de la conversación: el riesgo crítico no era solo la precisión del sensor o el coste, sino la estabilidad eléctrica bajo viento y lluvia. El revisor de seguridad cuestionó una arquitectura basada en Li-ion pura por riesgo de voltage sag, brown-out y pérdida del dron.
En la síntesis final, el plan ganador aceptó esa crítica: priorizó estabilidad operativa frente a autonomía teórica e incorporó una topología híbrida Li-ion + buffer LiPo.
La decisión es interesante no porque sea perfecta, sino porque se puede abrir.
Al abrirla, aparecen las propuestas iniciales, las revisiones, los veredictos del juez, las puntuaciones y el ganador de cada paso. También se ve que la fase de síntesis fue más lenta porque estaba reconciliando restricciones acumuladas. El juez evaluó doce propuestas y la ceremonia terminó correctamente.
La decisión no desapareció dentro de una respuesta final. Quedó como un artefacto observable.
Cómo explorar una decisión
Aquí la observabilidad tiene una función muy concreta: permitir que una decisión se pueda leer después.
Una ceremonia completa puede verse como una traza distribuida. Cada paso de deliberación aparece como un span. Y el debate no queda perdido en logs sin estructura: queda registrado como eventos del span.
En una deliberación real puedes ver eventos como:
proposal draftedpeer critique and revisionvalidator verdictproposal scoreddeliberation completed
Con esa estructura, abrir Grafana cambia de significado.
No estás mirando solamente latencia, errores o throughput. Estás leyendo cómo decidió el sistema.
La reunión deja un rastro navegable. Puedes abrir una ceremonia reciente y entrar en un span deliberate.
Desde ahí puedes leer las propuestas, ver qué críticas recibieron, revisar el veredicto del juez y comprobar qué propuesta ganó.
La traza se convierte en el acta técnica de la decisión.
No es replay determinista de ejecución. No significa que puedas volver a ejecutar el mundo externo y obtener exactamente el mismo razonamiento. Significa algo más concreto y defendible: puedes reabrir una decisión pasada por trace ID y recorrerla paso a paso.
Para equipos de plataforma esto importa. Un sistema multiagente en producción no puede limitarse a decir "el modelo respondió esto". Tiene que poder responder preguntas de operación y gobierno:
- Qué pasó en esta decisión.
- Qué agente propuso la opción ganadora.
- Qué crítica cambió la propuesta.
- Qué puntuación recibió.
- Cuánto tardó cada deliberación.
- Si hubo un juez con baja confianza.
Ese tipo de preguntas no se contestan bien con un log plano. Se contestan mejor con una traza.
Medir si la decisión funciona
Leer una reunión pasada es una parte del problema. La otra es saber si el proceso de decisión está funcionando bien a lo largo del tiempo.
Ahí entran las métricas.
Choreographer no solo emite trazas con el debate. También expone señales operativas sobre la calidad y el coste del proceso:
- duración de deliberaciones
- puntuación de las propuestas ganadoras
- latencia del juez
- distribución de puntuaciones del juez
- errores del juez clasificados por tipo
- tokens consumidos por juez y proveedores
- latencia y llamadas activas por proveedor
- uso del pool de Postgres
- resultado y duración de ceremonias
- duración y estado de cada paso de ceremonia
- latencia y errores al publicar eventos en NATS
En la prueba del dron, las métricas reflejaron el proceso completo: cuatro deliberaciones, doce generaciones, doce críticas, doce revisiones, doce puntuaciones del juez y una ceremonia finalizada.
También enseñan el cuello de botella mientras está ocurriendo. Con la ceremonia aún abierta, el gauge de llamadas activas por proveedor responde la pregunta que de otro modo es pura adivinación —¿está roto el sistema, se perdió la traza, falló el juez?— con algo mucho más concreto: queda una llamada larga del modelo en curso.
Ahí está el valor operativo. La observabilidad no solo sirve para reconstruir una historia después. Sirve para operar el sistema mientras decide.
La métrica más interesante no es solo "qué puntuación dio el juez". Es si el juez cambia algo.
Si un juez LLM puntúa propuestas pero casi nunca cambia el ganador frente a una referencia estructural, quizá está añadiendo coste sin aportar señal. Si reordena candidatos, entonces está influyendo en el resultado y merece ser observado con más cuidado.
Esa es la idea detrás de medir la discriminación del juez: no basta con tener un juez; hay que saber si el juez realmente ayuda a decidir.
Y en la prueba del dron, esa métrica habló a la primera. El juez puntuó las doce propuestas en una banda estrecha —media en torno a 0,94— y registró empate en los cuatro pasos: nunca separó a los líderes. La ceremonia siguió funcionando, el desempate determinista eligió ganador y el acta quedó completa. Pero la señal es accionable: este juez, con este modelo y este prompt, todavía no discrimina. Toca recalibrar el juez —el prompt, la escala o el modelo—, y la métrica que destapó el problema es la misma que confirmará la mejora. Sin ella, esa conclusión habría sido invisible.
La combinación completa el círculo: la traza permite leer una decisión individual; las métricas muestran si el sistema de decisiones se comporta bien en conjunto.
Nativo de Kubernetes, desplegable con Helm
Choreographer está pensado como infraestructura.
No es un notebook ni un script local con tres llamadas a un SDK. Vive en Kubernetes y se despliega mediante Helm, como una pieza normal de plataforma. Se instala, se actualiza y se configura como una release más.
Una vez desplegado, exporta OpenTelemetry, se integra con colectores, Tempo, Grafana y Prometheus, y encaja con una postura de seguridad de plataforma.
En el despliegue de Underpass, Choreographer exporta spans por OTLP/gRPC hacia el collector del namespace runtime usando mTLS. Desde ahí, el plano de observabilidad puede enviarlos a Tempo y hacerlos visibles en Grafana.
Ese detalle no es decorativo. Si queremos que una decisión multiagente sea operable, tiene que comportarse como el resto de sistemas operables:
- tener identidad de servicio
- emitir telemetría estándar
- desplegarse y actualizarse con Helm
- poder reiniciarse y escalarse
- poder inspeccionarse desde herramientas existentes
- poder vivir dentro de políticas de red y seguridad
La tesis no es "los agentes son especiales". La tesis es casi la contraria: si los agentes van a participar en sistemas de producción, tienen que entrar en la disciplina normal de producción.
Agnóstico por diseño
Choreographer también intenta evitar una trampa común: confundir el valor del sistema con el proveedor del modelo.
El valor no debería estar en si hoy usas un modelo local, un endpoint en la nube, un entorno de ejecución concreto o una librería de agentes concreta. Todas esas piezas van a cambiar.
Lo que debería sobrevivir es el protocolo de decisión.
Por eso Choreographer ya tiene interfaces para OpenAI, Anthropic y vLLM. Puedes usar modelos en la nube, modelos servidos localmente o cambiar de proveedor sin cambiar la forma de la ceremonia.
Por debajo de esas interfaces, el núcleo —escrito en Rust, con arquitectura hexagonal— se organiza alrededor de puertos estrechos: agentes, validadores, puntuación, ejecución, persistencia, mensajería. Los proveedores viven fuera del dominio. El dominio no debería saber si una propuesta la generó un modelo servido por vLLM, una API externa, un motor determinista o incluso un humano en el proceso.
Esa separación tiene dos efectos prácticos.
Primero, puedes cambiar piezas sin reescribir la forma de decidir.
Segundo, puedes probar y razonar sobre la decisión sin arrastrar todas las dependencias del mundo exterior.
La ceremonia es el contrato. Los adaptadores son implementaciones.
Qué no es Choreographer
También conviene precisar lo que Choreographer no promete.
No pretende ser "otro framework de agentes".
No es solo un motor de workflows. Un workflow mueve tareas. Una ceremonia estructura una decisión.
No es solo tracing. La traza importa porque el proceso está modelado de forma que puede dejar un rastro significativo. Si el proceso fuera opaco, Grafana solo mostraría spans vacíos.
Y no es full event sourcing. No estamos prometiendo replay durable de todos los efectos externos ni ejecución determinista. Estamos prometiendo algo más ajustado: una decisión observable, con suficiente estructura para abrirla después y entender cómo se tomó.
Esa distinción importa. Si queremos construir infraestructura de producción para agentes, tenemos que ser precisos.
Por qué esto importa
La primera ola de agentes se ha centrado mucho en capacidad: qué herramientas puede llamar, qué contexto puede leer, cuántos pasos puede ejecutar, qué modelo usa.
La siguiente pregunta es más incómoda:
¿Podemos confiar en cómo decide?
No en el sentido abstracto de "me gusta este resultado". En el sentido operativo:
- ¿Puedo ver cómo llegó ahí?
- ¿Puedo cambiar el proceso?
- ¿Puedo comparar decisiones?
- ¿Puedo detectar deliberaciones pobres?
- ¿Puedo auditar una reunión pasada?
- ¿Puedo mover esto entre proveedores y entornos de ejecución?
Choreographer intenta contestar que sí desde la arquitectura.
Con ceremonias declarativas, la decisión se diseña.
Con deliberate, la decisión se ejecuta como un flujo de propuesta, crítica, validación, puntuación y selección.
Con OpenTelemetry y Grafana, la decisión se observa.
Con métricas, la decisión se mide.
Con Kubernetes, la decisión se opera.
Con puertos y adaptadores, la decisión se mantiene portable.
Cierre
El resultado importa.
Pero cuando ese resultado afecta a una decisión que hay que defender, el proceso importa más.
Porque una respuesta puede parecer correcta y aun así ser imposible de defender. Una decisión observable, en cambio, deja ver sus alternativas, sus objeciones, sus validaciones y su criterio de selección.
Esa es la apuesta de Choreographer:
tratar el razonamiento multiagente como infraestructura configurable, observable, medible, portable y revisable.
No queremos solo agentes que contesten.
Queremos decisiones que se puedan auditar.
Choreographer es open source. El código, el chart de Helm, las ceremonias de catálogo, el documento de arquitectura y el catálogo completo de métricas están en github.com/underpass-ai/underpass-choreographer.
Top comments (0)