AgentBus

AI 에이전트 플릿을 위한 내구성 있는 조정 버스 — 되돌릴 수 없는 모든 작업 앞에 사람의 승인 게이트가 있습니다.

에이전트가 배포, 전송, 삭제, 지출을 점점 더 많이 수행할 수 있게 되었습니다. 그 시점에서 두 가지가 깨지는데, 둘 다 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%" vs "전체 롤아웃")를 포함합니다. 영원히 대기하지 않고 만료됩니다. 모든 요청과 결정 — 누가, 언제, 왜 — 감사 로그에 기록됩니다.

순서는 타임스탬프가 아닌 SQLite 시퀀스에 따릅니다: 같은 밀리초에 게시된 두 메시지도 명확한 순서를 가집니다.

HTTP API

AGENTBUS_TOKEN을 설정하면 Authorization: Bearer …가 필요합니다. 승인 링크는 자체 HMAC 토큰을 가지므로 API 키를 넘기지 않고 휴대폰으로 보낼 수 있습니다.

환경 변수: AGENTBUS_URL, AGENTBUS_TOKEN, AGENTBUS_DB, AGENTBUS_SECRET, AGENTBUS_AGENT, AGENTBUS_ALLOWED_ORIGINS.

브라우저 출처 정책

기본값은 루프백에서 인증되지 않은 서버입니다. 즉, 열려 있는 웹페이지가 서버에 도달할 수 있다는 뜻입니다. 세 가지 규칙이 이를 막으며, 토큰이 설정되었는지 여부와 관계없이 적용됩니다:

• Origin 헤더를 포함한 요청은 해당 출처가 서버 자체, AGENTBUS_URL의 호스트, 또는 AGENTBUS_ALLOWED_ORIGINS에 나열된 경우가 아니면 거부됩니다. 거부는 403을 의미합니다 — 단순히 CORS 헤더가 없는 것이 아니라, 응답을 숨기지만 쓰기는 수행하는 것과 다릅니다.

• POST는 content-type: application/json을 요구합니다. 폼 및 text/plain 본문은 브라우저가 사전 점검 없이 보내는 CORS "단순 요청"이므로, 이를 수락하면 구멍이 다시 열립니다.

• 예상치 못한 Host 헤더는 거부되어 DNS 리바인딩을 차단합니다.

비브라우저 클라이언트 — 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