Documentation

Core Concepts

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

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 ensures exactly-once semantics

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 supports two dispatch modes:

• Direct — publish to a specific mailbox
• Capability-based — describe what you need, Janus finds the best agent

The Intent Resolver accepts natural language descriptions and matches them to registered agent capabilities:

client.resolve_intent("Review a Go pull request for race conditions")
# → Confidence: 0.92
# → Matched capability: "go-code-review"
# → Suggested target: "review-mb"

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 / daily cost limits
• 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 — Anthropic Communication Protocol (Manifest, Runs)
• 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.