文档

核心概念

Janus 是一个持久化 Agent 任务代理（Broker）。它位于 Agent 之间，以治理、路由和可观测性保障任务的可靠交付。

架构总览

Janus 分为四层。外部客户端通过协议网关接入；无状态的核心服务负责任务生命周期、治理与后台 Worker；所有持久状态都外部化。每一层都可以独立扩展。

接入层只做协议适配。核心服务拥有状态机与治理。PostgreSQL 是事实来源；NATS 承载投递与事件；Redis 只保存心跳与速率计数。

接入层只做协议适配和认证 —— 不持有任何业务逻辑。核心服务拥有任务状态机、策略执行、预算核算和审计；它们无状态、可水平扩展。后台 Worker（Outbox 发布器、事件投影、租约扫描、心跳清扫）独立运行，通过数据库租约和幂等键协调，多个副本并行也不会重复投递。

PostgreSQL 是任务状态、事务性 outbox、预算和审计投影的事实来源。NATS JetStream 通过持久化流和按邮箱的消费者承载任务投递与领域事件。Redis 只保存 Agent 心跳和短窗口速率计数 —— 不存任何持久事实。

任务（Task）

工作的基本单位。任务携带一个不透明载荷（信封 envelope），从源 Agent 发往目标消费者。每个任务都有唯一 ID、租户作用域，以及完整的生命周期状态：

pending → claimed → in_progress → completed
                                        → failed
                                        → nacked → pending (重试)
                                                  → dlq

邮箱（Mailbox）

一个命名队列，任务在此投递。Agent 从自己拥有的邮箱拉取任务。邮箱是持久的——即使 Agent 崩溃，任务也会保留，直到 Agent 恢复并拉取它们。

关键属性：

• 作用域限定在某个租户内
• 由一个或多个 Agent 拥有（agent_id）
• 任务按优先级顺序 FIFO 拉取

租约（Lease）

Agent 拉取任务时，会获得一个限时租约。租约防止其他 Agent 抢占同一任务。如果 Agent 未确认（ACK）就崩溃：

• 租约在配置的超时时间后过期
• 任务回到 pending 状态，可被其他 Agent 重新拉取
• 幂等的 ACK/NACK 提供"至少一次"投递，且不会重复处理

信封（Envelope）

载荷包装器。包含：

• type — 消息类型标识
• payload — 实际数据（结构化 JSON）
• priority — high / normal / low
• context_refs — 对共享工件的引用（文件、图片、先前结果）

路由与能力解析

Janus 通过五种目标类型把每个任务路由到正确的 Agent：

• 直接路由 — 发布到指定 mailbox 或 agent
• 基于能力 — 设置 target_type: capability，Janus 找到声明了该能力的在线 Agent
• 团队路由 — 设置 target_type: group 投递给某个团队。团队成员关系来自每个 Agent 注册时的 team 字段——Janus 自动把团队解析为其在线成员的活跃邮箱
• 意图路由 — 设置 target_type: intent 并附自然语言描述。配置了 LLM（JANUS_LLM_ENABLED）时，Janus 将文本映射到最匹配的能力，经在线 catalog 校验后确定性路由；未配置 LLM 时降级为关键词匹配

治理（Governance）

每一次任务派发都会经过策略与预算检查：

• 策略引擎 — 谁能调用谁、使用什么数据形态
• 预算控制 — RPM / TPM / 并发限制（成本限额规划中——待可信计量落地）
• 审计轨迹 — 每一次 publish、pull、start、ack、nack 都被记录
• 人工审批 — 高风险任务可以要求手动审批

协议网关（Protocol Gateways）

Janus 原生支持多种 Agent 通信协议：

• A2A 网关 — Google Agent-to-Agent 协议（Agent Card、Task Send）
• ACP 网关 — IBM/BeeAI 的 Agent Communication Protocol（Manifest、Runs；现已并入 A2A）
• MCP 网关 — Model Context Protocol（Tools、Resources）
• REST API + gRPC — 面向 SDK 客户端的原生 Janus API

持久化模型（Durability Model）

任务被双写至 PostgreSQL（真相源）与 NATS JetStream（快速投递）。如果 Broker 进程中途崩溃：

• 已认领但未 ACK 的在途任务，其租约会过期
• outbox 机制确保 Broker 崩溃期间不会丢失任何任务
• 可通过 CLI 从死信队列手动重放

租户隔离（Tenant Isolation）

每个任务、邮箱和工件都限定在租户内。跨租户访问会被自动拒绝。所有审计事件都带有租户 ID 标签。