AgentBus

Un bus de coordinación duradero para flotas de agentes de IA, con una puerta de aprobación humana frente a cualquier cosa irreversible.

Cada vez se permite más a los agentes desplegar, enviar, eliminar y gastar. En ese punto se rompen dos cosas, y ninguna es un problema de LLM:

1. Los traspasos se pierden. Un agente termina, entrega el trabajo al siguiente y el proceso muere. Nada reintenta, nadie se da cuenta.

2. No hay un punto de estrangulamiento. La aprobación vive dentro de un prompt — "pregúntame primero" — que es una sugerencia, no un control, y no deja registro de quién permitió qué.

AgentBus es la infraestructura aburrida que hay debajo: una cola duradera con entrega al menos una vez, una puerta de aprobación humana bloqueante y un registro de auditoría de solo añadidura de cada mensaje y decisión.

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

Cero dependencias en tiempo de ejecución. Sin Redis, sin Postgres, sin broker, sin cuenta en la nube. Node 24+ y un archivo.

Inicio rápido

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

Protege una acción arriesgada detrás de un humano

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 bloquea e imprime un enlace. Una persona lo abre en su teléfono, aprueba o deniega, y el comando sale con 0 aprobado · 10 denegado · 11 expirado — así que && hace exactamente lo correcto, y la decisión queda registrada con su nombre.

Traspaso de trabajo duradero

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

El trabajo no confirmado vuelve a la cola cuando expira la concesión, así que un trabajador que muere a mitad de trabajo no pierde nada.

Related MCP server: gotoHuman MCP Server

Dar acceso a un agente (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" }
    }
  }
}

El agente obtiene request_approval, check_approval, publish, pull, ack, nack y stats. request_approval bloquea hasta que un humano decide, y devuelve una guía explícita:

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

Un tiempo de espera agotado devuelve pending, nunca approved — el silencio nunca es consentimiento.

Conceptos

Los temas están separados por puntos: deploy.prod.api. Los patrones usan * para un segmento y > para el resto — deploy.>, *.prod.api, >.

Los grupos de consumidores reciben cada uno su propia copia de cada mensaje que coincida. Dentro de un grupo, un mensaje va a exactamente un trabajador a la vez. Un grupo nuevo comienza desde ahora por defecto; --earliest reproduce todo el historial pendiente.

Las concesiones dan a un trabajador un tiempo de visibilidad (30 s por defecto, ampliable). Si se supera, el mensaje se vuelve a entregar. Después de max_attempts (5) se envía a la cola de mensajes muertos, visible en el panel y reproducible con un clic.

Las aprobaciones llevan un título, una acción legible por máquina, un detalle de texto libre, una carga útil estructurada, un nivel de riesgo y opciones etiquetadas opcionales ("canary 10%" vs "despliegue completo"). Expiran en lugar de colgar para siempre. Cada solicitud y decisión — quién, cuándo, por qué — queda en el registro de auditoría.

El orden se basa en una secuencia de SQLite, no en la marca de tiempo: dos mensajes publicados en el mismo milisegundo siguen teniendo un orden bien definido.

API HTTP

Establece AGENTBUS_TOKEN para exigir Authorization: Bearer …. Los enlaces de aprobación llevan su propio token HMAC, así que puedes enviar uno a un teléfono sin entregar la clave de API.

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

Política de origen del navegador

El valor predeterminado es un servidor no autenticado en loopback, lo que significa que una página web que tengas abierta podría alcanzarlo de otro modo. Tres reglas lo impiden, y se aplican tanto si hay un token como si no:

• Una solicitud que lleve una cabecera Origin se rechaza a menos que ese origen sea el del propio servidor, el host en AGENTBUS_URL o esté listado en AGENTBUS_ALLOWED_ORIGINS. Rechazada significa 403 — no solo una cabecera CORS ausente, que oculta la respuesta pero aun así realiza la escritura.

• POST requiere content-type: application/json. Los cuerpos de formulario y text/plain son "solicitudes simples" de CORS que un navegador envía sin preflight alguno, así que aceptarlos reabriría el agujero.

• Una cabecera Host inesperada se rechaza, lo que bloquea el rebinding de DNS.

Los clientes que no son navegadores — la CLI, el servidor MCP, curl, tus propios scripts — no envían Origin y no se ven afectados. Si sirves el panel en una dirección LAN o detrás de un proxy para que las aprobaciones lleguen a un teléfono, establece AGENTBUS_URL (o --url) a ese origen público; de todos modos, es de donde se construyen los enlaces de aprobación.

Desarrollo

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

TypeScript se ejecuta directamente en Node 24 mediante la eliminación nativa de tipos — no hay paso de compilación ni compilador en la ruta de ejecución.

Licencia

MIT