Kollaboratives Mensch-Agent-Protokoll (CHAP)

Das Protokoll für Menschen und Agenten, die gemeinsam echte Arbeit erledigen.

Wenn ein KI-Agent einen Entwurf erstellt und ein Mensch ihn bearbeitet – wo lebt diese Bearbeitung? In CHAP lebt sie in einem Umschlag, den du sechs Monate später abfragen, abspielen und verifizieren kannst.

Installation · Die 90-Sekunden-Tour · Zwölf Szenarien · Über dieses Repository · Paper

Du hast Agenten, die echte Arbeit erledigen. Code-Reviews entwerfen, Tickets triagieren, Vergleiche vorschlagen, Verträge prüfen. Ein Mensch genehmigt, bearbeitet oder lehnt jeden einzelnen ab. Genau jetzt lebt diese Entscheidung in deinem Anwendungscode, in deinen Chat-Threads, in deinen Ticket-Kommentaren und in deinem Kopf. Wenn sechs Wochen später etwas schiefgeht, kostet dich die Rekonstruktion dessen, was passiert ist, fünfundvierzig Minuten und ist zur Hälfte Rätselraten.

CHAP gibt dir einen Ort für diese Entscheidungen und eine Form, in die du sie gießen kannst. Der Entwurf des Agenten ist ein Artefakt. Die Bearbeitung des Menschen ist ein strukturierter Override mit einem Diff, einer Begründung und Tags, die du kontrollierst. Das Ganze wird per Inhalts-Hash zu einer Kette verbunden. Du fragst die Kette ab, statt Logs über vier UIs zu durchsuchen.

Die Kette übersteht Schlüsselrotation, Log-Ablauf und das Ausscheiden von Personen; ein einziger audit.read-Aufruf liefert das Ganze. Die Overrides, die deine Reviewer ohnehin schon machen, akkumulieren sich zu Supervisionsdaten, die du sonst hattest in Auftrag geben müssen. Wenn Genehmigungen nicht-abstreitbar sein müssen, fügt security-signed/1.0 OIDC-gebundene Signaturen mit einer von dir definierten signature_meaning hinzu, und audit-scitt/1.0 verankert die Kette in einem externen Transparenzlog, verifizierbar ohne Vertrauen in deine Server. Und CHAP sitzt neben MCP und A2A, statt sie zu ersetzen: MCP für Tools, A2A für andere Agenten, CHAP für die gemeinsame Arbeit mit Menschen.

Das ist der ganze Pitch.

Die 90-Sekunden-Tour

Ein Solo-Entwickler, der Cursor nutzt, um Pull Requests zu reviewen. Der Bot markiert eine „Warnung", mit der der Entwickler nicht einverstanden ist. Hier ist der gesamte Austausch, Ende zu Ende. Der Clip unten läuft in etwa 23 Sekunden über sechs beschriftete Schritte; der passende Code steht direkt darunter.

Und hier ist der Code, jede einzelne Zeile. Eine durchgehende Geschichte in zwei Sprachen; wähle den Stack, den du tatsächlich nutzt.

1. Einen Workspace aufsetzen. Ein eingebetteter Koordinator mit SQLite-Persistenz, zwei Teilnehmer, ein Workspace:

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. Der Bot entwirft, du überschreibst. Verdrahte deine bestehende Cursor-Integration so, dass sie Umschläge ausgibt:

// 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"],
})

Über die Oberflächen. TypeScript liefert eine typisierte Fassade (coord.api.*), sodass jede Methode vollständige Autovervollständigung und Compile-Zeit-Prüfungen erhält. Python behält die JSON-RPC-Umschlagform an der Oberfläche (coord.dispatch({...})), und Konsumenten wrappen sie, wie es zur Aufrufstelle passt; ein send()-Helfer ist das Idiom, das die Python-Tests verwenden. Beide Pfade erzeugen identische Wire-Bytes; die Audit-Kette ist Byte für Byte dieselbe, unabhängig davon, welcher Client den Aufruf gemacht hat.

3. Zwei Monate später: Analysiere, was du getan hast. Das Referenz-Repository enthält ein Analysescript in beiden Sprachen, das die Audit-Kette liest (über HTTP oder direkt aus deiner SQLite-Datei) und Overrides gruppiert:

# 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

Deine nächste Prompt-Überarbeitung für Cursor nennt das Muster beim Namen, statt zu raten.

Related MCP server: interlock-mcp

Der Override-Umschlag im Detail

Wenn du eine Form genau liest, dann den Override-Umschlag. Jedes Feld hat eine Aufgabe:

Die beiden Felder, die die meisten beim ersten Lesen übersehen, sind intent_preserved und tags.

intent_preserved unterscheidet einen verfeinernden Override (der Mensch stimmte der Entscheidung des Agenten zu, schrieb aber neu, wie sie ausgedrückt wurde) von einem substituierenden Override (der Mensch traf eine andere Entscheidung). Das sind zwei verschiedene Fehlermodi, und sie wollen verschiedene Korrekturen. Eine hohe Verfeinerungsrate um eine Policen-Klausel bedeutet, dass der Abruf des Agenten danebenliegt; eine hohe Substitutionsrate bei derselben Klausel bedeutet, dass die Policy selbst mehrdeutig ist oder der Aufgabenkontext des Agenten falsch ist.

tags ist das kontrollierte Vokabular, auf das sich dein Team einigt. Halte es klein. Was du dort hineinlegst, ist die Dimension, nach der du in drei Monaten aggregierst, wenn du Fragen beantwortest wie welche Prompts brauchen Arbeit? oder auf welchen Pfaden liegt der Bot konstant falsch?

Installation

TypeScript / Node:

npm install @brightbeamai/chap-coordinator

Python:

pip install chap-coordinator

Beide Pfade liefern dir Core plus das review/1.0-Profil und eine ausführbare Referenz. Die TypeScript-Referenz liegt in reference/; die Python-Referenz in reference/python/. Die TypeScript-Bibliothek liegt unter packages/coordinator/; die Python-Bibliothek unter packages/coordinator-py/.

Fünfminütiger Hands-on-Durchlauf: examples/00-five-minute-start.md.

Status

CHAP 0.2 ist ein öffentlicher Entwurf. Die Spezifikation umfasst sieben Core-Methoden plus elf optionale Profile (SPECIFICATION.md), mit zwei Referenzimplementierungen, TypeScript und Python, die jedes Profil abdecken und die Konformitätsprüfung auf demselben JSON-RPC-2.0-Wire bestehen. Ein Koordinator kann sich als MCP-Server oder als A2A-Agent präsentieren, und fünf Framework-Brücken bringen LangGraph-, Pydantic-AI-, AG2-, LlamaIndex-Workflows- und Google-ADK-Entscheidungen mit Mensch-im-Loop auf die Audit-Kette. Das vollständige Inventar, die Repository-Struktur und wie CHAP zu MCP und A2A steht, findest du in ABOUT.md.

Breaking Changes folgen Semantic Versioning. Profiloberflächen bewegen sich schneller als Core; wenn du also strikte Stabilität brauchst, warte auf 1.0.

Als Nächstes lesen

Beginne mit IN_PRACTICE.md, zwölf Szenarien von einem Solo-Entwickler mit Cursor bis hin zu GMP-regulierter Fertigung; das ist die nützlichste nächste Lektüre. ABOUT.md behandelt, was im Repository ist, wie CHAP zu MCP und A2A steht, die Standards, die es wiederverwendet, und wie du beitragen kannst. core/SPEC.md bringt die gesamte Protokolloberfläche auf einen Bildschirm. Und der technische Bericht auf arXiv begründet die Designentscheidungen: Architektur, Profilsemantik, Bedrohungsmodell und die zwölf Szenarien als JSON-Traces in einem ausgearbeiteten Anhang.

Zitieren

Wenn du CHAP in akademischer oder technischer Arbeit referenzierst, zitiere bitte den technischen Bericht:

@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 (Spezifikation) · Apache 2.0 (Code) · Lizenzfrei, jede Sprache, jede Bereitstellung.