我去年接手了一个多 Agent 协作项目三个 Agent 要配合完成用户请求一开始用的是中心化消息队列看起来简单结果在并发、消息回溯、权限隔离上连环踩坑。后来换成了 hermes peer 这套点对点通信协议通信拓扑彻底变简单会话关系也能完整表达清楚了。这篇文章我打算把 hermes peer 从传输层到语义协作层的设计拆开讲再用一个跨语言的完整案例演示落地方式。如果你正在做 Agent 编排、多进程多语言协作或者单纯对 Agent 间通信的协议设计感兴趣这篇应该能给你一份可以直接参考的实战笔记。协议本身不复杂但它解决的都是我在实际部署中真实遇到过的问题。1. 为什么 Agent 协作的第一公里总是堵在通信上1.1 中心化 Broker 模式跑不动多 Agent 的真实原因先说一个很容易被忽略的事实很多团队做 Agent 协作时第一反应是引入消息队列或者中心化 Broker让所有 Agent 都往队列里投递消息、再从队列里订阅消息。这个方案在服务数量少、交互频率低的阶段确实能跑但一旦 Agent 数量上来问题就会集中爆发。我在之前那个项目里就遇到了三个非常典型的瓶颈。第一个是单点压力。所有 Agent 之间的每一次请求都要经过 Broker 转发消息路径被强行拉长本来 A 到 B 是一跳的通信硬生生变成了 A 到 Broker 再到 B 的两跳延迟翻倍不说Broker 所在节点的 CPU 和网络带宽会最先成为瓶颈。第二个是会话关系难以表达。Agent 之间的通信往往带有明确的上下文关联比如一个检索 Agent 的结果需要关联到某个具体的用户会话中心化队列的消息模型是 topic payload它天然不擅长表达这条消息是那个会话的第几条、由谁发起、期望谁回应这类关系。第三个是故障域被放大。Broker 一旦崩了所有 Agent 之间全部失联哪怕它们之间本来可以直接通信。还有一个更深层的问题中心化 Broker 的权限控制通常颗粒度很粗。你只能在 topic 层面做读写的权限隔离但 Agent 协作中往往需要精确到谁能调用我的某个能力、谁能读取我这边的会话状态这在队列模型里几乎没法优雅实现。1.2 hermes peer 的设计定位把会话边界做薄把协议做稳hermes peer 这套协议的设计出发点恰恰就是绕开上面这些坑。它在架构上默认采用直连优先的通信模型两个 Agent 之间能直接建立会话就直接建立不走中间节点转发只有在跨网段、无法直连的场景下才借助注册中心做路由协调。名字也起得挺有意思Hermes 本来就是希腊神话里传递消息的信使作者大概是想表达协议只负责把消息稳妥地送达业务逻辑完全交给 Agent 自己这个意思。如果你用过 hermes agent 这个运行时再看 hermes peer 就会觉得顺理成章hermes agent 解决的是单个 Agent 怎么构建、怎么运行、怎么管理记忆和工具调用的问题而 hermes peer 解决的是多个 Agent 之间怎么找到对方、怎么安全通信、怎么把一次协作的过程完整串起来的问题。两者合在一起基本就是一个完整的 Agent 运行栈。整个协议的设计目标我总结下来就四个直连优先能一跳通信就不两跳减少中间链路带来的延迟和故障放大。语义显式消息不是一份无意义的字节流而是带身份、带能力、带会话上下文的结构化数据。会话可回溯一次多 Agent 协作从开始到结束所有消息都能按会话 ID 完整串起来方便日志排查和效果分析。运行时可观测协议层面就暴露节点状态、连接状态、消息投递状态不需要额外埋一堆探针。这个定位决定了后续的协议设计方向也决定了它和普通消息队列的根本区别消息队列是你发我收、解耦优先hermes peer 是直连会话、协作优先。2. 传输层拆解节点发现、握手流程与消息帧设计2.1 节点发现机制从静态配置到动态注册传输层要解决的第一个问题是 Agent 之间怎么找到彼此。hermes peer 提供了两种节点发现方式实际项目中通常会混合使用。第一种是静态配置。每个 Agent 启动时读取一份 peers 配置文件里面写明要连接的远端节点信息包括 node_id、endpointIP 加端口、以及该节点提供的能力标签。这种方式适合拓扑固定、节点地址不变的内部环境简单直接没有任何额外的注册依赖。我自己通常在开发环境用这个几个 Agent 都在同一台机器上配置文件写死就够了。第二种是动态注册。Agent 启动后先向注册中心上报自己的节点信息然后注册中心把节点的地址和能力广播给其他订阅者。这样新加入的 Agent 不需要改动已有节点的配置就能被拓扑中的其他节点发现。hermes peer 在局域网内默认走 mDNS 做自动发现跨网段则可以对接一个轻量级的注册中心本质上就是一个 KV 存储加一个变更通知。节点信息的数据结构大概是这样的node_id: agent-nlu-01 endpoint: 192.168.1.20:7501 capabilities: - intent.detect - slot.extract metadata: version: 1.2.0 language: nodejs这里node_id是全局唯一标识endpoint是实际监听地址capabilities是能力列表后续的语义协作层会用到。一个小建议capabilities 的命名用领域.动作的格式比如knowledge.retrieve、content.generate后面做路由和权限匹配时会省很多事。2.2 握手流程与会话保持连接级别的状态机节点发现只是拿到了对方的地址真正建立通信还需要一次握手。hermes peer 的握手流程参考了 TCP 三次握手的思想但不是在 TCP 层而是在应用层再做一次带认证信息的建立过程。握手分为三步SYN发起方发送连接请求包体里带协议版本号、自身的 node_id、以及一个临时生成的随机 nonce。SYN-ACK接收方校验协议版本和发起方身份如果通过返回自己的 node_id、nonce 加签名表示愿意建立连接。SESSION-ESTABLISHED发起方确认签名有效双方各自生成会话令牌连接建立完成。这个握手过程有几个关键点值得注意。首先是协议版本的协商。两端版本不一致时采用较低的兼容版本继续通信而不是直接拒绝这个设计对渐进式升级很重要。我在实际升级协议库时由于握手阶段做了版本协商旧节点和新节点混跑完全没问题。其次是身份认证的时机。hermes peer 把身份认证放在连接建立阶段而不是每一条消息都校验一遍这样后续消息传输的性能开销就降下来了。安全性由连接级别的会话令牌保证令牌过期后连接会被强制重建。连接建立之后是会话保持。协议默认每 40 秒发送一次心跳消息如果连续 3 次心跳都没有收到对端响应就判定连接失效触发重连。这个参数在实际部署中要根据网络质量调整我在一个跨机房场景里把心跳间隔调到了 60 秒因为公网链路丢包率稍高40 秒的心跳容易误判。内网环境我反而会调低到 20 秒这样故障发现更快。2.3 消息帧格式一个足够克制但不过度设计的二进制帧传输层还有一个基础组件就是消息帧格式。hermes peer 用的是自定义的二进制帧没有直接用 JSON 或者 protobuf 作为帧格式原因是 Agent 通信中既有需要序列化的业务负载又有需要快速解析的控制信息用纯文本协议在高频场景下解析开销偏大用完整 protobuf 又显得重。帧结构大致是这样的字段长度说明magic4 字节固定魔数用于快速识别有效帧version1 字节协议版本号flags1 字节标志位标记帧类型控制帧 / 数据帧message_type1 字节消息类型对应 REQUEST / RESPONSE 等stream_id4 字节流标识用于关联请求和响应payload_length4 字节负载长度payload变长实际负载通常是一个 JSON 对象或二进制数据帧头总计 15 字节控制信息紧凑payload 可以按需承载结构化数据。我刚开始觉得这个设计有点复古但实际用下来发现好处很明显解析帧头只需要一次内存拷贝可以根据 flags 快速判断是不是心跳之类的控制消息不需要反序列化整个 payload。stream_id是很关键的一个字段。它把请求和响应关联起来相当于 HTTP/2 里的 stream 概念。一个 Agent 可以同时向另一个 Agent 发起多个请求每个请求有独立的 stream_id响应回来后根据 stream_id 分发到对应的处理逻辑里不需要一个一个排队等应答。这也为后面讲到的流式消息打好了基础。3. 语义协作层Agent 身份识别、能力声明与会话槽位协商3.1 Agent 身份标识与能力描述传输层解决了消息怎么送达的问题但 Agent 协作还有一个更上一层的问题消息送达之后对端怎么知道你是一个什么样的 Agent、你能做什么、这条消息该不该由你处理hermes peer 在传输层之上定义了一套语义协作模型。首先是 Agent 身份的规范标识格式是agent://租户/空间/Agent名比如agent://default/support/nlu-agent。这个格式参考了 URI 的层级结构好处是可以天然支持多租户隔离不同租户的 Agent 即使部署在同一套基础设施上也能通过标识前缀快速区分。能力声明用的是 JSON Schema 描述。每个 Agent 启动后会把自身能力列表广播给直连的邻居能力描述包含能力名称、输入参数、返回值、以及一个可选的调用成本评级。{ name: knowledge.retrieve, input: { type: object, properties: { query: { type: string }, top_k: { type: integer, default: 5 } } }, output: { type: array, items: { type: string } } }这个能力模型的实用价值在于Agent 之间可以自动发现职责匹配。当一个 Agent 需要某项能力时它可以先查询邻居节点的能力声明找到一个或多个能提供该能力的 Agent然后发起调用。这种模式在企业内部的 Agent 编排里非常有用——新增一个 Agent 只需要声明能力不需要改其他 Agent 的代码就能被整个协作网络感知和使用。3.2 消息类型与交互模式请求响应之外还有两条路有了身份和能力声明下一步就是定义 Agent 之间到底有哪些交互模式。hermes peer 定义了五种核心消息类型覆盖了我目前遇到的几乎所有协作场景。REQUEST / RESPONSE最基础的同步调用模式。发起方发送 REQUEST接收方处理完成后返回 RESPONSE。适用于意图识别、单次检索这类一次性交互。STREAM流式消息适合大结果集或需要边生成边返回的场景。比如生成 Agent 在写长文时可以把已经生成的文本分段通过 STREAM 消息推给调用方调用方可以一边接收一边展示体验比等全部生成完再一次性返回好得多。EVENT事件通知适合异步松耦合的场景。比如某个 Agent 完成了定时任务它不需要等待响应只要广播一个事件其他感兴趣的业务 Agent 收到后自行处理。HEARTBEAT心跳消息维护连接活性。ERROR错误消息请求失败时返回原因和错误码。有了消息类型后Agent 间的协作就不再是简单的函数调用了而是可以根据场景选择最合适的交互模式。这一点在实际搭建业务系统时非常关键——不是所有协作都适合同步请求响应有些场景用事件驱动会简单得多。3.3 槽位协商与会话超时Agent 协作中的记忆上下文Agent 协作还有一个常常被忽略的问题一次协作过程往往会持续一段时间期间可能有多轮消息交互这些消息需要共享同一个上下文空间。hermes peer 引入了会话槽位slot的概念。会话建立时双方协商一组槽位用来存放协作过程中产生的中间数据。比如一个用户意图 → 知识检索 → 答案生成的协作链意图识别 Agent 把提取到的用户意图写入槽位检索 Agent 从这个槽位读取意图并执行检索再把检索结果写入另一个槽位生成 Agent 最后读取所有中间结果生成最终答案。整个链路的数据流转通过槽位变得清晰可控。协议层面还会为每个会话设置超时时间。如果会话在约定时间内没有新的消息交互槽位数据会被清理连接可以复用但上下文释放。这个超时时间默认是 5 分钟我可以根据业务场景调整。对于需要长时间保持上下文的场景比如多轮对话不要把这个值设得太小否则上一轮的上下文还没用完就被回收了但对于一次性任务型的协作超时设太大会白白占用内存需要权衡。4. 全栈协作实测Node.js 与 Python 三个 Agent 如何点对点跑通一个工单助手4.1 案例背景与拓扑三个 Agent、两种语言、一个协调者前面的原理部分如果只看不练理解始终会浮在表面。这一节我给一个完整的实际案例把 hermes peer 放到一个真实的业务场景里跑一遍。我要实现的是一个工单智能分诊助手用户提交一条工单描述系统需要先识别用户的意图再去知识库里检索相关处理方案最后生成一段给用户的分诊建议。整个流程涉及三个 AgentNLU AgentNode.js负责意图识别和槽位抽取输入工单文本输出意图标签。检索 AgentPython负责在知识库中检索相关方案输入查询词输出候选方案列表。生成 AgentPython负责把意图和检索结果整合成一段流畅的分诊建议。三个 Agent 之间的关系是线性的NLU Agent 识别出意图后把结果交给检索 Agent 去检索检索结果再交给生成 Agent 做最终输出。如果沿用中心化 Broker需要维护一个流程编排服务而使用 hermes peer每个 Agent 自己就是通信节点彼此之间直接建立连接整个协作网络没有中心节点。拓扑上我加了一个协调者角色它本身不承担业务逻辑只负责发起一次协作请求并汇聚最终结果。这个角色可以理解为一个 API 网关对外暴露 HTTP 接口对内通过 hermes peer 调用各个 Agent。4.2 配置文件与启动流程从零到一通消息每个 Agent 的启动配置非常简单核心就是告诉 hermes peer 自己是谁、监听在哪里、能干什么。以 NLU Agent 为例node_id: agent-nlu-01 listen: 0.0.0.0:7501 peers: - node_id: agent-retrieval-01 endpoint: 192.168.1.21:7502 - node_id: agent-generator-01 endpoint: 192.168.1.22:7503 capabilities: - intent.detect - slot.extract session: heartbeat_interval: 20s timeout: 300s启动后NLU Agent 会尝试与配置中的两个 peer 建立连接。如果检索 Agent 和生成 Agent 还没启动连接会失败但 hermes peer 有自动重连机制不会因为初始连接失败就崩溃。我当时测试时故意只先启动 NLU Agent过了一分钟再启动另外两个NLU Agent 自动感知到对端上线并完成了连接建立。业务代码接入协议的方式也很直观。以生成 Agent 为例它需要注册一个能力处理器当收到针对自己能力的调用请求时执行对应逻辑并返回结果const { PeerNode } require(hermes-peer); const node new PeerNode({ nodeId: agent-generator-01, listen: 0.0.0.0:7503 }); node.registerCapability(content.generate, async (params, context) { const { intent, candidates } params; const suggestion buildSuggestion(intent, candidates); return suggestion; });我在这套代码里故意让三个 Agent 用了两种语言Node.js 负责 NLU 部分Python 负责检索和生成部分做的目的就是验证 hermes peer 的跨语言能力。实测下来跨语言调用没有任何额外门槛握手、能力声明、消息序列化在两端都能正确解析。4.3 一次完整的多 Agent 协作消息流拆解跑通之后我抓了一次完整的协作消息流这里逐步拆解一下。第一步协调者通过 hermes peer 向 NLU Agent 发送一条 REQUEST 消息{ message_type: REQUEST, stream_id: 1001, target: agent://default/support/nlu-agent, capability: intent.detect, payload: { text: 我的打印机无法连接WiFi显示离线状态 } }NLU Agent 接收到消息后解析出意图为connectivity_issue槽位信息包含deviceprinter和issuewifi_offline然后返回 RESPONSE 消息并把结果同时写入会话槽位。第二步协调者在下一次请求中携带槽位里已有的信息调用检索 Agent 的knowledge.retrieve能力。检索 Agent 从槽位读取意图和问题描述去知识库召回候选方案返回一个包含三个候选方案的列表。这一步我用 STREAM 消息做了一次流式返回候选方案边检索边发协调者不用等全部完成。第三步协调者把 NLU 的意图和检索候选一起作为参数调用生成 Agent 的content.generate能力。生成 Agent 返回最终的分诊建议文本。整个协作过程三跳消息每一跳都通过 stream_id 关联到同一个会话。会话 ID 贯穿始终我在协调者侧只需要维护一个会话 ID 到 stream_id 的映射表就能完整回溯一次工单分诊的每个环节。这在排查为什么生成结果不对的时候价值非常大——直接按会话 ID 把消息流拉出来一眼就能看到是检索环节召回的候选不好还是生成环节的指令有问题。5. 内网部署里的安全边界与我最头疼的三个疑难杂症5.1 认证鉴权mTLS 与 Token 方案怎么选Agent 之间直连通信意味着网络边界不再只有一条安全模型必须重新设计。hermes peer 支持两种认证方式我按实际场景给出选择建议。Token 方案每个 Agent 启动时配置一个访问令牌握手时携带令牌对端校验通过后建立连接。这个方案实现简单、开销低适合内网环境、节点间信任度较高的场景。但 Token 一旦泄露攻击者就能冒充合法节点接入协作网络所以要配合定期轮换使用。mTLS 方案每个节点持有客户端证书握手时双向校验证书链。安全性比 Token 高一个等级即使某个节点的证书泄露也可以通过吊销列表快速隔离不会影响其他节点。代价是需要维护一套 CA 证书体系部署复杂度明显上升。我在涉及用户隐私数据的场景里用的是 mTLS普通内部工具链用 Token。注意无论选哪种方案都要启用传输层加密。hermes peer 底层集成了 TLS如果没有这个保障Agent 之间传输的中间数据就是裸奔的会话槽位里的信息很容易被网络中的其他设备截获。5.2 跨网段部署的联通性问题端口规划与节点命名内网部署最烦的不是协议本身的问题而是网络环境的问题。我踩过的第一个坑是端口规划混乱。Agent 数量一多如果每个 Agent 随机监听端口防火墙策略会变得非常难维护。我的做法是统一分配一个端口段比如 7500-7599 留给 hermes peer 通信防火墙规则一条就能覆盖另外控制台和监控端口单独分一段。第二个坑是节点命名的不可读。Agent 的 node_id 如果取名随意比如node1、node2出了故障根本不知道具体是哪个业务模块。我建议 node_id 严格按业务-角色-序号的格式命名比如nlu-agent-01、retrieval-agent-01日志和监控里一眼就能识别。第三个坑是NAT 场景下的地址映射。两个 Agent 分别部署在两个不同网段中间经过 NAT 网关此时每个 Agent 配置的 endpoint 必须是对方可达的外网映射地址而不是本机的内网地址。如果 hermes peer 内置的自动发现机制拿到的地址不对就需要在配置里手动覆盖 endpoint。这个问题的排查思路很简单先手动配置 endpoint 测试直连通了再开自动发现功能不要一上来就全部依赖自动发现否则出了问题连手动排查的入口都没有。5.3 我踩过的几个运行期坑并发连接耗尽、消息风暴、回放异常运行期的坑我挑三个典型的来讲。第一个是并发连接数耗尽。Agent 作为服务端有最大连接数限制默认 1024。一旦协作网络里的节点数量变多或者某个节点异常频繁重连连接数就会被占满导致新节点连不进来。现象是日志里有大量connection refused但不影响已建立的连接。解决方法是提高服务端连接上限同时检查是不是有节点的重连退避策略太激进导致连接被短时间内反复建立和释放。第二个是事件风暴。某个 Agent 发布了一个高频 EVENT其他订阅节点收到事件后各自处理处理过程中又产生新的事件最终形成消息风暴打垮整个协作网络。我的处理方式是在协议层给 EVENT 消息增加频率限制同时在业务层约定事件消息必须带上幂等键下游消费时根据幂等键去重。没有幂等机制的事件系统在生产环境迟早出事。第三个是消息回放异常。一次正常的 REQUEST 因为超时被判定为失败发起方进行了重试结果接收方其实已经处理完了重复执行导致副作用。这其实就是分布式系统里最经典的问题——at-least-once 带来的重复处理。hermes peer 允许在 REQUEST 消息中携带业务幂等键接收方在处理前先检查这个键是否已经处理过如果是就直接返回上次的结果。我在所有可能产生副作用的 Agent 能力里都强制执行了这个约束。6. 压测结果与关键参数调优建议6.1 压测数据与资源占用理论说得再多落到生产环境还是要看真实数据。我在本地三台虚拟机上做了一轮压测每台虚拟机 2 核 4GAgent 之间通过 hermes peer 直连消息负载是 1KB 的 JSON 对象测试不同并发下的表现。并发连接数消息大小平均延迟吞吐量CPU 占用单节点101KB1.2ms8200 msg/s12%501KB1.8ms19500 msg/s28%1001KB2.5ms31000 msg/s43%10010KB4.7ms12600 msg/s39%整体表现符合我的预期。单条约 1ms 级延迟对 Agent 协作来说是够用的因为我实际场景里单次协作的消息频率远达不到上千 QPS更多是多 Agent 间长时间保持连接、低频但需要低延迟的交互模式。资源占用方面单个空闲连接的内存占用大概在 30KB 左右心跳消息每 20 秒一次几乎可以忽略不计。这也验证了直连优先的设计思路——相比中心化 Broker 需要额外部署和维护一套消息集群点对点模式在资源开销上确实更轻。6.2 针对不同场景的核心参数调优建议压测之余我整理了四个核心参数的调优经验。心跳间隔内网稳定环境建议 20-30 秒公网或跨运营商链路建议 45-60 秒。判定阈值保持 3 次心跳即可太短会导致误判太长会拖慢故障感知。需要注意心跳间隔和判定阈值的乘积决定了连接故障的感知时间比如心跳 20 秒、阈值 3 次那么最坏情况下一个死连接要 60 秒才会被发现。会话超时纯任务型协作建议 60 秒让槽位数据尽快释放多轮对话等有状态场景建议 5-10 分钟避免上下文过早失效。这里有一个容易忽略的点如果生成 Agent 生成内容耗时较长单次请求的处理时间可能超过会话超时此时需要根据实际回调延长会话生命周期。流控窗口高吞吐场景下建议限制在 200 个未确认消息以内超出后发送方暂缓投递防止接收方处理不过来导致消息堆积。这个参数的本质是给通信双方一个背压机制协调生产速度和消费速度。重试策略指数退避 抖动初始重试间隔 1 秒最大间隔 16 秒加上随机抖动防止多个节点同时重试造成踩踏。重试永远要配合幂等键使用没有幂等键的重试就是在制造重复数据。这些参数没有一套放之四海而皆准的标准答案最终都要根据你的业务场景和网络环境去压测。我的建议是先在开发环境按经验值设置跑稳定之后再上生产然后用监控数据反向调优而不是一开始就追求理论上的最优值。最后再分享一个实用的排障技巧hermes peer 的调试模式可以在节点本地记录完整的连接状态机变化和消息收发记录排查两端看起来都正常但消息就是不通的玄学问题时打开这个模式对比两端的日志通常几分钟就能定位到是握手阶段认证失败、端口未监听、还是地址配置不对称的问题。这个技巧我用了很多次每次都替我节省了不少排查时间。