Cómo orquestar un equipo de agentes con KCP sin perder el control

Si ya tienes varios agentes colaborando, el problema no suele ser crear otro agente. El problema real es decidir qué conocimiento cargar y qué acciones permitir sin terminar con lógica casera difícil de auditar.

En esta demo resolví ese problema con dos piezas del ecosistema KCP: kcp-agent para planificar y kcp-harness para gobernar la ejecución. El resultado es un flujo donde el sistema decide qué unidades son relevantes para un caso clínico y, por separado, valida en runtime si cada agente puede leer o escribir donde dice que puede.

Source Code: https://github.com/joedayz/governed-agents.git

El problema: agentes útiles, pero sin gobernanza clara

Un equipo de agentes puede verse convincente en una demo aunque por debajo tenga reglas frágiles:

• un planificador ad hoc que decide qué cargar;

• permisos implícitos repartidos en prompts;

• validaciones que viven "en el papel" pero no en la ejecución real;

• poca trazabilidad sobre por qué una acción fue permitida o denegada.

Eso funciona hasta que un agente intenta hacer algo fuera de alcance.

En este proyecto usé un caso simple de triaje de citas clínicas para mostrar una alternativa más robusta: separar planificación y control de ejecución.

La idea central

La arquitectura se apoya en una división muy clara:

Pieza	Responsabilidad
kcp-agent	Decide qué unidades del manifiesto (skills) son relevantes para una tarea.
kcp-harness	Decide si una acción concreta está permitida según el action_scope.
orquestador.ts	Conecta ambas decisiones en una ejecución de extremo a extremo.

Dicho de forma simple: kcp-agent responde qué hace falta cargar y kcp-harness responde qué se puede hacer con eso.

El caso de ejemplo

La demo procesa un caso clínico como:

fiebre leve y dolor de garganta

Ese dato entra al orquestador y activa una corrida completa. Importa aclarar algo que suele confundir al ver la salida por primera vez:

Cada ejecución procesa un solo caso clínico. Las "unidades cargadas" no son otros casos, sino skills y documentos que kcp-agent consideró relevantes para ese mismo caso.

Cómo se modela el conocimiento

El manifiesto knowledge.yaml combina tres tipos de unidades:

1. documentos de conocimiento como protocolo-triaje y faq-agenda;

2. skills gobernadas como retriever-skill, assessor-skill, drafter-skill y executor-skill;

3. un playbook compuesto llamado gestionar-cita-clinica.

Lo interesante no es solo que todo esté descrito en el manifiesto, sino que cada skill declara su propio action_scope. Por ejemplo, executor-skill puede usar write_file, pero solo dentro de salidas/.

Diagrama 1: vista general de la orquestación

Este diagrama resume la separación de responsabilidades: primero se calcula el plan y luego se validan las acciones observadas.

Diagrama 2: planificación con kcp-agent

Aquí no se ejecuta ninguna herramienta externa ni se toca el filesystem para efectos del caso. Solo se decide qué piezas vale la pena cargar.

En una corrida normal, la salida muestra unidades como:

• faq-agenda

• gestionar-cita-clinica

• retriever-skill

• protocolo-triaje

• assessor-skill

• drafter-skill

Y puede dejar otras como "ignoradas" si no son relevantes para la intención detectada.

Diagrama 3: control de acciones con kcp-harness

Esta parte es la que convierte los permisos declarados en una frontera real de ejecución.

En la demo:

• retriever, assessor y drafter leen archivos con read_file;

• executor escribe con write_file;

• cualquier escritura fuera de salidas/ queda fuera de alcance.

Diagrama 4: ejecución normal

Si todo cae dentro del alcance, el sistema registra el resultado final en salidas/resultado.json.

Diagrama 5: intento fuera de alcance

Este es el punto más importante de la demo. La protección no depende de "que el agente se porte bien". Depende de una validación explícita y auditable en runtime.

Qué enseña esta demo en la práctica

Más allá del ejemplo clínico, hay cuatro lecciones útiles para cualquier sistema multiagente:

1. No mezcles selección de contexto con permisos de ejecución. Son problemas distintos.

2. Declara el alcance junto al skill. Si un agente puede escribir, define exactamente dónde.

3. Haz que el runtime adjudique cada acción. El permiso debe verificarse cuando ocurre la acción, no solo cuando diseñas el prompt.

4. Conserva trazabilidad. Un buen veredicto no solo bloquea: también explica por qué.

Comandos de la demo

npm install
npm run validate
npm run harness:check
npm run orquestar
npx tsx orquestador.ts "dolor de pecho y dificultad para respirar"
npm run orquestar:romper-alcance

Cuándo usar este patrón

Este enfoque vale especialmente la pena cuando tienes:

• múltiples agentes con responsabilidades separadas;

• conocimiento distribuido en varios documentos o skills;

• operaciones sensibles como escritura de archivos, llamadas a APIs o cambios de estado;

• necesidad de explicar por qué una acción fue bloqueada.

Si tu sistema todavía depende de prompts largos y permisos implícitos, KCP te da una forma más explícita de convertir esa coordinación en reglas verificables.

Cierre

La parte valiosa de esta demo no es que coordine cuatro agentes. La parte valiosa es que cada decisión importante queda separada, declarada y verificable.

kcp-agent decide la relevancia. kcp-harness decide la conformidad. El orquestador solo conecta ambas piezas.

Esa separación hace que un sistema multiagente sea más fácil de entender, más fácil de auditar y mucho más difícil de romper por accidente.

Enjoy!

Joe