Construye un equipo de agentes gobernado (y por que luego vas a querer KCP)

Un sistema multiagente no se vuelve seguro por tener mas agentes. Si cada agente puede decidir libremente que leer, que escribir y cuando actuar, solo conviertes un problema en cuatro. En este post construimos una demo de clinica con 4 agentes, un playbook declarativo, una regla de autoridad lowest-of, escalado humano y un ledger verificable. No usamos las herramientas de Thor todavia: primero entendemos el mecanismo, luego veremos por que KCP hace falta de verdad.

Y te dejo el código para que puedas probarlo por ti mismo: https://github.com/joedayz/governed-agents

El problema: mas agentes no significa mas control

Cuando la gente escucha "multiagente", suele imaginar algo asi:

• un agente busca contexto

• otro decide

• otro redacta

• otro ejecuta

Suena ordenado. Pero si no hay reglas verificables, lo unico que hiciste fue repartir el caos.

La pregunta correcta no es:

"Cuantos agentes tengo?"

La pregunta correcta es:

"Que puede hacer cada agente, con que autoridad, y como lo pruebo despues?"

Ese es el objetivo de esta demo.

La demo: una clinica, una solicitud de cita, cuatro agentes

Usamos un caso facil de entender para cualquier lector: un paciente escribe a la clinica, describe sintomas, y el sistema debe decidir que hacer.

La idea no es "tener varios LLMs". La idea es separar responsabilidades:

• el retriever lee y resume

• el assessor calcula hechos con reglas

• el drafter redacta

• el executor solo ejecuta dentro de un scope permitido

Dos usan modelo. Dos no.

Esa mezcla es importante: no todo problema debe resolverse con un LLM.

Arquitectura mental: playbook + caps + escalado humano

Todo el comportamiento del equipo sale de un manifiesto (knowledge.yaml) y de un orquestador pequeno que hace una sola cuenta:

efectivo = min(granted del paso, cap del agente)
brecha   = needs - efectivo

Si la brecha es mayor que cero, el paso escala a un humano.

No hay magia. No hay "el modelo parecia confiable". Hay una regla simple y auditable.

Los parametros reales del equipo

Estos son los agentes definidos en la demo:

Agente	usa_llm	cap	Hace
retriever	si	explain	Lee y resume protocolos y FAQ
assessor	no	propose	Calcula prioridad y accion con reglas
drafter	si	propose	Redacta la respuesta al paciente
executor	no	propose	Ejecuta acciones aprobadas

Y estos son los pasos del playbook:

Fijate en el paso 5:

• el agente es executor

• su cap real es propose

• el paso necesita execute

Entonces:

efectivo = min(propose, propose) = propose
needs    = execute
brecha   = 2

Resultado: ese paso siempre escala a humano.

Eso es gobernanza. El modelo no "se porta bien": no puede saltarse la escalera.

Diagrama del flujo completo

Los cuatro outcomes del sistema son:

• autonomous: el agente puede actuar solo

• informed: se informa a un humano, pero no bloquea

• authorized: se detiene hasta firma humana

• learning: el agente propone una mejora y el humano decide

Que hace cada agente, exactamente

1. retriever

Parametros

• usa_llm: true

• cap: explain

• lee docs/protocolo-triaje.md

• lee docs/faq-citas.md

• salida: un resumen breve para el resto del flujo

Responsabilidad

No decide. No clasifica. No confirma citas. Solo transforma documentos en contexto util.

Por que existe

Porque leer y resumir texto si es una tarea natural para un LLM.

2. assessor

Parametros

• usa_llm: false

• cap: propose

• entrada principal: caso["sintomas"]

• salida: prioridad, accion_sugerida, caso_limite, requiere_urgencias

Reglas actuales

• si hay dolor de pecho, falta de aire o desmayo -> prioridad alta

• si hay fiebre, dolor de garganta, tos o vomitos -> prioridad media

• en otro caso -> prioridad baja

Responsabilidad

Convierte sintomas en un hecho deterministico.

Por que no usa LLM

Porque esta parte no deberia depender de creatividad. Si el mismo caso entra hoy y manana, deberia producir el mismo resultado.

3. drafter

Parametros

• usa_llm: true

• cap: propose

• entrada: resumen del retriever + hecho calculado por assessor

• salida: borrador de respuesta para el paciente

Responsabilidad

Toma una decision ya calculada y la vuelve lenguaje claro.

Limite importante

Puede proponer texto. No puede comprometer agenda ni ejecutar acciones irreversibles.

4. executor

Parametros

• usa_llm: false

• cap: propose

• action_scope.paths: [salidas/]

• salida: escritura en salidas/respuesta-cliente.md

Responsabilidad

Ejecuta acciones chicas y acotadas.

Limite importante

Aunque un paso le otorgue execute, su cap sigue siendo propose. Por eso:

• puede escribir en salidas/

• no puede confirmar agenda sin autorizacion humana

• no puede escribir fuera de salidas/

Eso es fail-closed: lo no declarado queda prohibido.

El manifiesto que gobierna todo

La parte mas valiosa de la demo no esta en el prompt. Esta en el manifiesto:

agentes:
  retriever:  { cap: explain, usa_llm: true,  hace: "lee y resume protocolos y FAQ" }
  assessor:   { cap: propose, usa_llm: false, hace: "calcula prioridad y accion con reglas" }
  drafter:    { cap: propose, usa_llm: true,  hace: "redacta la respuesta al paciente" }
  executor:   { cap: propose, usa_llm: false, hace: "ejecuta acciones aprobadas" }

playbook:
  id: gestionar-cita-clinica
  pasos:
    - id: 5
      titulo: "Confirmar la reserva de la cita (compromete agenda)"
      agente: executor
      granted: propose
      needs: execute

action_scope:
  executor:
    paths: [salidas/]

Esto ya empieza a parecerse a un control plane:

• define el equipo

• define los limites

• define el flujo

• define que acciones requieren humano

La gran leccion es esta:

La autoridad no vive en el modelo. Vive en datos declarativos y reglas verificables.

Como se comporta con distintos casos

La demo incluye cuatro escenarios predefinidos:

Caso	Sintomas	Resultado
alta	dolor de pecho y falta de aire	va a urgencias
media	fiebre leve y dolor de garganta	cita en 24 horas + informed
baja	chequeo general	cita en 2 a 5 dias
borde	tos leve	cae en prioridad media

Puedes correrlos asi:

Sin Anthropic

python3 orquestador.py --sim --caso alta
python3 orquestador.py --sim --caso media
python3 orquestador.py --sim --caso baja
python3 orquestador.py --sim --caso borde

Con Anthropic

source /Users/josediaz/.api-keys
python3 orquestador.py --caso alta
python3 orquestador.py --caso media
python3 orquestador.py --caso baja
python3 orquestador.py --caso borde

Lo importante a observar no es solo la respuesta final. Mira tambien:

• como cambia el paso 2

• cuando aparece informed

• por que el paso 5 sigue escalando

• que queda registrado en ledger.jsonl

El ledger: evidencia, no solo logs

Cada paso escribe un recibo encadenado en ledger.jsonl.

Si alguien edita un evento viejo, la cadena deja de verificar.

Eso cambia la conversacion de:

• "creemos que el agente se porto bien"

a:

• "aqui esta la secuencia exacta, con actor, outcome y hash"

En sistemas multiagente esto importa aun mas, porque ya no preguntas solo "que hizo el modelo", sino que hizo cada actor y con que autoridad.

Y entonces, si esto ya funciona, por que luego necesitaremos KCP

Porque esta demo funciona, pero todavia es una version manual y pequena.

Estas son las limitaciones que aparecen en cuanto quieres escalar:

1. El contexto sigue muy cableado a mano

Hoy el retriever sabe explicitamente que debe leer:

• docs/protocolo-triaje.md

• docs/faq-citas.md

Eso sirve en un ejemplo chico. Pero en un sistema real querras:

• descubrir conocimiento por intent

• marcar fuentes deprecadas

• enrutar contexto por audiencia

• separar docs, skills, politicas y playbooks sin hardcode

Eso es exactamente el tipo de problema que KCP resuelve.

2. El manifiesto ya existe, pero aun no es interoperable de punta a punta

Ya tenemos knowledge.yaml, pero todavia:

• parte del comportamiento vive en YAML

• parte vive en orquestador.py

• parte vive en agentes.py

KCP empuja a que el conocimiento y sus metadatos sean navegables por cualquier agente, no solo por este script puntual.

3. El equipo no tiene skills reutilizables

Hoy tenemos agentes con roles, pero no una biblioteca de capacidades declaradas que otro runtime pueda cargar y respetar.

Con KCP, la idea deja de ser:

• "este script sabe hacer esto"

y pasa a ser:

• "esta capacidad esta declarada, versionada y enrutable"

4. La gobernanza local no basta cuando aparecen mas herramientas

En esta demo el executor solo escribe un archivo.

En produccion, los agentes querran tocar:

• calendarios

• bases de datos

• tickets

• correo

• APIs externas

En ese punto necesitas un protocolo claro para decir:

• que conocimiento cargar

• que tools presentar

• que scope aprobar

• como dejar evidencia portable

5. Querras que varios runtimes entiendan el mismo mapa

Si mañana cambias:

• de script local a Claude Code

• de un agente a varios

• de un repo a varios repos

no quieres reescribir la semantica del contexto desde cero.

Quieres un formato comun.

Eso es KCP: hacer navegable el conocimiento y gobernable el contexto.

El punto pedagogico de esta demo

No construimos este ejemplo para competir con un framework.

Lo construimos para que la necesidad del framework se vuelva obvia.

Primero entiendes estas ideas a mano:

1. separar roles

2. declarar autoridad

3. distinguir cap, granted y needs

4. escalar a humano cuando la brecha lo exige

5. dejar evidencia verificable

Y solo despues tiene sentido introducir KCP como la forma de volver eso:

• reusable

• estandar

• interoperable

• escalable

Sin ese paso intermedio, KCP parece "otra capa mas".

Con esta demo, se entiende que KCP es el siguiente paso natural.

Resumen para llevar

Idea	En la demo	Por que importa
Separacion de roles	4 agentes con responsabilidades distintas	reduce mezcla de decisiones
Autoridad declarada	cap, granted, needs	evita permisos implicitos
Governanza deterministica	regla lowest-of	hace verificable el flujo
Escalado humano	authorized, informed, learning	concentra supervision donde importa
Scope restringido	action_scope.paths: [salidas/]	aplica fail-closed
Evidencia	ledger.jsonl	permite auditoria posterior
Escalabilidad futura	KCP	evita hardcode de contexto y reglas

Referencias

• Demo completa: equipo-agentes/

• Manifiesto del equipo: equipo-agentes/knowledge.yaml

• Orquestador: equipo-agentes/orquestador.py

• Agentes: equipo-agentes/agentes.py

• Protocolo KCP: Knowledge Context Protocol

Si el primer post respondia "como gobierno un agente?", este responde "como gobierno un equipo?". El siguiente paso ya no es agregar mas prompts: es darle a ese equipo un mapa de conocimiento portable. Ahi es donde KCP deja de ser teoria y empieza a volverse necesario.

Enjoy!

Joe