# Aqua CLI 消息协议设计：端到端加密与 P2P Agent 通信架构 > 深入解析 Aqua 如何基于 libp2p 实现 AI Agent 的点对点消息传递、身份验证与中继穿越，为构建分布式多智能体系统提供可落地的协议参数。 ## 元数据 - 路径: /posts/2026/02/23/aqua-cli-messaging-protocol/ - 发布时间: 2026-02-23T11:01:48+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 站点: https://blog.hotdry.top ## 正文 在多智能体系统（Multi-Agent System）日益普及的今天，AI Agent 之间的通信机制成为基础设施层面的关键挑战。传统基于 REST API 的调用模式难以满足去中心化、动态拓扑与安全可信的下一代 Agent 网络需求。Aqua 作为 Quaily 推出的 CLI 消息工具，为 AI Agent 提供了一套完整的点对点通信协议实现，其核心设计思路值得深入剖析。 ## Aqua 协议定位与核心能力 Aqua 取自 "AQUA Queries & Unifies Agents" 的缩写，旨在为 AI Agent 提供一种轻量级、可自托管的 messaging protocol。与传统的请求-响应式 API 调用不同，Aqua 构建了一套完整的消息队列与路由层，使得 Agent 之间可以像人类使用即时通讯工具一样进行异步、双向的通信。 从功能特性来看，Aqua 具备以下核心能力：首先是点对点 Agent 通信，支持端到端加密与身份验证；其次是持久化消息存储，采用 inbox/outbox 架构确保消息不丢失；第三是 Circuit Relay v2 支持，解决跨网络拓扑的连接穿越问题；最后是简洁的 CLI 接口，屏蔽底层网络细节。 这些能力使得 Aqua 特别适合以下场景：分布式 AI Agent 协作编排、边缘计算节点间的状态同步、需要隐私保护的多方 Agent 交互，以及网络环境复杂的跨域通信。 ## 基于 libp2p 的底层网络架构 Aqua 的网络层完全构建在 libp2p 之上，这一选择为其带来了成熟的 P2P 能力。libp2p 是 IPFS项目的核心网络库，提供了对等发现、传输协商、 NAT 穿越等基础设施，Aqua 在此基础上封装了适合 Agent 通信的协议层。 在身份机制方面，Aqua 使用 libp2p 的 PeerID 作为全局唯一标识。每个 Agent 启动时通过 `aqua id ` 命令生成自己的身份，包含公私钥对和对应的 PeerID。这个 PeerID 在整个 Aqua 网络中具有全局唯一性，类似于 XMPP 协议中的 JID（Journal Entry Identifier）。 在传输层面，Aqua 同时支持 TCP 和 QUIC（UDP）两种传输协议。QUIC 作为新一代传输协议，具备更低的连接延迟和更好的丢包恢复能力，适合网络条件不稳定的场景。Aqua 的官方中继节点提供了两种协议的接入端点： - TCP：`/dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E` - UDP（QUIC）：`/dns4/aqua-relay.mistermorph.com/udp/6372/quic-v1/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E` 在连接模式上，Aqua 提供了三种.relay-mode 参数，分别适用于不同网络环境：auto 模式下，Aqua 优先尝试直连，失败后自动切换到中继模式；off 模式仅允许直连，适用于同一局域网或具备公网IP的场景；required 模式强制走中继，适合严格的网络隔离环境。 ## 消息协议与指令编排 Aqua 的消息协议设计遵循简洁、可扩展的原则，支持多种消息类型和元数据。核心的消息发送通过 `aqua send "message content"` 命令完成，这条命令背后实际上完成了两件事：建立与目标 Agent 的加密连接，以及将消息推送至对方的 inbox。 在消息格式层面，Aqua 支持通过 `--content-type` 参数指定内容类型，默认情况下为纯文本。当 Agent 需要传递结构化数据时，可以指定 `application/json`，这对于传递 JSON 格式的指令或状态更新尤为有用。 为了支持复杂的对话场景，Aqua 引入了两个重要的可选参数：`--reply-to` 用于实现消息回复的线程化追踪，`--session-id` 用于标识属于同一会话的多轮交互。这两个参数的存在使得 Aqua 不仅支持简单的单向消息推送，还能构建完整的多轮对话链路。 在协议层面，Aqua 定义了以下几种消息类型：`hello` 用于建立首次连接的握手过程，`ping` 用于保持连接活跃和健康检查，`capabilities` 用于协商双方支持的协议特性，`send` 用于实际的消息推送，`agent.data.push` 则是 Aqua 特有的数据推送协议，用于将消息写入接收方的 inbox。 ## 跨网络的中继与 NAT 穿越 在真实的部署环境中，AI Agent 通常运行在不同的网络环境中，NAT 穿越是不可避免的问题。Aqua 通过集成 libp2p 的 Circuit Relay v2 机制来解决这一挑战。 Circuit Relay 的工作原理可以类比为 P2P 网络中的“中转站”。当两个 Agent 位于不同的私有网络时，它们各自与中继节点建立连接，中继节点在两者之间转发流量，从而实现间接通信。Aqua 的官方中继节点 `aqua-relay.mistermorph.com` 提供了公共的中继服务，生产环境建议部署自有的中继服务以获得更好的可控性。 使用中继模式的关键在于获取自己的 relay-circuit 地址。Agent 需要首先启动 serve 进程（`aqua serve --relay-mode auto --relay `），然后从输出中复制包含 `/p2p-circuit/` 路径的地址。这个地址形如 `/dns4/aqua-relay.mistermorph.com/tcp/6372/p2p/12D3KooWSYjt4v1exWDMeN7SA4m6tDxGVNmi3cCP3zzcW2c5pN4E/p2p-circuit/p2p/`，可以分享给其他 Agent 用于建立连接。 对于需要严格控制访问权限的场景，Aqua 的中继服务支持 `--allow-peer` 参数的白名单模式，确保只有授权的 Agent 才能使用中继服务。 ## 持久化存储与消息可靠性 Aqua 采用本地文件系统作为消息存储后端，数据默认保存在 `~/.aqua` 目录（可通过 `--dir` 或 `AQUA_DIR` 环境变量覆盖）。这种设计使得 Aqua 不依赖外部数据库，降低了部署复杂度，同时通过文件系统实现了消息的持久化。 存储层采用 JSONL（JSON Lines）格式存储消息正文，这种格式既保证了写入性能，又便于后续的日志分析和数据恢复。具体来看，Aqua 的存储结构包含以下关键文件：`identity.json` 保存本地身份信息（包括 PeerID 和密钥材料），`contacts.json` 维护联系人注册表，`inbox_messages.jsonl` 存储接收到的消息，`outbox_messages.jsonl` 存储已发送消息的副本，`inbox_read_state.json` 记录消息的已读/未读状态，`dedupe_records.json` 用于消息去重和幂等性保障，`protocol_history.json` 保存协议协商历史。 Aqua 还内置了去重机制，通过 `dedupe_records.json` 记录已处理消息的唯一标识，防止重复投递。这在网络不稳定导致重传的场景下尤为重要。 ## CLI 交互设计与 Agent 集成 Aqua 的 CLI 设计充分考虑了与 AI Agent 的集成需求。所有输出数据的命令都支持 `--json` 参数，以结构化 JSON 格式返回结果，便于程序化解析和处理。这对于自动化工作流至关重要，Agent 可以通过解析 JSON 输出获取对方的消息内容、联系人列表或自身状态。 从命令组织来看，Aqua 的 CLI 可以分为以下几类：身份管理类包括 `init` 和 `id`，用于初始化和查看身份信息；联系人管理类包括 `contacts list/add/import/show/verify/del`，提供完整的联系人生命周期管理；节点服务类包括 `serve`（启动监听）和 `relay serve`（启动中继服务）；通信类包括 `hello/ping/capabilities/send`，分别用于连接测试和消息发送；消息查看类包括 `inbox list/mark-read` 和 `outbox list`，用于查看收发的消息。 在实际集成中，推荐的 Agent 启动流程如下：首先通过 `aqua id` 获取自己的 PeerID；然后启动 serve 进程并配置中继模式；接着将获取到的 relay-circuit 地址通过外部渠道分享给协作 Agent；最后通过 `aqua contacts add` 添加目标 Agent 的地址并验证身份。消息的发送与接收可以完全通过脚本自动化，Agent 只需定时轮询 `aqua inbox list --unread` 即可获取新消息。 ## 信任模型与安全实践 Aqua 在设计时将安全性作为核心考量。端到端加密由 libp2p 的加密通道默认提供，确保消息在传输过程中不被窃听。身份验证方面，Aqua 提供了 `--verify` 参数用于标记可信联系人，但这个验证过程需要带外（out-of-band）完成——即双方通过其他渠道确认彼此的公钥指纹。 这种设计体现了一种务实的信任建立思路：在开放的分布式系统中，强制要求中心化 CA 认证并不现实，因此 Aqua 选择让用户自行决定信任的建立方式。`--verify` 标记只是表明“已确认对方身份”，而非自动执行的密码学验证。 生产环境部署时，建议遵循以下实践：严格保管 `~/.aqua/identity.json` 文件，防止私钥泄露；如使用官方中继，应评估其可用性和日志策略；对于高安全需求场景，部署私有中继节点；定期备份消息存储目录，以防数据丢失。 ## 工程落地的关键参数 对于计划在生产环境中采用 Aqua 的团队，以下参数和配置值得重点关注。首先是 `--relay-mode` 的选择，生产环境推荐使用 `auto` 以兼顾连接成功率和资源消耗。其次是中继服务的选择，官方提供的 `aqua-relay.mistermorph.com` 适合原型验证，生产环境建议自建中继节点。第三是数据目录的配置，通过 `AQUA_DIR` 环境变量可以方便地将数据存储在指定位置，便于容器化部署时的卷挂载。第四是 JSON 输出的使用，所有脚本化的交互都应加上 `--json` 参数，确保输出的可解析性。第五是消息轮询间隔的设置，建议设置为 1-5 秒，既能保证实时性，又不会对系统造成过大压力。 综合来看，Aqua 为 AI Agent 提供了一套成熟、可落地的 CLI 消息协议方案。其基于 libp2p 的架构保证了网络的去中心化特性，端到端加密和身份验证机制满足了安全需求，而简洁的 CLI 设计和丰富的文档则降低了使用门槛。随着多智能体系统的持续发展，这类专门面向 Agent 通信的基础设施将会扮演越来越重要的角色。 --- **参考资料** - Aqua 官方仓库：https://github.com/quailyquaily/aqua - Aqua 架构文档：https://github.com/quailyquaily/aqua/blob/master/docs/architecture.md - Aqua Agent Skill 定义：https://github.com/quailyquaily/aqua/blob/master/SKILL.md ## 同分类近期文章 ### [NVIDIA PersonaPlex 双重条件提示工程与全双工架构解析](/posts/2026/04/09/nvidia-personaplex-dual-conditioning-architecture/) - 日期: 2026-04-09T03:04:25+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 NVIDIA PersonaPlex 的双流架构设计、文本提示与语音提示的双重条件机制，以及如何在单模型中实现实时全双工对话与角色切换。 ### [ai-hedge-fund：多代理AI对冲基金的架构设计与信号聚合机制](/posts/2026/04/09/multi-agent-ai-hedge-fund-architecture/) - 日期: 2026-04-09T01:49:57+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析GitHub Trending项目ai-hedge-fund的多代理架构，探讨19个专业角色分工、信号生成管线与风控自动化的工程实现。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation-framework/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [LiteRT-LM C++ 推理运行时：边缘设备的量化、算子融合与内存管理实践](/posts/2026/04/08/litert-lm-cpp-inference-runtime-quantization-fusion-memory/) - 日期: 2026-04-08T21:52:31+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 LiteRT-LM 在边缘设备上的 C++ 推理运行时，聚焦量化策略配置、算子融合模式与内存管理的工程化实践参数。