Protocolo Colaborativo Humano-Agente (CHAP)

El protocolo para que humanos y agentes trabajen juntos de verdad.

Cuando un agente de IA redacta algo y un humano lo edita, ¿dónde vive esa edición? En CHAP, vive en un sobre que puedes consultar, reproducir y verificar seis meses después.

Instalación · El recorrido de 90 segundos · Doce escenarios · Sobre este repositorio · Artículo

Tienes agentes haciendo trabajo real. Redactan revisiones de código, clasifican incidencias, sugieren acuerdos, revisan contratos. Un humano aprueba, edita o rechaza cada uno. Ahora mismo, esa decisión vive en el código de tu aplicación, en tus hilos de chat, en los comentarios de tus incidencias y en tu cabeza. Cuando algo sale mal seis semanas después, reconstruir lo que pasó te cuesta cuarenta y cinco minutos y es en parte adivinar.

CHAP te da un único lugar para poner esas decisiones y una única forma para estructurarlas. El borrador del agente es un artefacto. La edición del humano es una anulación estructurada con un diff, una justificación y etiquetas que controlas tú. Todo se encadena mediante hash de contenido. Consultas la cadena en lugar de buscar en los registros de cuatro interfaces.

La cadena sobrevive a la rotación de claves, a la caducidad de los registros y a que la gente se vaya; una sola llamada a audit.read lo devuelve todo. Las anulaciones que tus revisores ya estaban haciendo se acumulan en datos de supervisión que de otro modo tendrías que encargar. Cuando las aprobaciones deben ser no repudiables, security-signed/1.0 añade firmas vinculadas a OIDC con un signature_meaning que defines tú, y audit-scitt/1.0 ancla la cadena en un registro de transparencia externo, verificable sin confiar en tus servidores. Y CHAP se sitúa junto a MCP y A2A en lugar de sustituirlos: MCP para herramientas, A2A para otros agentes, CHAP para el trabajo compartido con humanos.

Esa es toda la propuesta.

El recorrido de 90 segundos

Un desarrollador en solitario que usa Cursor para revisar solicitudes de extracción. El bot marca una "advertencia" con la que el desarrollador no está de acuerdo. Aquí está todo el intercambio, de principio a fin. El vídeo de abajo dura unos 23 segundos en seis pasos etiquetados; el código correspondiente está justo debajo.

Y aquí está el código, entero. Una historia continua en dos lenguajes; elige la pila que uses de verdad.

1. Pon en marcha un espacio de trabajo. Un coordinador integrado con persistencia SQLite, dos participantes, un espacio de trabajo:

import { Coordinator } from "@brightbeamai/chap-coordinator";
import { SqliteStore } from
  "@brightbeamai/chap-coordinator/storage/sqlite";

const coord = new Coordinator({
  store: new SqliteStore("./chap.db"),
});

coord.api.workspace.create({
  workspace: "wsp_pr_reviews",
  profiles:  ["core/1.0", "review/1.0"],
});

coord.api.participant.join({
  workspace: "wsp_pr_reviews",
  from:      "human:me@local",
  type:      "human",
});

coord.api.participant.join({
  workspace: "wsp_pr_reviews",
  from:      "agent:cursor#v1",
  type:      "agent",
});

from chap_coordinator import Coordinator
from chap_coordinator.storage.sqlite \
    import SqliteStore

coord = Coordinator(store=SqliteStore("./chap.db"))

def send(method, params):
    return coord.dispatch({
        "jsonrpc": "2.0", "id": method,
        "method": method, "params": params,
    })

send("workspace.create", {
    "workspace": "wsp_pr_reviews",
    "profiles":  ["core/1.0", "review/1.0"],
})

send("participant.join", {
    "workspace": "wsp_pr_reviews",
    "from":      "human:me@local",
    "type":      "human",
})

send("participant.join", {
    "workspace": "wsp_pr_reviews",
    "from":      "agent:cursor#v1",
    "type":      "agent",
})

2. El bot redacta, tú anulas. Conecta tu integración existente con Cursor para que emita sobres:

// The bot's review is the output of a task.
const { task_id } = coord.api.task.create({
  workspace: "wsp_pr_reviews",
  from:      "agent:cursor#v1",
  assignee:  "agent:cursor#v1",
  kind:      "code_review",
  input:     { pr_id: "PR-482" },
});

coord.api.task.complete({
  workspace: "wsp_pr_reviews",
  from:      "agent:cursor#v1",
  task_id,
  output:    cursorReview,
});

coord.api.review.request({
  workspace: "wsp_pr_reviews",
  from:      "agent:cursor#v1",
  task_id,
  artefact:  cursorReview,
  to:        "human:me@local",
});

// You disagree with one comment. Override it.
coord.api.decide.override({
  workspace:        "wsp_pr_reviews",
  from:             "human:me@local",
  task_id,
  intent_preserved: true,
  diff: [{ op: "replace",
           path: "/comments/0/severity",
           value: "info" }],
  rationale: "False positive. Framework " +
             "convention, not a bug.",
  tags: ["false-positive",
         "framework-pattern-misread"],
});

# The bot's review is the output of a task.
r = send("task.create", {
    "workspace": "wsp_pr_reviews",
    "from":      "agent:cursor#v1",
    "assignee":  "agent:cursor#v1",
    "kind":      "code_review",
    "input":     {"pr_id": "PR-482"},
})
task_id = r["result"]["task_id"]

send("task.complete", {
    "workspace": "wsp_pr_reviews",
    "from":      "agent:cursor#v1",
    "task_id":   task_id,
    "output":    cursor_review,
})

send("review.request", {
    "workspace": "wsp_pr_reviews",
    "from":      "agent:cursor#v1",
    "task_id":   task_id,
    "artefact":  cursor_review,
    "to":        "human:me@local",
})

# You disagree with one comment. Override it.
send("decide.override", {
    "workspace":        "wsp_pr_reviews",
    "from":             "human:me@local",
    "task_id":          task_id,
    "intent_preserved": True,
    "diff": [{"op":    "replace",
              "path":  "/comments/0/severity",
              "value": "info"}],
    "rationale": "False positive. Framework "
                 "convention, not a bug.",
    "tags": ["false-positive",
             "framework-pattern-misread"],
})

Sobre las superficies. TypeScript incluye una fachada tipada (coord.api.*) para que cada método tenga autocompletado completo y comprobaciones en tiempo de compilación. Python mantiene la forma del sobre JSON-RPC en la superficie (coord.dispatch({...})) y los consumidores lo envuelven como mejor se adapte al punto de llamada; un helper send() es el modismo que usan los tests de Python. Ambas rutas emiten los mismos bytes en el cable; la cadena de auditoría es idéntica byte a byte independientemente de qué cliente haga la llamada.

3. Dos meses después, analiza lo que has estado haciendo. El repositorio de referencia incluye un script de análisis en ambos lenguajes que lee la cadena de auditoría (por HTTP o directamente desde tu archivo SQLite) y agrupa las anulaciones:

# TypeScript reference, against the SqliteStore from step 1:
$ npm --prefix reference/core-plus-review run analyze -- --db ./chap.db wsp_pr_reviews

# Python reference, same idea:
$ python3 reference/python/analyze_overrides.py --db ./chap.db wsp_pr_reviews

Override Learning Report
========================
Total overrides: 47

By tag:
  false-positive             ████████████████  31  (66%)
  framework-pattern-misread  ███████████       22  (47%)
  cosmetic-pref              ████              8   (17%)

Top file paths:
  src/handlers/                                    18 overrides
  src/components/                                  9  overrides

Tu próxima revisión del prompt para Cursor menciona el patrón por su nombre en lugar de adivinarlo.

Related MCP server: interlock-mcp

El sobre de anulación, en detalle

Si hay una forma que debas mirar de cerca, que sea el sobre de anulación. Cada campo tiene un trabajo:

Los dos campos que la mayoría pasa por alto en la primera lectura son intent_preserved y tags.

intent_preserved distingue una anulación de refinamiento (el humano estuvo de acuerdo con la decisión del agente pero reescribió cómo se expresaba) de una anulación de sustitución (el humano llegó a una decisión distinta). Son dos modos de fallo diferentes y requieren correcciones diferentes. Una tasa alta de refinamiento en torno a una cláusula de una política significa que la recuperación del agente falla; una tasa alta de sustitución en la misma cláusula significa que la propia política es ambigua, o que el contexto de la tarea del agente es incorrecto.

tags es el vocabulario controlado en el que tu equipo se pone de acuerdo. Mantenlo pequeño. Lo que pongas ahí es la dimensión sobre la que agregarás dentro de tres meses, cuando respondas preguntas como ¿qué prompts necesitan trabajo? o ¿qué rutas está fallando el bot de forma sistemática?

Instalación

TypeScript / Node:

npm install @brightbeamai/chap-coordinator

Python:

pip install chap-coordinator

Cualquiera de las dos rutas te da Core más el perfil review/1.0 y una referencia ejecutable. La referencia de TypeScript está en reference/; la de Python en reference/python/. La biblioteca de TypeScript está en packages/coordinator/; la de Python en packages/coordinator-py/.

Tutorial práctico de cinco minutos: examples/00-five-minute-start.md.

Estado

CHAP 0.2 es un borrador público. La especificación son siete métodos Core más once perfiles opcionales (SPECIFICATION.md), con dos implementaciones de referencia, TypeScript y Python, que cubren todos los perfiles y pasan el arnés de conformidad en el mismo cable JSON-RPC 2.0. Un coordinador puede presentarse como servidor MCP o como agente A2A, y cinco puentes de frameworks ponen las decisiones de supervisión humana de LangGraph, Pydantic AI, AG2, LlamaIndex Workflows y Google ADK en la cadena de auditoría. El inventario completo, la estructura del repositorio y cómo se relaciona CHAP con MCP y A2A están en ABOUT.md.

Los cambios que rompen compatibilidad siguen el Control de Versiones Semántico. Las superficies de los perfiles avanzan más rápido que Core, así que si necesitas estabilidad estricta, espera a la 1.0.

Sigue leyendo

Empieza con IN_PRACTICE.md, doce escenarios desde un desarrollador en solitario con Cursor hasta fabricación regulada por GMP; es la siguiente lectura más útil. ABOUT.md cubre qué hay en el repositorio, cómo se relaciona CHAP con MCP y A2A, los estándares que reutiliza y cómo contribuir. core/SPEC.md encaja toda la superficie del protocolo en una pantalla. Y el informe técnico en arXiv fundamenta las decisiones de diseño: arquitectura, semántica de perfiles, modelo de amenazas y los doce escenarios como trazas JSON en un apéndice práctico.

Citar

Si haces referencia a CHAP en trabajo académico o técnico, cita el informe técnico:

@techreport{chap2026,
  author      = {Shahid, Arsalan and Suttie, Gordon and Black, Philip},
  title       = {Collaborative Human-Agent Protocol (CHAP): An open protocol for auditable, structured multi-human and multi-agent collaboration},
  institution = {Brightbeam AI},
  year        = {2026},
  type        = {Technical Report},
  number      = {arXiv:2606.09751},
  url         = {https://arxiv.org/abs/2606.09751}
}

CC-BY 4.0 (especificación) · Apache 2.0 (código) · Libre de regalías, cualquier lenguaje, cualquier despliegue.