AgentBus

Прочная шина координации для флотов ИИ-агентов — с блокирующим этапом одобрения человеком перед любым необратимым действием.

Агентам всё чаще разрешают развёртывать, отправлять, удалять и тратить. В этот момент ломаются две вещи, и ни одна из них не является проблемой LLM:

1. Передача работы теряется. Агент завершает задачу, передаёт работу следующему, и процесс умирает. Никто не повторяет попытку, никто не замечает.

2. Нет единой точки контроля. Одобрение живёт внутри промпта — «сначала спроси меня» — это предложение, а не контроль, и не оставляет записи о том, кто что разрешил.

AgentBus — это скучная инфраструктура под всем этим: прочная очередь с доставкой как минимум один раз, блокирующий шлюз одобрения человеком и журнал аудита только для добавления, в котором фиксируется каждое сообщение и каждое решение.

                    ┌──────────────────────────────┐
   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

Ноль зависимостей в рантайме. Никакого Redis, Postgres, брокера или облачного аккаунта. Node 24+ и файл.

Быстрый старт

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

Заблокировать рискованное действие за одобрением человека

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 блокирует выполнение и выводит ссылку. Человек открывает её на телефоне, одобряет или отклоняет, и команда завершается с кодом 0 — одобрено · 10 — отклонено · 11 — истекло — так что && делает ровно то, что нужно, а решение записывается на имя этого человека.

Прочная передача работы

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

Не подтверждённая работа возвращается в очередь по истечении аренды, так что воркер, убитый в середине задачи, ничего не теряет.

Related MCP server: team-protocol

Предоставление доступа агенту (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" }
    }
  }
}

Агент получает request_approval, check_approval, publish, pull, ack, nack и stats. request_approval блокирует выполнение, пока человек не примет решение, и возвращает явные указания:

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

Тайм-аут возвращает pending, но никогда approved — молчание никогда не является согласием.

Концепции

Топики разделяются точками: deploy.prod.api. В шаблонах * означает один сегмент, а > — все остальные: deploy.>, *.prod.api, >.

Группы потребителей получают собственную копию каждого подходящего сообщения. Внутри группы сообщение одновременно обрабатывает ровно один воркер. Новая группа по умолчанию начинает с текущего момента; --earliest воспроизводит весь накопленный журнал.

Аренды дают воркеру тайм-аут видимости (по умолчанию 30 секунд, можно продлить). Если он пропущен, сообщение доставляется повторно. После max_attempts (5) сообщение попадает в очередь недоставленных, видно на панели управления и может быть воспроизведено одним кликом.

Одобрения содержат заголовок, машиночитаемое действие, произвольный текст деталей, структурированную полезную нагрузку, уровень риска и опциональные помеченные варианты («канарейка 10%» против «полный релиз»). Они истекают, а не висят вечно. Каждый запрос и решение — кто, когда, почему — попадают в журнал аудита.

Порядок определяется последовательностью SQLite, а не временной меткой: два сообщения, опубликованные в одну миллисекунду, всё равно имеют чётко определённый порядок.

HTTP API

Установите AGENTBUS_TOKEN, чтобы требовать Authorization: Bearer …. Ссылки на одобрения содержат собственный HMAC-токен, так что вы можете отправить их на телефон, не передавая ключ API.

Окружение: AGENTBUS_URL, AGENTBUS_TOKEN, AGENTBUS_DB, AGENTBUS_SECRET, AGENTBUS_AGENT, AGENTBUS_ALLOWED_ORIGINS.

Политика происхождения браузера

По умолчанию это неаутентифицированный сервер на loopback, что означает, что веб-страница, открытая у вас, в противном случае могла бы до него добраться. Три правила это предотвращают, и они действуют независимо от того, установлен ли токен:

• Запрос с заголовком Origin отклоняется, если этот источник не является собственным сервером, хостом из AGENTBUS_URL или не указан в AGENTBUS_ALLOWED_ORIGINS. Отказ означает 403 — а не просто отсутствие заголовка CORS, который скрывает ответ, но всё равно выполняет запись.

• POST требует content-type: application/json. Формы и тела text/plain — это «простые запросы» CORS, которые браузер отправляет без предварительной проверки, поэтому их принятие снова открыло бы дыру.

• Неожиданный заголовок Host отклоняется, что блокирует DNS rebinding.

Не-браузерные клиенты — CLI, MCP-сервер, curl, ваши собственные скрипты — не отправляют Origin и не затрагиваются. Если вы обслуживаете панель управления на LAN-адресе или за прокси, чтобы одобрения доходили до телефона, установите AGENTBUS_URL (или --url) на этот публичный источник; именно из него строятся ссылки на одобрения.

Разработка

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

TypeScript выполняется напрямую на Node 24 через нативное удаление типов — нет этапа сборки и нет компилятора в пути выполнения.

Лицензия

MIT