# 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](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:

```plaintext
fiebre leve y dolor de garganta
```

![](http://localhost:63342/markdownPreview/1267483732//Users/josediaz/Projects/JoeDayz/kcp/equipo-agentes-con-kcp/docs align="center")

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**

![](https://cdn.hashnode.com/uploads/covers/64a79aba336591d2a1481aae/e7341706-40d4-4ad6-81b5-73916342a515.png align="center")

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`

![](https://cdn.hashnode.com/uploads/covers/64a79aba336591d2a1481aae/737efc1b-4465-4fc1-8b90-72a8a4e22b7b.png align="center")

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`

![](https://cdn.hashnode.com/uploads/covers/64a79aba336591d2a1481aae/efede684-455d-47d4-b3cb-777207a7bdb3.png align="center")

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**

![](https://cdn.hashnode.com/uploads/covers/64a79aba336591d2a1481aae/87c33618-7114-409c-b1fd-66910e418917.png align="center")

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

## **Diagrama 5: intento fuera de alcance**

![](https://cdn.hashnode.com/uploads/covers/64a79aba336591d2a1481aae/7949bfef-0ea4-4267-8b2f-86ab9b2d8c45.png align="center")

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**

```typescript
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
```

![](http://localhost:63342/markdownPreview/1267483732//Users/josediaz/Projects/JoeDayz/kcp/equipo-agentes-con-kcp/docs align="center")

## **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