Documentation

Core Concepts

Janus is a durable agent task broker. It sits between agents and reliably delivers tasks with governance, routing, and observability.

Architecture Overview

Janus is layered into four planes. External clients enter through protocol gateways; stateless core services own the task lifecycle, governance, and background workers; all durable state is externalized. Every layer scales independently.

The ingress plane only adapts protocols. Core services own state machines and governance. PostgreSQL is the source of truth; NATS carries deliveries and events; Redis holds only heartbeats and rate counters.

The ingress plane does only protocol adaptation and authentication — it holds no business logic. The core services own the task state machine, policy enforcement, budget accounting, and audit; they are stateless and scale horizontally. Background workers (outbox publisher, event projector, lease scanner, heartbeat sweep) run independently and coordinate through database leases and idempotency keys, so multiple replicas never double-deliver.

PostgreSQL is the source of truth for task state, the transactional outbox, budgets, and audit projections. NATS JetStream carries task deliveries and domain events through durable streams and per-mailbox consumers. Redis holds only agent heartbeats and short-window rate counters — never durable facts.

Task

The fundamental unit of work. A task carries an opaque payload (the envelope) from a source agent to a target consumer. Every task has a unique ID, a tenant scope, and a lifecycle state:

pending → claimed → in_progress → completed
                                        → failed
                                        → nacked → pending (retry)
                                                  → dlq

Mailbox

A named queue where tasks are delivered. Agents pull tasks from a mailbox they own. Mailboxes are durable — if an agent crashes, tasks remain until the agent comes back and pulls them.

Key properties:

• Scoped to a tenant
• Owned by one or more agents (agent_id)
• Tasks are pulled FIFO within priority order

Lease

When an agent pulls a task, it receives a time-bound lease. The lease prevents other agents from claiming the same task. If the agent crashes without ACKing:

• The lease expires after the configured timeout
• The task reverts to pending and becomes available for another agent to pull
• Idempotent ACK/NACK delivers at-least-once with no duplicate processing

Envelope

The payload wrapper. Contains:

• type — message type identifier
• payload — the actual data (structured JSON)
• priority — high / normal / low
• context_refs — references to shared artifacts (files, images, previous results)

Routing & Capability Resolution

Janus routes every task to the right agent through five target types:

• Direct — publish to a specific mailbox or agent
• Capability-based — set target_type: capability and Janus finds an online agent that declares that capability
• Group — set target_type: group to deliver to a team. Group membership comes from the team field on each agent's registration — Janus resolves the team to its online members' active mailboxes automatically
• Intent — set target_type: intent with a natural-language description. With LLM configured (JANUS_LLM_ENABLED), Janus maps the text to the best matching capability, validates it against the live catalog, then routes deterministically; without LLM, a keyword matcher is used as fallback

Governance

Every task dispatch passes through policy and budget checks:

• Policy Engine — who can call whom, with what data shape
• Budget Control — RPM / TPM / concurrency limits (cost estimated from reported usage at settlement; authoritative per-model metering on the enterprise roadmap)
• Audit Trail — every publish, pull, start, ack, nack is recorded
• Human Approval — high-risk tasks can require manual approval

Protocol Gateways

Janus speaks multiple agent communication protocols natively:

• A2A Gateway — Google Agent-to-Agent protocol (Agent Card, Task Send)
• ACP Gateway — Agent Communication Protocol by IBM/BeeAI (Manifest, Runs; now merged into A2A)
• MCP Gateway — Model Context Protocol (Tools, Resources)
• REST API + gRPC — native Janus API for SDK clients

Durability Model

Tasks are dual-written to PostgreSQL (source of truth) and NATS JetStream (fast delivery). If the broker process crashes mid-flight:

• In-flight tasks that were claimed but not ACKed have their leases expire
• The outbox ensures no tasks are lost during broker crashes
• Manual replay from dead letter queue is available via CLI

Tenant Isolation

Every task, mailbox, and artifact is scoped to a tenant. Cross-tenant access is automatically denied. All audit events are tagged with tenant ID.