AgentBus

Ein dauerhafter Koordinationsbus für KI-Agentenflotten – mit einem menschlichen Genehmigungs-Gate vor allem, was irreversibel ist.

Agenten dürfen zunehmend bereitstellen, senden, löschen und ausgeben. An diesem Punkt brechen zwei Dinge, und keines davon ist ein LLM-Problem:

1. Übergaben gehen verloren. Ein Agent wird fertig, übergibt die Arbeit an den nächsten, und der Prozess stirbt. Nichts wird erneut versucht, niemand merkt es.

2. Es gibt keinen zentralen Kontrollpunkt. Die Genehmigung lebt in einem Prompt – „frag mich zuerst“ –, was ein Vorschlag ist, keine Kontrolle, und keine Aufzeichnung hinterlässt, wer was erlaubt hat.

AgentBus ist die unaufgeregte Infrastruktur darunter: eine persistente Warteschlange mit Mindestens-einmal-Zustellung, ein blockierendes menschliches Genehmigungs-Gate und ein Append-only-Audit-Log über jede Nachricht und jede Entscheidung.

                    ┌──────────────────────────────┐
   agents  ────────▶│  topics · groups · leases    │────────▶  workers
   (MCP/HTTP/CLI)   │  retries · dead letters      │
                    ├──────────────────────────────┤
   agent  ─ ask ───▶│  approval gate  ── blocks ───│──▶ human (phone/dashboard)
                    ├──────────────────────────────┤
                    │  append-only audit log       │
                    └──────────────────────────────┘
                         one SQLite file

Keine Laufzeitabhängigkeiten. Kein Redis, kein Postgres, kein Broker, kein Cloud-Konto. Node 24+ und eine Datei.

Schnellstart

npx agentbus serve                 # http://127.0.0.1:7801 — API + dashboard

Riskante Aktionen hinter ein menschliches Gate legen

agentbus ask "Deploy api build 118 to production" \
  --action deploy.prod --risk high \
  --detail "3 commits, including a migration that drops a column." \
  --payload '{"service":"api","build":118}' \
  --wait && ./deploy.sh

ask --wait blockiert und gibt einen Link aus. Eine Person öffnet ihn auf ihrem Telefon, genehmigt oder lehnt ab, und der Befehl beendet sich mit 0 genehmigt · 10 abgelehnt · 11 abgelaufen – sodass && genau das Richtige tut und die Entscheidung unter ihrem Namen protokolliert wird.

Dauerhafte Arbeitsübergabe

# Producer — survives a crash, deduplicated by key
agentbus pub job.render '{"file":"a.png"}' --key render-a

# Consumer — any shell command becomes a durable worker.
# Payload on stdin; exit 0 acks, non-zero retries with backoff, then dead-letters.
agentbus sub 'job.>' --group renderers --exec './render.sh'

Nicht quittierte Arbeit kehrt in die Warteschlange zurück, wenn die Lease abläuft. Ein Worker, der mitten in der Aufgabe beendet wird, verliert nichts.

Related MCP server: gotoHuman MCP Server

Einem Agenten Zugriff gewähren (MCP)

// .mcp.json  — or claude_desktop_config.json
{
  "mcpServers": {
    "agentbus": {
      "command": "npx",
      "args": ["-y", "agentbus", "mcp"],
      "env": { "AGENTBUS_URL": "http://127.0.0.1:7801", "AGENTBUS_AGENT": "deploy-agent" }
    }
  }
}

Der Agent erhält request_approval, check_approval, publish, pull, ack, nack und stats. request_approval blockiert, bis ein Mensch entscheidet, und gibt explizite Anweisungen zurück:

{
  "state": "denied",
  "approved": false,
  "decidedBy": "sami",
  "reason": "not without a backup",
  "guidance": "Not approved (denied). Do NOT proceed. Tell the user and stop."
}

Ein Timeout gibt pending zurück, niemals approved – Schweigen ist niemals Zustimmung.

Konzepte

Topics sind punktgetrennt: deploy.prod.api. Muster verwenden * für ein Segment und > für den Rest – deploy.>, *.prod.api, >.

Consumer-Gruppen erhalten jeweils eine eigene Kopie jeder passenden Nachricht. Innerhalb einer Gruppe geht eine Nachricht zu einem bestimmten Zeitpunkt an genau einen Worker. Eine neue Gruppe startet standardmäßig ab jetzt; --earliest spielt den gesamten Rückstand erneut ab.

Leases geben einem Worker ein Sichtbarkeits-Timeout (Standard 30 s, verlängerbar). Wird es verpasst, wird die Nachricht erneut zugestellt. Nach max_attempts (5) wird sie in die Dead-Letter-Queue gelegt, ist im Dashboard sichtbar und mit einem Klick erneut abspielbar.

Genehmigungen (Approvals) tragen einen Titel, eine maschinenlesbare Aktion, ein Freitext-Detail, eine strukturierte Nutzlast, eine Risikostufe und optionale beschriftete Auswahlmöglichkeiten („Canary 10 %“ vs. „vollständiges Rollout“). Sie laufen ab, statt für immer zu hängen. Jede Anfrage und Entscheidung – wer, wann, warum – landet im Audit-Log.

Reihenfolge wird über eine SQLite-Sequenz bestimmt, nicht über den Zeitstempel: Zwei Nachrichten, die in derselben Millisekunde veröffentlicht werden, haben trotzdem eine klar definierte Reihenfolge.

HTTP-API

Setzt man AGENTBUS_TOKEN, wird Authorization: Bearer … verlangt. Genehmigungslinks enthalten ihr eigenes HMAC-Token, sodass man einen davon an ein Telefon senden kann, ohne den API-Schlüssel herauszugeben.

Umgebungsvariablen: AGENTBUS_URL, AGENTBUS_TOKEN, AGENTBUS_DB, AGENTBUS_SECRET, AGENTBUS_AGENT, AGENTBUS_ALLOWED_ORIGINS.

Browser-Origin-Richtlinie

Standardmäßig läuft ein nicht authentifizierter Server auf Loopback; das bedeutet, dass eine Webseite, die man gerade offen hat, sonst darauf zugreifen könnte. Drei Regeln verhindern das, und sie gelten unabhängig davon, ob ein Token gesetzt ist:

• Eine Anfrage mit einem Origin-Header wird abgelehnt, sofern diese Origin nicht die eigene des Servers, der Host aus AGENTBUS_URL oder in AGENTBUS_ALLOWED_ORIGINS aufgeführt ist. Abgelehnt bedeutet 403 – nicht bloß ein fehlender CORS-Header, der die Antwort versteckt, aber den Schreibvorgang trotzdem ausführt.

• POST erfordert content-type: application/json. Formular- und text/plain-Bodies sind CORS-„Simple Requests“, die ein Browser ganz ohne Preflight sendet; sie zu akzeptieren würde die Sicherheitslücke wieder öffnen.

• Ein unerwarteter Host-Header wird abgelehnt, was DNS-Rebinding blockiert.

Nicht-Browser-Clients – die CLI, der MCP-Server, curl, eigene Skripte – senden kein Origin und sind nicht betroffen. Wenn man das Dashboard auf einer LAN-Adresse oder hinter einem Proxy bereitstellt, damit Genehmigungen ein Telefon erreichen, setzt man AGENTBUS_URL (oder --url) auf diese öffentliche Origin; aus ihr werden ohnehin die Genehmigungslinks erstellt.

Entwicklung

npm test          # 66 tests, no network, no fixtures
npm run typecheck # strict, noUncheckedIndexedAccess, erasableSyntaxOnly

TypeScript läuft direkt auf Node 24 über natives Type-Stripping – es gibt keinen Build-Schritt und keinen Compiler im Laufzeitpfad.

Lizenz

MIT