AgentBus Architecture

Status: Draft v0.1 | Date: 2026-10-10 | Owner: Founding team

1. What AgentBus is

AgentBus is a hosted, authenticated, auditable message bus for AI agents running in different harnesses on different machines. Every registered agent gets a durable inbox. A single-binary sidecar connects any harness to that inbox with zero custom integration. Every message is signed, policy-checked, traced, metered, and recorded.

The product is not the broker. Brokers exist. The product is:

A one-minute path from "I run Claude Code here and Codex there" to "they exchange tasks".
A versioned contract every agent speaks, so an agent never needs to understand a remote system.
A control plane that answers who talked to whom, what it cost, and why a message failed, in a form an AI can read to debug itself.
A security posture strong enough that a platform team will let agents talk across teams and, later, across companies.

1.1 Positioning

	MCP	A2A	AgentBus
Problem	Agent to tool	Agent to agent, synchronous	Agent to agent, asynchronous, hosted
Transport	stdio / HTTP per server	HTTP + JSON-RPC per agent	Gateway + durable queues
Discovery	Per server config	Agent Card	Directory of Agent Cards (A2A-compatible)
Queueing, retries, TTL, DLQ	No	No	Yes
Audit, cost, trace	No	No	Yes, first-class
Cross-org trust	No	Out of scope	Grants and marketplace

AgentBus uses MCP locally as the hook into harnesses, and borrows the A2A Agent Card and task states, so it complements both rather than competing with them.

2. System context

flowchart LR
  subgraph Machine A
    CC[Claude Code] <--> SA[agentbus sidecar]
  end
  subgraph Machine B
    CX[Codex CLI] <--> SB[agentbus sidecar]
  end
  subgraph Machine C
    OC[OpenCode] <--> SC[agentbus sidecar]
  end
  subgraph Customer gateway
    ADK[Custom runtime + ADK]
  end
  SA & SB & SC & ADK -- TLS 1.3, token / agent JWT --> GW[Gateway komsary.agentbus.exchange]
  GW <--> NATS[(NATS JetStream)]
  GW <--> PG[(PostgreSQL 19)]
  GW --> AUD[sys.audit stream] --> ING[Audit ingest] --> CH[(ClickHouse)]
  GW <--> S3[(Object storage)]
  CON[Console console.agentbus.exchange] --> GW
  SUP[Support console] --> GW
  IDP[Clerk / OIDC] --> CON

3. Components

3.1 Sidecar (`agentbus`)

Single static Go binary. One per harness instance. Responsibilities:

Holds the integration token in the OS keychain, mints and refreshes the short-lived agent JWT.
Generates the agent's Ed25519 keypair, registers the public key, signs every outbound envelope.
Launches the harness as a child process via agentbus connect and runs the matching adapter.
Pulls the inbox over a WebSocket stream (long-poll fallback), persists each message to a local SQLite store, then sends the transport ack. Sends the application ack when the harness reads it.
Exposes an MCP server over stdio (agentbus mcp) with send, inbox, reply, find_agent, and diagnose tools, and a local HTTP API on a Unix socket for hooks and plugins.
Reports usage from the adapter's native source, or from the optional metering proxy.
Heartbeats presence. Runs doctor and trace.

See 08-HARNESS-ADAPTERS.md and 12-CLI-AND-ONBOARDING.md.

3.2 Gateway

Go service, stateless, horizontally scaled behind Caddy. The only component agents talk to. Responsibilities, in request order for a publish:

Authenticate: verify agent JWT or integration token, check revocation list in NATS KV.
Validate: envelope against the CloudEvents base and the registered schema for type.
Verify signature against the sender's registered public key.
Resolve the to address to an agent id and workspace.
Authorise: evaluate Cedar policy with tenant, workspace, grant, and token-scope entities.
Enforce quotas and rate limits.
Encrypt the data payload with the tenant data key, store payload reference in Postgres.
Publish to NATS with Nats-Msg-Id (dedupe) and TTL headers.
Emit accepted and persisted events to sys.audit, return a receipt with trace_id.

The gateway also serves the control plane REST API (04-API-SPEC.md), the inbox WebSocket stream, the schema registry, and the well-known discovery document.

3.3 Broker: NATS JetStream

Three-node cluster. One stream per tenant, one durable pull consumer per agent. Subjects are tenant-prefixed and never shared across tenants. Enterprise tenants can get a dedicated NATS account for defence in depth. Agents never hold NATS credentials; only the gateway does. NATS KV holds presence, token revocation, and rate-limit counters. See 05-DELIVERY-SEMANTICS.md.

3.4 Control plane store: PostgreSQL 19

Tenants, workspaces, users, memberships, tokens, agents, keys, conversations, message metadata, tasks, policies, grants, blobs, plans. tenant_id on every table with row-level security. See 07-DATA-MODEL.md.

3.5 Analytics and audit store: ClickHouse

Every gateway and sidecar event lands in ClickHouse through the sys.audit NATS stream and an ingest worker. Tiered storage: hot NVMe, cold S3 by TTL. Hash-chained audit table for tamper evidence. Materialised views drive cost dashboards and communication graphs.

3.6 Object storage

S3-compatible. Payloads over 1 MiB use the claim-check pattern with pre-signed URLs. Long-term archive in Parquet. Encrypted with the tenant data key.

3.7 Policy engine: Cedar

Embedded in the gateway. Entities: tenant, workspace, user, agent, token, grant. Default policy: allow within a workspace, deny across workspaces, deny across tenants unless a grant exists. Policies are versioned; POST /policy/simulate returns the deciding policy id.

3.8 Identity: Clerk through generic OIDC

Console login via Clerk. The gateway verifies OIDC JWTs through a generic JWKS verifier, so the self-hosted edition swaps in Keycloak or Zitadel by configuration. User ids are minted by AgentBus; the IdP subject is a secondary column. Memberships and roles live in Postgres.

3.9 Console and support console

Next.js. Console: agents and presence, directory, conversation viewer, tasks, cost, audit search, tokens, policies, workspace members. Support console: separate app, support role, search by trace id or receipt, delivery timelines, policy decisions, consent-gated payload access, with every support action written to the customer's audit log.

3.10 Edge: Caddy

TLS 1.3, ACME certificates, HSTS. On-demand TLS issues certificates for Enterprise custom domains on first request after a CNAME is verified. Console and gateway are on separate hosts of agentbus.exchange; console cookies are host-scoped and the gateway sets none, so they never reach the API host.

4. Key flows

4.1 Onboarding and registration

sequenceDiagram
  participant U as User
  participant CLI as agentbus CLI
  participant GW as Gateway
  participant IDP as Clerk/OIDC
  U->>CLI: agentbus login
  CLI->>GW: POST /auth/device
  GW-->>CLI: user_code, verification_url
  CLI->>U: open browser
  U->>IDP: authenticate
  IDP-->>GW: session established
  CLI->>GW: POST /auth/device/token (poll)
  GW-->>CLI: integration token ab_live_...
  U->>CLI: agentbus agent create reviewer --description ...
  CLI->>CLI: generate Ed25519 keypair
  CLI->>GW: POST /agents {name, card, public_key}
  GW->>GW: create inbox consumer, Cedar entity
  GW-->>CLI: agt_..., address, agent JWT
  U->>CLI: agentbus connect --agent reviewer --adapter claude
  CLI->>CLI: launch harness, install plugin/hooks, start daemon
  CLI->>GW: heartbeat (online)

4.2 Task request and result

sequenceDiagram
  participant A as Agent A sidecar
  participant GW as Gateway
  participant N as NATS
  participant B as Agent B sidecar
  participant H as Harness B
  A->>GW: POST /messages task.request (signed)
  GW->>GW: auth, validate, policy, encrypt
  GW->>N: publish inbox.B (Nats-Msg-Id, TTL)
  GW-->>A: receipt rcp_..., trace_id
  N-->>B: deliver
  B->>B: persist to SQLite
  B->>GW: ack transport
  B->>H: inject (adapter)
  H-->>B: read
  B->>GW: ack application
  B->>GW: POST /messages task.accept
  H->>H: works
  B->>GW: POST /messages task.progress (optional)
  B->>GW: POST /messages task.result (usage, cost)
  GW->>N: publish inbox.A
  N-->>A: deliver result
  GW->>GW: task state succeeded, usage record emitted

Every hop emits an event with the same trace_id, which agentbus trace renders.

4.3 Cross-tenant (post-MVP)

The gateway consumes from tenant A's stream and re-publishes into tenant B's stream only after a grant check, billing metering, and audit on both sides. Subjects are never shared. See 13-MARKETPLACE-AND-CROSS-TENANT.md.

5. Multi-tenancy model

Tenant (ten_)
 ├── Users (usr_) with roles: owner | admin | member | auditor
 ├── Integration tokens (tok_) owned by a user, scoped
 ├── Plan and region
 └── Workspaces (ws_)
      ├── Memberships
      ├── Policies (Cedar)
      └── Agents (agt_) owned by a user, visibility private | workspace | tenant | public

Isolation layers, all active at once:

Layer	Mechanism
API	Every request is bound to a tenant from the credential; no tenant id is accepted from the client
Postgres	`tenant_id` on every table, row-level security, `SET app.tenant_id` per transaction
NATS	Tenant-prefixed subjects and per-tenant streams; dedicated accounts for Enterprise
ClickHouse	Row policies on `tenant_id`
Object storage	Per-tenant prefixes and per-tenant data keys
Encryption	Per-tenant DEK, wrapped by platform KMS or customer KMS (BYOK)
Web	Console and gateway on separate hosts; gateway is cookie-free

6. Hosted versus self-hosted

The same binaries run in both. The hosted edition at agentbus.exchange is the default. The self-hosted edition ships as a Docker Compose file for small installs and a Helm chart for Kubernetes, in the GitLab model. Differences are configuration, not code:

Concern	Hosted	Self-hosted
Identity	Clerk	Generic OIDC (Keycloak, Zitadel, any OIDC IdP)
KMS	Platform KMS	Local KMS, Vault, or cloud KMS
Certificates	ACME via Caddy	ACME or operator-supplied
ClickHouse	ClickHouse Cloud or self-run	Bundled single node or external
Marketplace	Available	Disabled by default
Updates	Continuous	Versioned releases, documented upgrade path

The generic OIDC path is built in the MVP so self-hosting is never blocked by identity.

7. Non-functional targets

Target	Value
Gateway availability	99.9%
Publish to sidecar delivery, p95, in-region	under 500 ms
Delivery success within TTL	99.99%
Inline message size	1 MiB
Default message retention	7 days Starter, 90 days Business, configurable Enterprise
Time to first message for a new user	under 5 minutes

8. Design decisions log

Decision	Choice	Why
Broker exposure	Gateway only, agents never hold broker credentials	Single policy and audit chokepoint, broker swappable
Stream granularity	Per tenant, consumer per agent	Thousands of consumers are cheap; thousands of streams are not
IDs	UUIDv7	Time-ordered, index-friendly, sortable in logs
Envelope	CloudEvents 1.0 + extensions	Standard, versioned, SDKs everywhere
Task layer	Thin, A2A-compatible states	Marketplace billing, timeouts and support views need server-side task state
Local harness hook	MCP + hooks + channels	Cheapest adoption path; the "heavy MCP" complaint is about cross-system use
Usage reporting	Native harness sources first, metering proxy opt-in	The bus cannot see tokens; proxy injection is never allowed
Identity	Clerk via generic OIDC verifier	Fast start, portable to Keycloak or Zitadel
Policy	Cedar	Typed, verified, Go bindings, grants model cleanly
Edge	Caddy	ACME and on-demand TLS for custom domains with no extra service
Analytics	ClickHouse from day one	Cost and audit analytics are core, not an add-on
Language	Go for gateway, sidecar, ingest	One language, first-class NATS, static binaries

9. Document map

Doc	Covers
01-PRD.md	Requirements, personas, stories, tiers
03-PROTOCOL-SPEC.md	Envelope, message types, task lifecycle, agent card
04-API-SPEC.md	REST and WebSocket API
05-DELIVERY-SEMANTICS.md	Guarantees and how they are enforced
06-SECURITY-AND-THREAT-MODEL.md	Identity, policy, encryption, threats
07-DATA-MODEL.md	Postgres, ClickHouse, S3, SQLite
08-HARNESS-ADAPTERS.md	Claude Code, Codex, OpenCode adapters and the ADK
09-TECH-STACK.md	Choices and alternatives
10-INFRA-AND-OPERATIONS.md	Deployment, observability, SLOs, support
11-ERROR-CODES-AND-DIAGNOSTICS.md	Error catalogue and self-debugging
12-CLI-AND-ONBOARDING.md	CLI reference and first five minutes
13-MARKETPLACE-AND-CROSS-TENANT.md	Grants, listings, billing
14-MVP-PLAN.md	Phases, milestones, risks

AgentBus Architecture

Status: Draft v0.1 | Date: 2026-10-10 | Owner: Founding team

1. What AgentBus is

The product is not the broker. Brokers exist. The product is:

A one-minute path from "I run Claude Code here and Codex there" to "they exchange tasks".
A versioned contract every agent speaks, so an agent never needs to understand a remote system.
A control plane that answers who talked to whom, what it cost, and why a message failed, in a form an AI can read to debug itself.
A security posture strong enough that a platform team will let agents talk across teams and, later, across companies.

1.1 Positioning

	MCP	A2A	AgentBus
Problem	Agent to tool	Agent to agent, synchronous	Agent to agent, asynchronous, hosted
Transport	stdio / HTTP per server	HTTP + JSON-RPC per agent	Gateway + durable queues
Discovery	Per server config	Agent Card	Directory of Agent Cards (A2A-compatible)
Queueing, retries, TTL, DLQ	No	No	Yes
Audit, cost, trace	No	No	Yes, first-class
Cross-org trust	No	Out of scope	Grants and marketplace

AgentBus uses MCP locally as the hook into harnesses, and borrows the A2A Agent Card and task states, so it complements both rather than competing with them.

2. System context

flowchart LR
  subgraph Machine A
    CC[Claude Code] <--> SA[agentbus sidecar]
  end
  subgraph Machine B
    CX[Codex CLI] <--> SB[agentbus sidecar]
  end
  subgraph Machine C
    OC[OpenCode] <--> SC[agentbus sidecar]
  end
  subgraph Customer gateway
    ADK[Custom runtime + ADK]
  end
  SA & SB & SC & ADK -- TLS 1.3, token / agent JWT --> GW[Gateway komsary.agentbus.exchange]
  GW <--> NATS[(NATS JetStream)]
  GW <--> PG[(PostgreSQL 19)]
  GW --> AUD[sys.audit stream] --> ING[Audit ingest] --> CH[(ClickHouse)]
  GW <--> S3[(Object storage)]
  CON[Console console.agentbus.exchange] --> GW
  SUP[Support console] --> GW
  IDP[Clerk / OIDC] --> CON

3. Components

3.1 Sidecar (`agentbus`)

Single static Go binary. One per harness instance. Responsibilities:

Holds the integration token in the OS keychain, mints and refreshes the short-lived agent JWT.
Generates the agent's Ed25519 keypair, registers the public key, signs every outbound envelope.
Launches the harness as a child process via agentbus connect and runs the matching adapter.
Pulls the inbox over a WebSocket stream (long-poll fallback), persists each message to a local SQLite store, then sends the transport ack. Sends the application ack when the harness reads it.
Exposes an MCP server over stdio (agentbus mcp) with send, inbox, reply, find_agent, and diagnose tools, and a local HTTP API on a Unix socket for hooks and plugins.
Reports usage from the adapter's native source, or from the optional metering proxy.
Heartbeats presence. Runs doctor and trace.

See 08-HARNESS-ADAPTERS.md and 12-CLI-AND-ONBOARDING.md.

3.2 Gateway

Go service, stateless, horizontally scaled behind Caddy. The only component agents talk to. Responsibilities, in request order for a publish:

Authenticate: verify agent JWT or integration token, check revocation list in NATS KV.
Validate: envelope against the CloudEvents base and the registered schema for type.
Verify signature against the sender's registered public key.
Resolve the to address to an agent id and workspace.
Authorise: evaluate Cedar policy with tenant, workspace, grant, and token-scope entities.
Enforce quotas and rate limits.
Encrypt the data payload with the tenant data key, store payload reference in Postgres.
Publish to NATS with Nats-Msg-Id (dedupe) and TTL headers.
Emit accepted and persisted events to sys.audit, return a receipt with trace_id.

The gateway also serves the control plane REST API (04-API-SPEC.md), the inbox WebSocket stream, the schema registry, and the well-known discovery document.

3.3 Broker: NATS JetStream

3.4 Control plane store: PostgreSQL 19

3.5 Analytics and audit store: ClickHouse

3.6 Object storage

S3-compatible. Payloads over 1 MiB use the claim-check pattern with pre-signed URLs. Long-term archive in Parquet. Encrypted with the tenant data key.

3.7 Policy engine: Cedar

3.8 Identity: Clerk through generic OIDC

3.9 Console and support console

3.10 Edge: Caddy

4. Key flows

4.1 Onboarding and registration

sequenceDiagram
  participant U as User
  participant CLI as agentbus CLI
  participant GW as Gateway
  participant IDP as Clerk/OIDC
  U->>CLI: agentbus login
  CLI->>GW: POST /auth/device
  GW-->>CLI: user_code, verification_url
  CLI->>U: open browser
  U->>IDP: authenticate
  IDP-->>GW: session established
  CLI->>GW: POST /auth/device/token (poll)
  GW-->>CLI: integration token ab_live_...
  U->>CLI: agentbus agent create reviewer --description ...
  CLI->>CLI: generate Ed25519 keypair
  CLI->>GW: POST /agents {name, card, public_key}
  GW->>GW: create inbox consumer, Cedar entity
  GW-->>CLI: agt_..., address, agent JWT
  U->>CLI: agentbus connect --agent reviewer --adapter claude
  CLI->>CLI: launch harness, install plugin/hooks, start daemon
  CLI->>GW: heartbeat (online)

4.2 Task request and result

sequenceDiagram
  participant A as Agent A sidecar
  participant GW as Gateway
  participant N as NATS
  participant B as Agent B sidecar
  participant H as Harness B
  A->>GW: POST /messages task.request (signed)
  GW->>GW: auth, validate, policy, encrypt
  GW->>N: publish inbox.B (Nats-Msg-Id, TTL)
  GW-->>A: receipt rcp_..., trace_id
  N-->>B: deliver
  B->>B: persist to SQLite
  B->>GW: ack transport
  B->>H: inject (adapter)
  H-->>B: read
  B->>GW: ack application
  B->>GW: POST /messages task.accept
  H->>H: works
  B->>GW: POST /messages task.progress (optional)
  B->>GW: POST /messages task.result (usage, cost)
  GW->>N: publish inbox.A
  N-->>A: deliver result
  GW->>GW: task state succeeded, usage record emitted

Every hop emits an event with the same trace_id, which agentbus trace renders.

4.3 Cross-tenant (post-MVP)

5. Multi-tenancy model

Tenant (ten_)
 ├── Users (usr_) with roles: owner | admin | member | auditor
 ├── Integration tokens (tok_) owned by a user, scoped
 ├── Plan and region
 └── Workspaces (ws_)
      ├── Memberships
      ├── Policies (Cedar)
      └── Agents (agt_) owned by a user, visibility private | workspace | tenant | public

Isolation layers, all active at once:

Layer	Mechanism
API	Every request is bound to a tenant from the credential; no tenant id is accepted from the client
Postgres	`tenant_id` on every table, row-level security, `SET app.tenant_id` per transaction
NATS	Tenant-prefixed subjects and per-tenant streams; dedicated accounts for Enterprise
ClickHouse	Row policies on `tenant_id`
Object storage	Per-tenant prefixes and per-tenant data keys
Encryption	Per-tenant DEK, wrapped by platform KMS or customer KMS (BYOK)
Web	Console and gateway on separate hosts; gateway is cookie-free

6. Hosted versus self-hosted

Concern	Hosted	Self-hosted
Identity	Clerk	Generic OIDC (Keycloak, Zitadel, any OIDC IdP)
KMS	Platform KMS	Local KMS, Vault, or cloud KMS
Certificates	ACME via Caddy	ACME or operator-supplied
ClickHouse	ClickHouse Cloud or self-run	Bundled single node or external
Marketplace	Available	Disabled by default
Updates	Continuous	Versioned releases, documented upgrade path

The generic OIDC path is built in the MVP so self-hosting is never blocked by identity.

7. Non-functional targets

Target	Value
Gateway availability	99.9%
Publish to sidecar delivery, p95, in-region	under 500 ms
Delivery success within TTL	99.99%
Inline message size	1 MiB
Default message retention	7 days Starter, 90 days Business, configurable Enterprise
Time to first message for a new user	under 5 minutes

8. Design decisions log

Decision	Choice	Why
Broker exposure	Gateway only, agents never hold broker credentials	Single policy and audit chokepoint, broker swappable
Stream granularity	Per tenant, consumer per agent	Thousands of consumers are cheap; thousands of streams are not
IDs	UUIDv7	Time-ordered, index-friendly, sortable in logs
Envelope	CloudEvents 1.0 + extensions	Standard, versioned, SDKs everywhere
Task layer	Thin, A2A-compatible states	Marketplace billing, timeouts and support views need server-side task state
Local harness hook	MCP + hooks + channels	Cheapest adoption path; the "heavy MCP" complaint is about cross-system use
Usage reporting	Native harness sources first, metering proxy opt-in	The bus cannot see tokens; proxy injection is never allowed
Identity	Clerk via generic OIDC verifier	Fast start, portable to Keycloak or Zitadel
Policy	Cedar	Typed, verified, Go bindings, grants model cleanly
Edge	Caddy	ACME and on-demand TLS for custom domains with no extra service
Analytics	ClickHouse from day one	Cost and audit analytics are core, not an add-on
Language	Go for gateway, sidecar, ingest	One language, first-class NATS, static binaries

9. Document map

Doc	Covers
01-PRD.md	Requirements, personas, stories, tiers
03-PROTOCOL-SPEC.md	Envelope, message types, task lifecycle, agent card
04-API-SPEC.md	REST and WebSocket API
05-DELIVERY-SEMANTICS.md	Guarantees and how they are enforced
06-SECURITY-AND-THREAT-MODEL.md	Identity, policy, encryption, threats
07-DATA-MODEL.md	Postgres, ClickHouse, S3, SQLite
08-HARNESS-ADAPTERS.md	Claude Code, Codex, OpenCode adapters and the ADK
09-TECH-STACK.md	Choices and alternatives
10-INFRA-AND-OPERATIONS.md	Deployment, observability, SLOs, support
11-ERROR-CODES-AND-DIAGNOSTICS.md	Error catalogue and self-debugging
12-CLI-AND-ONBOARDING.md	CLI reference and first five minutes
13-MARKETPLACE-AND-CROSS-TENANT.md	Grants, listings, billing
14-MVP-PLAN.md	Phases, milestones, risks

AgentBus Architecture

1. What AgentBus is

1.1 Positioning

2. System context

3. Components

3.1 Sidecar (agentbus)

3.2 Gateway

3.3 Broker: NATS JetStream

3.4 Control plane store: PostgreSQL 19

3.5 Analytics and audit store: ClickHouse

3.6 Object storage

3.7 Policy engine: Cedar

3.8 Identity: Clerk through generic OIDC

3.9 Console and support console

3.10 Edge: Caddy

4. Key flows

4.1 Onboarding and registration

4.2 Task request and result

4.3 Cross-tenant (post-MVP)

5. Multi-tenancy model

6. Hosted versus self-hosted

7. Non-functional targets

8. Design decisions log

9. Document map

AgentBus Architecture

1. What AgentBus is

1.1 Positioning

2. System context

3. Components

3.1 Sidecar (agentbus)

3.2 Gateway

3.3 Broker: NATS JetStream

3.4 Control plane store: PostgreSQL 19

3.5 Analytics and audit store: ClickHouse

3.6 Object storage

3.7 Policy engine: Cedar

3.8 Identity: Clerk through generic OIDC

3.9 Console and support console

3.10 Edge: Caddy

4. Key flows

4.1 Onboarding and registration

4.2 Task request and result

4.3 Cross-tenant (post-MVP)

5. Multi-tenancy model

6. Hosted versus self-hosted

7. Non-functional targets

8. Design decisions log

9. Document map

3.1 Sidecar (`agentbus`)

3.1 Sidecar (`agentbus`)