OoderAgent 多节点 A2A 路由与管理深度揭秘

一张 MQTT 网如何养活一个 Agent 集群

当多个 Agent 分散在不同 JVM 进程、不同机器节点上，"A 帮 B 干活"就不再是方法调用，而是一次跨越网络、进程、身份与故障的远征。本文基于 ooderAgent 平台真实代码（ooder-a2a 协议栈 + ooder-pro 目录/工具层），拆解它如何用一条 MQTT 总线 + 一张权威状态表 + 一个统一寻址目录，解决多节点 A2A 的路由与管理问题。

一、从一个真实 Bug 说起：定向投递为什么"既非定向，又可能误投"

2026 年 9 月 11 日，ooderAgent 的 A2A 协议栈里修掉了一个极具代表性的缺陷。修复前的定向投递，把 Agent ID 当 Node ID 用——topic 形如 ooder/node/{agentId}/inbox，而所有节点又都订阅通配 ooder/node/+/inbox。后果是灾难性的三连：

1. 定向失效：消息发到"agentId 命名的 topic"，没有人真正按节点认领； 2. 回声：本节点发的组播/定向，可能被本节点自己再收到一次； 3. 误投：任何恰好订阅了通配符的节点都可能消费不属于自己的消息。

修复后的 A2AMessage.java 在字段注释里留下了这条设计裁决，也是全文的题眼——"谁干"与"发给谁"必须语义分离：

/**
 * ★ C′(2026-09-11) 目标**节点**ID —— 与 toAgentId 语义分离。
 *
 * 此前 publishTargeted 把 Agent ID 当 Node ID 用（topic 形如 ooder/node/{agentId}/inbox），
 * 而所有节点又都订阅通配 ooder/node/+/inbox → 定向既非定向、又可能回声/误投。
 *   toAgentId    = 执行体标识（谁干）；
 *   targetNodeId = 该执行体所在节点（发给谁）；缺省时由 AgentDirectoryPort 解析，
 *                  解析不到【不发布并 WARN】（不再静默丢失）。
 */
private String targetNodeId;

这个小小的字段背后，是一整套多节点 A2A 路由体系的缩影。要理解 ooderAgent 的解法，得先看清它的分层。

二、南北向分层：北向 HTTP 管生命周期，A2A/MQTT 管协作

ooderAgent 对"南北向"有一条明确的分界（见设计总纲与 agent-network-northbound-a2a-authority-20261001.md）：

北向协议（HTTP）管生命周期：执行体的注册/注销/名册持久化、目录查询、运维对账，全部走业务面 API。2026-10-01 完成的一次架构收敛中，寄生在 BPM 引擎节点上的"冷名册"层被整体剥离，注册权威统一归位到 A2A 栈的 AgentRosterStore——从此名册只有一个权威源。

A2A（MQTT）管协作：运行期的任务派发、响应回投、组播协作、心跳，全部走 MQTT 总线，不依赖任何点对点 HTTP 直连。

分层的意义在于：生命周期是低频、强一致、可运维审计的（适合 HTTP + 落库）；协作是高频、尽力而为、面向流的（适合消息总线）。两条通道各司其职，互不越界。

三、寻址模型：四个标识 + 一条解析链

多节点路由的第一性问题，是地址空间的设计。ooderAgent 定义了四个正交标识（distributed-a2a-design-and-config-20260918.md §3.1）：

agentId 的第一段还是命名空间（fin.* = 场景宿主本机执行体，llm.* = 独立 llm-agent 进程承载）。同一能力 fin.tax 与 llm.tax 映射到同一流程定义，但执行端 canHandle 只认本实例命名空间前缀，不跨命名空间代收——错投会被目录判为不可达，诚实失败。

Topic 约定（唯一权威）

值得注意的是"降级订阅"的设计态度：宁可告警也不假装正常。localNodeId 没配好时系统不会静默把定向退化成广播，而是明确 WARN 提示这是错的。

四、路由核心：publishTargeted 与"不误投"安全闸

全部定向投递收束在协议栈的一个方法里（A2AProtocolServiceImpl.java publishTargeted，L586-615）：

private PublishOutcome publishTargeted(A2AMessage message) {
    if (message.getToAgentId() == null) {
        return new PublishOutcome(false, "toAgentId 为空，无法定向投递");
    }
    A2aAgentIdentity.sign(message);            // P1: 定向投递统一签名，strict 接收端才不会拒收
    ...
    String targetNodeId = resolveTargetNodeId(message);
    if (targetNodeId == null || targetNodeId.isEmpty()) {
        // 解析不到目标节点：不发布 + WARN（每个 agentId 只告警一次）+ 落 UNDELIVERABLE
        return new PublishOutcome(false, "无法解析目标节点（agent=" + message.getToAgentId() + "）…");
    }
    if (localNodeId.equals(targetNodeId)) {
        // 目标即本节点：跳过 MQTT，本地 handler 已消费
        return new PublishOutcome(true, null);
    }
    String topic = MqttEventTransport.targetedTopic(targetNodeId);   // ooder/node/{nodeId}/inbox
    boolean ok = mqttTransport.publish(topic, wrapPayload(message));
    return new PublishOutcome(ok, ok ? null : "MQTT 发布失败（topic=" + topic + "）");
}

目标节点的解析只有两级，且优先级明确（resolveTargetNodeId，L617-635）：

1. 显式 message.targetNodeId 优先——调用方（如统一寻址服务）解析好后直接声明； 2. 否则查执行体目录 AgentDirectoryPort.find(toAgentId).nodeId； 3. 仍解析不到 → 不发布，出站行落 UNDELIVERABLE 并写明原因。

这里有一条极易被忽视的安全闸：不误投。目标节点解析不出来时，系统绝不"退回通配广播搏一把"——宁可 UNDELIVERABLE 让失败可见，也不把消息撒进全网赌运气。这条闸配合"自环过滤"（下节），构成多节点投递的确定性下界。

与之配套的是双通道信封：所有 MQTT 载荷包裹为 {"protocol":"a2a","version":"…","message":{…}}，接收端只处理 protocol=a2a 的负载，避免与同一总线上其他协议串线。

五、状态机：一张 a2a_message 表管到底

分布式系统里，路由的"可管理性"最终要落到状态可观测。ooderAgent 的选择是：协议侧 a2a_message 表是唯一权威状态机，会话侧消息只是引用视图。出站状态机（A2AProtocolServiceImpl.java sendMessage，L790-857）：

// 出站状态常量（L96-104）：SENT / LOCAL_CONSUMED / PUBLISHED / UNDELIVERABLE / FAILED
// 入站一律 direction=RECV, status=RECV
if (handledLocally) {
    markSendStatus(message, STATUS_LOCAL_CONSUMED, null);
} else {
    PublishOutcome outcome = publishTargeted(message);
    if (outcome.published) {
        markSendStatus(message, STATUS_PUBLISHED, null);
    } else {
        // 本地无消费者 + 定向投递失败 = 无法投递（失败原因写进 error，供面板/探针可见）
        markSendStatus(message, STATUS_UNDELIVERABLE, outcome.reason);
    }
}

三个设计取舍值得点出：

· PUBLISHED 的语义是诚实的：它只代表消息进入了 broker 发送队列（QoS1），不承诺对端收到。这种"不夸大"的语义让运维面板不会误导人。

· 失败原因随行：PublishOutcome 携带 reason（如"MQTT 未启用或未连接"、"无法解析目标节点"），写入 a2a_message.error 并触发 a2a_failed 事件——失败不是一行干巴巴的状态码，而是可诊断的证据。

· 请求-响应的本地闭环：本节点发出的 TASK_RESPONSE 若命中 pendingRequests，直接完成 future 并记 LOCAL_CONSUMED（L802-813）。修复注释里写得很清楚：此前回填只挂在 MQTT 入站回环路径上，MQTT 未启用时 sendRequest 的 future 永不完成——请求-响应假超时。

六、幂等与自环：两次真实事故铸就的两道闸

闸一：handledLocally —— 单次派发被消费 2 次的事故

2026-09-12，d22 探针实测发现 [A2A-Local] 计数 0→2：本地 handler 已经直接消费的消息，又被交给 RouteAgent → MessageRouter → RoutingTable 分发，命中了同一个 handler。执行端因此重复执行。修复只有四行逻辑，却是一类分布式问题的通用解：

// ★ 2026-09-12 缺陷修复：本地 handler 已直接消费时，不再交给 RouteAgent 分发。
//   否则 RouteAgent → MessageRouter → RoutingTable 会命中同一个 handler，
//   导致单次派发被消费 2 次（d22 探针实测 [A2A-Local] 计数 0→2）。
if (!handledLocally && routeAgent != null) {
    routeAgent.dispatch(message);
}

幂等的第一性原则：本地能消费的绝不进总线，进了总线的绝不二次分发。

闸二：自环过滤 —— 心跳的"身份改判"

isSelfOriginated（L653-668）负责把"自己发的消息"拦在入站之外，但它经历了一次精细的改判：

· 一般消息：fromAgentId == 本节点 nodeId，或 from 是本节点已注册执行体 → 自环，丢弃； · 心跳例外（F1，2026-09-19）：handlers 里会包含"名册内远端执行体"的本地占位 handler（宿主启动期为目录内每个 agentId 注册），用它判自环会把远端心跳全部误杀，名册永远"静态在线"； · 最终方案（F6）：心跳发布方在 header 声明 originNodeId，接收方只比较节点身份：

private boolean isSelfOriginated(A2AMessage message) {
    if (A2AMessageType.HEARTBEAT.equals(message.getMessageType())) {
        Object origin = message.getHeader("originNodeId");
        return origin != null && localNodeId.equals(String.valueOf(origin));
    }
    ...
    return handlers.containsKey(from);
}

这两道闸合起来的效果：同一条消息，从任何路径走，最多被一个消费者执行一次；节点自己永远听不到自己的回声。

七、目录服务：多节点寻址的"总机"

有了 topic 和状态机，还差最关键一环："资金日报"这个人类诉求，到底对应哪个节点的哪个执行体？这就是统一寻址目录的职责（AgentDirectoryService.java）。

四级解析，失败不回退

resolve() 的分支顺序就是它的世界观（L104-210）：

1. 显式 targetNodeId 优先：指定了节点就只在该节点的执行体内解析，未命中直接 UNDELIVERABLE——绝不静默回退到其他节点（避免"显式指定 A 却投到 B"）； 2. mention 别名匹配：@资金日报 四级匹配（精确 agentId → 别名表 → 能力段后缀 → 包含）； 3. pid 反查：流程实例 ID → SkillFlowEngine 查 definitionId → 场景绑定执行体； 4. sceneId 直配。

每次失败都携带候选列表返回，"未命中"与"命中但投递失败"语义分明——这是给 LLM 和运维看的错误消息设计。

目录联邦与三重防漂移

allSpecs()（L285-337）把目录装成一份"远端优先"的合并视图，每一层都在防一类真实事故：

// ① 目录端口（含远端节点执行体 + nodeId）——远端 fin.* 优先
// ② 本节点能力规格（补 sceneId 与本地执行体）——目录已有者保留目录 nodeId
// ③ ★ 按能力段去重并优先当前命名空间
//    —— 命名空间切换后 agent_roster 会残留旧名（如 8018 由 llm→fin 后 llm.* 仍在册），
//      不去重会把 @资金日报 解析到 stale 的 llm.bank-statement（实测缺陷）
return preferNamespace(merged);

三重防漂移，对应三类多节点环境的经典病：

· 远端优先：同一能力段若远端节点已有 fin.*，绝不解析给本节点无消费方的同名执行体； · 目录携带 nodeId：解析结果天然带着"该投给谁"； · 命名空间去重：同一能力只保留一条，当前命名空间胜出——名册残留旧名不再劫持路由。

集群对账：RosterNodeConsistency

名册是持久的（a2a-agents.json，重启恢复），集群拓扑是变化的（节点会退役、nodeId 会变）。两者一错位，路由就会投往不存在的节点。新类 RosterNodeConsistency.java 就是干这个的：

· 拉取集群权威节点集（RouteRegistry.urlOf("cluster", …) → /api/cluster/nodes，即 CLUSTER_NODE.NODE_ID）； · 对名册中每条 nodeId 分类：OK（在集群中）/ STALE（集群中已不存在）/ UNKNOWN（集群数据不可达，降级不误判）； · 启动期阻塞校验一次（A2aAgentRosterSeeder 加载名册后调用 refreshBlocking()），运行期 TTL 缓存异步刷新；陈旧条目标记 stale=true。

配合运维端点（A2aOpsController.java），多节点管理就有了完整闭环：

"路由数据健康"第一次成为可查询、可告警的一等公民，而不是藏在日志里的事后考古。

八、北向入口：LLM 工具如何优雅地跨节点派任务

A2aSendTool.java 是 LLM 在 FC-Loop 中调用 a2a_send 的北向入口，它身上叠着两个后来才补齐的关键设计：

补丁一：replyNodeId——没有它，跨节点响应必死

请求头必须带 replyNodeId=本节点，执行端才能把 TASK_RESPONSE 定向回投到 ooder/node/{本节点}/inbox（L183-193）：

// ★ 2026-09-28（跨节点应答可达性修复）：缺失时跨节点响应必 UNDELIVERABLE，
//   本端 pending future 只能等超时。与 P2aDispatchService 同口径（唯一实现，避免两处漂移）。
String localNodeId = a2aProtocolService.getLocalNodeId();
if (localNodeId != null && !localNodeId.trim().isEmpty()) {
    request.setHeader("replyNodeId", localNodeId.trim());
}

这正是分布式 A2A 审计（2026-09-28）列出的 P0 缺陷：审计发现 A2aSendTool 未设置 replyNodeId，而 P2aDispatchService、A2aOpsController 都有——跨节点请求能发出去，响应永远回不来，只能假超时。"有去无回"比"发不出去"更隐蔽，也更需要工具层的自我审查。

补丁二：P4 统一寻址——消除"绕过 resolve 的口径分裂"

工具自己解析出的节点可能与目录权威不一致。P4（2026-10-01）把 a2a_send 接入 AgentDirectoryService.resolve（L195-219）：

// · resolve 命中远端节点 → 显式写入 request.targetNodeId（协议栈优先采纳）；
// · 命中本节点/本地持能   → 不设 targetNodeId，保持本地消费；
// · resolve 未命中       → 不静默回退也不硬失败，交回协议栈目录兜底。
if (agentDirectoryService != null) {
    Map<String, Object> resolved = agentDirectoryService.resolve(agentId, null, null);
    String targetNodeId = nodeIdOf(resolved);
    if (targetNodeId != null && !localNodeId.equals(targetNodeId)) {
        request.setTargetNodeId(targetNodeId);
    }
}

从此寻址只有一条权威链：工具层 resolve → 显式 targetNodeId → 协议栈目录反查 → 解析不到即 UNDELIVERABLE。任何一层都不会再各说各话。

同步等待与超时降级也很克制：sendRequest(request).get(timeoutMs + 5000)，超时返回"执行端回填超时（任务可能已受理，可用 a2a_query 稍后回查）"——不吞掉"任务可能在路上"的可能性，把判断权交还 LLM。

可观测性：SSE 事件原样透传

协议侧每次状态推进都会 emit 事件，SseA2AEventPort.java 把 a2a_message/a2a_failed 推给浏览器，路由优先级为 conversationId → sceneGroupId → sessionId。关键纪律：broadcastToConversation 用 event().name(eventName) 原样透传事件名，前端收到的就是协议事件本名；只有无匹配 SSE 连接时才降级为 skill_progress 通道。历史教训是事件经转发通道改名后，前端按名消费的契约即告断裂——所以"透传不改名"被写成了硬约束。

九、南向接入与鉴权：服务身份的三件套

南向的执行体和代理调用，不经过用户会话，必须有独立于用户体系的信任模型：

· X-OODER-Source：声明调用来源（如 studio），必须在 trusted-sources 白名单内（缺省 studio,aiserver,bpm-server,scene-engine,im-ai）； · 统一服务令牌：-Dooder.bpm.system.token 下发，各节点配置同一值，保证跨服务调用鉴权通过； · X-OODER-Actor 与目标一致性：目标 userId 为空时只要求凭据有效（共享端点）；有声明时要求 actor 与 userId 一致——避免误拒合法的服务态调用，也堵住"带凭据冒充任意用户"。

南向代理 CodeAgentProxyController.java 则展示了边界的克制：只转发白名单路径、目标固定 ooder.codeagent.base-url、不透传用户身份令牌、只带 X-OODER-Source: studio、未配置上游返回 503。南向通道是服务间的事，用户的会话身份止步于协议边界。

十、诚实的边界：审计留下的已知极限

一篇深度揭秘如果只讲成绩就是广告。2026-09-28 的分布式 A2A 审计同样留下了清晰的边界清单——它们是这套体系的"已知未知"：

把边界写进设计文档而不是埋进日志，本身就是这套体系的治理哲学：每一个"做不到"都被显式命名，而不是等着被误认为"做到了"。

十一、结语：三条设计哲学

回看整个多节点 A2A 路由体系，从 C′ 的语义分离到 P4 的统一寻址，反复出现的是三条原则：

1. 显式优于隐式——targetNodeId 与 toAgentId 分离、显式节点优先且不回退、replyNodeId 显式声明、originNodeId 显式声明。所有"猜"的空间都被逐个消灭。

2. 诚实失败优于静默误投——解析不到目标就不发布（UNDELIVERABLE + WARN + 失败原因入库），绝不退回广播赌运气；PUBLISHED 只承诺进入队列不冒充送达；超时降级时告诉 LLM"任务可能已受理"。

3. 单一权威源——状态以协议侧 a2a_message 表为权威（会话侧只是视图）；寻址以 AgentDirectoryService 为权威（工具层不得自行解析）；名册以 A2A 栈 AgentRosterStore 为权威（2026-10-01 完成 BPM 冷名册剥离）。

多节点 A2A 的路由与管理，本质上是在"网络的不可靠"与"业务的确定性"之间架桥。ooderAgent 的答案是：用一条总线消灭直连，用一张状态表消灭黑箱，用一个目录消灭猜测，用两道闸消灭重复——然后把剩下做不到的事，诚实地写下来。

本文基于 ooderAgent 平台源码与设计文档撰写