AgentMesh Wire Protocol v1.0 全解析:面向 AI Agent 的端到端加密消息协议
AgentMesh Wire Protocol v1.0 全解析:面向 AI Agent 的端到端加密消息协议
本篇文章基于 docs/specs/AGENTMESH-WIRE-1.0.md 展开,并结合 Agent Governance Toolkit 仓库中 Python / TypeScript SDK 的源码实现进行纵深解读。读完本文,你将掌握:AgentMesh 的 DID 身份模型与密钥体系、X3DH 密钥协商与 Double Ratchet 双棘轮加密的完整参数与状态机、JSON 帧结构与 KNOCK 意图握手协议、Registry/Relay 服务的设计、Ed25519-Timestamp 认证与治理集成方式,以及协议版本化与安全模型。无论你是要在 Python、TypeScript、Rust、.NET 还是 Go 中实现 AgentMesh 兼容客户端,本文都能作为一份可直接对照规范的实战指南。
AgentMesh Wire Protocol v1.0 是 Agent Governance Toolkit(AGT)为 AI Agent 之间端到端加密消息传输定义的线路协议规范。它解决的是多智能体系统中最棘手的问题之一:两个自治 Agent 如何在不可信的传输链路上建立加密会话、交换消息,同时让治理层(策略引擎、信任评分、审计日志)在加解密之前完成"允许/拒绝"决策。本规范覆盖 1:1 点对点消息,1:N 群组消息明确留待 v2 使用 MLS(RFC 9420)实现。
1. 协议定位:传输层与治理层分离
1.1 设计目标
规范开篇明确了协议的六个核心目标:
- 机密性(Confidentiality):只有通信双方能解密消息;
- 前向保密(Forward secrecy):当前密钥泄露不会导致历史消息被解密;
- 泄露后安全(Post-compromise security):棘轮(ratchet)能在密钥泄露后"自愈";
- 认证(Authentication):消息通过密码学绑定到 Agent 身份;
- 重放保护(Replay protection):每个消息密钥单次使用;
- 离线投递(Offline delivery):通过 store-and-forward 机制为离线 Agent 持久化消息。
1.2 与 AGT 治理层的关系
这是本规范最重要的架构决策:AgentMesh 定义的是传输层,而 AGT 的治理层(策略引擎、信任评分、审计日志)环绕在传输层之外运作——在传输层加密或解密之前,先评估消息是否允许发送或接收。治理与传输刻意分离,以便两者独立演进。
规范给出了清晰的层级图:AGT Governance Layer (Policy → Trust → Audit) 输出 allow/deny 决策,向下传给 AgentMesh Wire Protocol (X3DH → Ratchet → Envelope),再由 Transport (WebSocket / gRPC) 承载密文。这一分层设计在源码中有直接印证,例如 agent-governance-python/agent-mesh/src/agentmesh/encryption/channel.py 等加密模块与 agent-governance-python/agent-mesh/src/agentmesh/governance/ 治理模块在包结构上就是分离的。
1.3 设计原则
- 标准优先(Standards first):每个密码学操作都引用已发布的 RFC 或规范,不搞自研加密;
- 身份统一(One identity, everywhere):所有 SDK 与服务共享同一套 Agent 身份格式;
- 多语言可实现(Crypto in every language):协议必须能用经过审计的库在 Python、TypeScript、Rust、.NET、Go 中实现;
- 治理可分离(Governance-separable):治理决策发生在传输层动作之前,传输层永不做出策略决策;
- Relay 是服务而非特性(Relay is a service, not a feature):store-and-forward 是可部署的服务,不内嵌进 SDK;
- 协议版本化(Protocol versioning):每个帧都携带版本字段,未来版本(含 MLS 群组支持)可协商。
2. 标准基础:全部引用公开 RFC 与 CC0 规范
| 组件 | 标准 | 参考 |
|---|---|---|
| 密钥协商 | X3DH | Signal X3DH 规范(CC0) |
| 会话加密 | Double Ratchet | Signal Double Ratchet 规范(CC0) |
| Diffie-Hellman | X25519 | RFC 7748 |
| 密钥派生 | HKDF-SHA256 | RFC 5869 |
| 对称加密 | ChaCha20-Poly1305 | RFC 8439 |
| 签名 | Ed25519 | RFC 8032 |
| 身份 | DID | W3C DID Core |
| 未来群组消息 | MLS | RFC 9420 |
2.1 为什么 v1 选 Signal Protocol 而非 MLS
规范用一张对比表给出了决策依据:
| 标准 | Signal Protocol | MLS(RFC 9420) |
|---|---|---|
| 点对点消息 | 原生支持 | 支持(2 人群组) |
| 群组消息 | N×(N-1)/2 个会话 | 原生树形棘轮 |
| 实现复杂度 | 中等 | 高 |
| AGT 现有实现 | Python(61 个测试) | 无 |
| 生态采用 | WhatsApp、Signal、Google Messages | Cisco Webex、Wire(新兴) |
| 规范成熟度 | 10+ 年 | RFC 于 2023 年发布 |
选择 Signal Protocol 的原因:AGT 已有可用的 Python 实现、Agent 间场景以点对点为主、五种语言的实现负担可控。MLS 通过第 15 节定义的版本协商机制预留给 v2 群组消息。
3. Agent 身份:自验证 DID
3.1 身份格式与指纹
所有 Agent 遵循 W3C DID Core 规范,用 DID(去中心化标识符)标识:
did:agentmesh:<fingerprint>
其中指纹为:
fingerprint = base58btc(sha256(ed25519_public_key)[0:20])
即 Agent Ed25519 公钥的 20 字节截断 SHA-256 哈希,用 base58btc(比特币字母表)编码。其性质包括:
- 自验证(Self-verifying):任何持有公钥的人都能重新计算指纹;
- 紧凑(Compact):27-28 个字符,如
did:agentmesh:3J98t1WpEZ73CNmQvie; - 无需注册表往返即可完成基础验证;
- 抗碰撞(Collision-resistant):160 位哈希提供 2^80 碰撞阻力。
3.2 身份收敛决策(ADR)
规范记录了一条 ADR 决策:将 Python 的 did:mesh: 与 TypeScript 的 did:agentmesh: 统一收敛为单一的 did:agentmesh:<fingerprint> 格式,理由是指纹由公钥派生、自验证,且 did:agentmesh: 前缀更贴合包命名。迁移策略是:已有 did:mesh: 标识符通过兼容 shim 继续有效,新身份必须使用 did:agentmesh:。
值得说明的是,从当前仓库源码看,TypeScript SDK 的 agent-governance-typescript/src/encryption/mesh-client.ts 中 computeCanonicalDid 仍按 did:mesh:<sha256(public_key)[:32]>(16 字节摘要)派生 DID 以匹配 Python 服务端实现,这与规范收敛到 did:agentmesh:(20 字节 base58btc)的 ADR 属于实现与规范之间的演进过渡状态,读者在跨 SDK 对接时需以各自版本的注册表/中继实现为准。
3.3 密钥材料
每个 Agent 持有五类密钥:
| 密钥 | 类型 | 用途 | 生命周期 |
|---|---|---|---|
| 身份密钥(IK) | Ed25519 | 签名、DID 派生 | 长期 |
| 身份密钥(IK-X) | X25519 | DH 运算(由 IK 派生) | 与 IK 相同 |
| 签名预密钥(SPK) | X25519 | X3DH,由 IK 签名 | 定期轮换(建议 7 天) |
| 一次性预密钥(OPK) | X25519 | X3DH,使用即消耗 | 单次使用 |
| 棘轮密钥 | X25519 | Double Ratchet DH 步骤 | 每消息轮次 |
3.4 Ed25519 到 X25519 的转换
身份密钥是 Ed25519(用于签名),而 X3DH 需要 X25519(用于 DH)。转换使用 RFC 7748 第 4.1 节定义的 birational map:
x25519_private = ed25519_sk_to_curve25519(ed25519_private_key)
x25519_public = ed25519_pk_to_curve25519(ed25519_public_key)
这是 libsodium(crypto_sign_ed25519_pk_to_curve25519)、@noble/curves(edwardsToMontgomeryPub)等库的标准操作。源码层面,Python 实现在 agent-governance-python/agent-mesh/src/agentmesh/encryption/x3dh.py 中通过 PyNaCl 的 crypto_sign_ed25519_sk_to_curve25519 / crypto_sign_ed25519_pk_to_curve25519 完成转换;TypeScript 实现在 agent-governance-typescript/src/encryption/x3dh.ts 中通过 sha512(seed) 取前 32 字节并按 RFC 7748 §5 clamp(privateKey[0] &= 248; privateKey[31] &= 127; privateKey[31] |= 64)实现,两种实现路径等价。
4. 密码学原语:单一强制密码套件
4.1 密码套件
协议只定义一个强制密码套件:
AGENTMESH_X25519_CHACHA20POLY1305_SHA256
| 原语 | 算法 | 参数 |
|---|---|---|
| DH | X25519 | RFC 7748 |
| AEAD | ChaCha20-Poly1305 | RFC 8439,96 位 nonce,128 位 tag |
| 哈希 | SHA-256 | FIPS 180-4 |
| KDF | HKDF-SHA256 | RFC 5869 |
| 签名 | Ed25519 | RFC 8032 |
| 密钥编码 | 原始 32 字节 | X25519 使用小端 u-coordinate |
4.2 HKDF 用法
所有密钥派生使用 HKDF-SHA256(RFC 5869),带域特定的 info 字符串:
| 用途 | Salt | Info | 输出长度 |
|---|---|---|---|
| X3DH 共享密钥 | 0x00 * 32(零块) |
"AgentMesh_X3DH_v1" |
32 字节 |
| 根密钥棘轮 | 当前根密钥 | "AgentMesh_Ratchet_v1" |
64 字节(32 root + 32 chain) |
| 链密钥 → 消息密钥 | — | 以 0x01 为 HMAC-SHA256 |
32 字节 |
| 链密钥 → 下一链 | — | 以 0x02 为 HMAC-SHA256 |
32 字节 |
X3DH HKDF 输入(Signal 规范):0xFF * 32 字节串 F 前缀到 IKM 之前(IKM = F || DH1 || DH2 || DH3 <a href="https://link.gitcode.com/i/8e60ac11857ac1393172f58b9512df6e" target="_blank">|| DH4]),HKDF 的 salt 是零块(0x00 * 32),不是 F。规范特别指出,早期草案错误地把 F 用作 salt,相关修正记录在 [docs/security/audits/2026-06-22-x3dh-kdf-spec-fix.md。
这个细节在源码中有极其生动的印证:TypeScript 的 x3dh.ts 注释记录了此前 TS 端错误地把 F 作为 HKDF salt、把裸 DH 拼接作为 IKM,导致与已修正的 Python SDK 之间出现"握手成功但第一条消息解密报 invalid tag"的跨运行时互操作问题;修正后 kdf() 统一实现为 hkdf(sha256, F_PREFIX || ikm, ZERO_SALT, X3DH_INFO, 32),并在 agent-governance-python/agent-mesh/tests/test_x3dh.py 中通过 test_kdf_uses_zero_salt_and_prepends_f_to_ikm 测试固定了盐/IKM 语义,防止回归。
4.3 AEAD 构造
消息用 ChaCha20-Poly1305(RFC 8439)加密:
nonce = random(12) # 96-bit random nonce
aad = header_bytes || associated_data
ciphertext = ChaCha20Poly1305.encrypt(key, nonce, plaintext, aad)
output = nonce || ciphertext # nonce prepended
关联数据(AAD) 将密文绑定到消息头和 Agent 身份,防止头部篡改:
aad = serialize(header) || sender_did_bytes || recipient_did_bytes
5. 密钥管理:预密钥包与轮换策略
5.1 预密钥包(Pre-Key Bundle)
Agent 向注册表发布预密钥包,供异步会话建立使用:
{
"version": 1,
"agent_did": "did:agentmesh:3J98t1WpEZ73CNmQvie",
"identity_key": "<base64url(x25519_public)>",
"signed_pre_key": {
"key_id": 42,
"public_key": "<base64url(x25519_public)>",
"signature": "<base64url(ed25519_signature)>"
},
"one_time_pre_keys": [
{ "key_id": 100, "public_key": "<base64url(x25519_public)>" },
{ "key_id": 101, "public_key": "<base64url(x25519_public)>" }
],
"timestamp": "2026-04-21T19:00:00Z"
}
5.2 签名预密钥轮换
签名预密钥建议每 7 天轮换一次。轮换后注册表必须保留上一把 SPK 14 天,以便在途的会话建立完成。
5.3 一次性预密钥补充
OPK 使用即消耗。Agent 建议在注册表上维持至少 10 把 OPK,当数量低于 5 时补充。TypeScript SDK 的默认行为是连接时生成并上传 20 把 OPK(oneTimePrekeyCount,默认 20,见 mesh-client.ts),每把 X3DH 发起成功即被对方消耗一把。
6. X3DH 密钥协商:完整流程与参数
完全遵循 Signal X3DH 规范,参数如下:
curve = X25519
hash = SHA-256
info = "AgentMesh_X3DH_v1"
6.1 发起方流程(Initiator Flow)
- 从注册表获取接收方的预密钥包;
- 验证 SPK 签名(对 SPK 公钥的 Ed25519 签名);
- 生成临时 X25519 密钥对(EK);
- 计算 DH 值:
DH1 = DH(IK_sender, SPK_recipient)DH2 = DH(EK_sender, IK_recipient)DH3 = DH(EK_sender, SPK_recipient)DH4 = DH(EK_sender, OPK_recipient)(若有 OPK)
- 派生共享密钥:
SK = HKDF(salt = 0x00*32, IKM = 0xFF*32 || DH1||DH2||DH3[||DH4], info = "AgentMesh_X3DH_v1", 32); - 以 SK 初始化 Double Ratchet(发送方角色)。
6.2 响应方流程(Responder Flow)
- 接收包含发送方 IK、EK 和所用 OPK ID 的初始消息;
- 计算对应的 DH 值(角色对调);
- 派生相同的共享密钥 SK;
- 以 SK 初始化 Double Ratchet(接收方角色);
- 删除已消耗的 OPK。
6.3 关联数据(Associated Data)
AD = sender_identity_key_x25519 || recipient_identity_key_x25519
AD 传给 Double Ratchet,并绑定进每条消息的 AEAD。
6.4 源码级印证
- Python 的
X3DHKeyManager实现于 agent-governance-python/agent-mesh/src/agentmesh/encryption/x3dh.py,测试 test_x3dh.py 覆盖了 20+ 场景:完整交换、无 OPK 交换、OPK 消耗、重用 OPK 报错、篡改 SPK 签名拒绝、伪造身份密钥拒绝等(如test_full_exchange_with_otk、test_otk_consumed_after_use、test_tampered_spk_signature_rejected)。 - TypeScript 的 x3dh.ts
initiate()依次计算 DH1/DH2/DH3,存在 OPK 时追加 DH4;respond()(L227-L261)按角色对调计算,并在usedOneTimeKeyId存在时校验并删除对应 OPK(this.oneTimePreKeys.delete(usedOneTimeKeyId))。 - 预密钥包验证(
verifyBundle)在 x3dh.ts:校验 Ed25519 身份密钥存在且为 32 字节、SPK 签名为 64 字节、SPK 与身份密钥均为 32 字节,最后用 Ed25519 公钥验证 SPK 签名,确保预密钥确实由包的所有者生成而非攻击者注入。
7. Double Ratchet:逐消息前向保密
完全遵循 Signal Double Ratchet 规范,参数如下。
7.1 棘轮状态
state = {
dh_self: X25519KeyPair, # 当前 DH 棘轮密钥对
dh_remote: X25519PublicKey, # 对端当前 DH 棘轮密钥
root_key: bytes[32], # 根链密钥
chain_send: bytes[32] | null, # 发送链密钥
chain_recv: bytes[32] | null, # 接收链密钥
n_send: uint32, # 发送消息计数器
n_recv: uint32, # 接收消息计数器
pn: uint32, # 上一发送链长度
skipped: Map<(bytes, uint32), bytes[32]> # 跳过的消息密钥
}
7.2 对称棘轮(KDF 链)
message_key = HMAC-SHA256(chain_key, 0x01)
next_chain_key = HMAC-SHA256(chain_key, 0x02)
TypeScript 实现于 agent-governance-typescript/src/encryption/ratchet.ts 的 kdfChain(),与规范完全一致。
7.3 DH 棘轮步骤
当收到消息的 DH 公钥与 dh_remote 不同时触发:
- 缓存当前接收链的跳过消息密钥;
dh_output = DH(dh_self.private, new_dh_remote);root_key, chain_recv = KDF_ROOT(root_key, dh_output);- 生成新 DH 密钥对:
dh_self = X25519.generate(); dh_output = DH(dh_self.private, new_dh_remote);root_key, chain_send = KDF_ROOT(root_key, dh_output);- 重置发送/接收计数器。
根密钥 KDF 在 ratchet.ts 中实现为 hkdf(sha256, dhOutput, rootKey, "AgentMesh_Ratchet_v1", 64),前 32 字节为新 root key、后 32 字节为新链密钥,输出长度与规范一致。
7.4 跳过的消息密钥
每会话最大跳过密钥数:100(可配置)。超过此上限必须以错误拒绝消息。跳过密钥建议持久化以便会话恢复。
值得注意:TypeScript 实现额外增加了一个总量上限 MAX_SKIPPED_KEYS_TOTAL = 2000(ratchet.ts),防止会话跨多次 DH 棘轮步骤后 skippedKeys 无界增长,其注释明确"镜像了 Python 核心实现的 _MAX_SKIPPED_KEYS_TOTAL"——这是规范基线之上各语言实现自行加固的典型例子。
7.5 会话序列化
棘轮状态必须可序列化为 JSON 以便持久化:
{
"dh_self_private": "<hex>",
"dh_self_public": "<hex>",
"dh_remote_public": "<hex>",
"root_key": "<hex>",
"chain_key_send": "<hex>",
"chain_key_recv": "<hex>",
"n_send": 0,
"n_recv": 0,
"pn": 0,
"skipped_keys": { "<dh_pub_hex>:<n>": "<message_key_hex>" }
}
8. 消息信封:JSON 帧格式
8.1 通用帧格式
所有协议帧都是带 type 字段和 version 字段的 JSON 对象:
{
"v": 1,
"type": "<frame_type>",
"from": "did:agentmesh:<fingerprint>",
"to": "did:agentmesh:<fingerprint>",
"id": "<uuid>",
"ts": "<ISO-8601>",
...帧特有字段
}
8.2 帧类型
| 类型 | 方向 | 用途 |
|---|---|---|
connect |
客户端 → Relay | 注册在线状态、认证 |
disconnect |
客户端 → Relay | 优雅断开 |
knock |
Agent → Agent(经 Relay) | 携带意图的会话发起 |
knock_accept |
Agent → Agent(经 Relay) | 带策略条件接受会话 |
knock_reject |
Agent → Agent(经 Relay) | 带原因拒绝会话 |
message |
Agent → Agent(经 Relay) | 加密的应用消息 |
ack |
Agent → Agent(经 Relay) | 投递确认 |
prekey_request |
客户端 → Registry | 获取预密钥包 |
prekey_response |
Registry → 客户端 | 预密钥包 |
prekey_upload |
客户端 → Registry | 发布预密钥包 |
heartbeat |
客户端 → Relay | 保活 + 在线状态 |
error |
任意 → 任意 | 错误响应 |
8.3 消息帧(核心加密帧)
{
"v": 1,
"type": "message",
"from": "did:agentmesh:sender",
"to": "did:agentmesh:recipient",
"id": "550e8400-e29b-41d4-a716-446655440000",
"ts": "2026-04-21T19:00:00Z",
"header": {
"dh": "<base64url(sender_dh_public_key)>",
"pn": 5,
"n": 0
},
"ciphertext": "<base64url(nonce || encrypted_payload)>"
}
头部字段:
dh— 发送方当前 DH 棘轮公钥(32 字节,base64url);pn— 上一发送链长度(用于跳过密钥计算);n— 当前发送链中的消息序号。
密文: 12 字节 nonce 前置到 ChaCha20-Poly1305 输出之前。
TypeScript 发送路径完全按此构造:send() 在 mesh-client.ts 中调用 session.channel.send(...) 后,将 encrypted.header.dhPublicKey / previousChainLength / messageNumber 分别映射为帧的 dh / pn / n,密文 base64url 编码(实现中实际使用标准 base64 Buffer 编码,解码侧与之对应)。
8.4 初始消息(X3DH)
会话的第一条消息包含 X3DH 建立数据:
{
"v": 1,
"type": "message",
"from": "did:agentmesh:sender",
"to": "did:agentmesh:recipient",
"id": "...",
"ts": "...",
"x3dh": {
"identity_key": "<base64url(sender_x25519_identity_key)>",
"ephemeral_key": "<base64url(sender_ephemeral_key)>",
"used_opk_id": 100
},
"header": { "dh": "...", "pn": 0, "n": 0 },
"ciphertext": "..."
}
x3dh 字段只在会话的第一条消息中出现。接收方在解密前用它执行 X3DH 响应方流程。
9. KNOCK 意图协议:治理门控的会话握手
KNOCK 是一种携带意图(intent-carrying)的握手,先于会话建立。它允许接收方在接受会话前评估发起方声明的意图——与 AGT 治理层集成。
9.1 KNOCK 帧
{
"v": 1,
"type": "knock",
"from": "did:agentmesh:sender",
"to": "did:agentmesh:recipient",
"id": "...",
"ts": "...",
"intent": {
"action": "delegate_task",
"description": "Process customer refund #12345",
"capabilities_required": ["payments:write", "crm:read"],
"trust_minimum": 700
},
"signature": "<base64url(ed25519_signature_over_canonical_intent)>"
}
9.2 KNOCK 接受
{
"v": 1,
"type": "knock_accept",
"from": "did:agentmesh:recipient",
"to": "did:agentmesh:sender",
"id": "...",
"ts": "...",
"knock_id": "<原始 knock 的 id>",
"conditions": {
"max_messages": 100,
"ttl_seconds": 3600,
"allowed_actions": ["payments:write"]
},
"signature": "<base64url(ed25519_signature)>"
}
9.3 KNOCK 拒绝
{
"v": 1,
"type": "knock_reject",
"from": "did:agentmesh:recipient",
"to": "did:agentmesh:sender",
"id": "...",
"knock_id": "<原始 knock 的 id>",
"reason": "insufficient_trust",
"signature": "<base64url(ed25519_signature)>"
}
9.4 治理集成
接受 KNOCK 之前,接收方的治理层评估:
- 发送方 DID 是否已注册且激活?
- 发送方信任分是否达到
trust_minimum? - 发送方是否持有
capabilities_required? - 声明的
intent.action是否通过策略引擎?
只有所有检查通过,接收方才发送 knock_accept 并进入 X3DH 密钥交换。
9.5 源码级实现细节
TypeScript 的 MeshClient 对 KNOCK 做了大量工程化加固(mesh-client.ts):
- 超时与竞态处理:
knockTimeout默认 10 秒,超时后等待方统一以"拒绝"收尾;timedOut标志防止慢处理器的knock_accept在计时器已判负之后发出; - 待决队列(knockPending):若加密消息先于 KNOCK 判决到达(Relay 不保证帧间顺序),
handleMessage会等待 KNOCK 决议后再决定是否解密; - 会话自动引导:发起方在 KNOCK 帧内嵌
establishment(含ik/ek/otk),接收方接受后即可自动 bootstrap 响应方会话,无需等第一条密文才手工acceptSession(),消除了 "No encrypted session" 竞态(注释中称为 vendored agentmesh-sdk patch #4b); - Pre-KNOCK 缓冲:对"KNOCK 判决前到达的加密帧"按 peer 缓冲,默认每 peer 5 条、TTL 3000ms、全局最多 100 个 peer 缓冲,超限驱逐最旧 peer(Gap-G4 修复);
- 明文降级防护:是否按 legacy 明文处理完全由接收方自身的操作者配置(
plaintextPeers白名单)决定,绝不信任帧上发送方可控的plaintext布尔值;且e2eVerifiedSet是单向闩锁——一旦某 peer 成功解密过一条消息,该 peer 终生不再按明文路径处理(Gap-G3 修复,防恶意 Relay 用垃圾密文强制关会话后降级攻击)。
10. Registry API:注册表服务
注册表是存储 Agent 元数据、预密钥包并提供发现的 REST 服务。
10.1 端点
| 方法 | 路径 | 用途 |
|---|---|---|
POST |
/v1/agents |
注册 Agent |
GET |
/v1/agents/{did} |
获取 Agent 元数据 |
DELETE |
/v1/agents/{did} |
注销 Agent |
PUT |
/v1/agents/{did}/prekeys |
上传预密钥包 |
GET |
/v1/agents/{did}/prekeys |
获取预密钥包(消耗一把 OPK) |
GET |
/v1/agents/{did}/presence |
获取在线状态/最后可见时间 |
POST |
/v1/agents/{did}/reputation |
提交信誉反馈 |
GET |
/v1/discover |
按能力搜索 Agent |
10.2 Agent 注册
POST /v1/agents
Authorization: Ed25519-Timestamp <did> <timestamp> <signature>
{
"did": "did:agentmesh:3J98t1WpEZ73CNmQvie",
"public_key": "<base64url(ed25519_public)>",
"capabilities": ["data:read", "data:write"],
"metadata": {
"name": "trading-agent",
"framework": "langchain",
"version": "1.0.0"
}
}
10.3 预密钥获取
GET /v1/agents/did:agentmesh:3J98t1WpEZ73CNmQvie/prekeys
Authorization: Ed25519-Timestamp <did> <timestamp> <signature>
响应包含一把 OPK(原子消耗):
{
"identity_key": "<base64url>",
"signed_pre_key": { "key_id": 42, "public_key": "<base64url>", "signature": "<base64url>" },
"one_time_pre_key": { "key_id": 100, "public_key": "<base64url>" }
}
如果 OPK 耗尽,one_time_pre_key 为 null,发起方执行 3-DH(不含 DH4)。
源码印证:TypeScript 的 MeshClient.registerSelf()(mesh-client.ts)生成 SPK 与 oneTimePrekeyCount 把 OPK,携带能力列表(自动附加 displayName 以便按名 discover)与元数据完成注册,然后上传预密钥;注册采用 POP(proof-of-possession)模式,服务端验证 Ed25519(public_key || timestamp) 后返回规范 DID 并回写为 active DID,保证后续 registry 查询与 relay connect.from 与服务端视图一致。
11. Relay 服务:Store-and-Forward 中继
中继为可能离线的 Agent 提供 store-and-forward 投递。
11.1 架构
Agent A ──WebSocket──► Relay ──WebSocket──► Agent B
│
┌────▼─────┐
│ Inbox DB │ (离线消息)
└──────────┘
11.2 连接
{
"v": 1,
"type": "connect",
"from": "did:agentmesh:sender",
"auth": {
"timestamp": "2026-04-21T19:00:00Z",
"signature": "<base64url(ed25519_sign(timestamp))>"
}
}
11.3 Store-and-Forward
- 离线 Agent 的消息存储在 Relay 的 inbox 数据库中;
- TTL:72 小时(按部署可配置);
- 投递: 重连时 Relay 推送所有待处理消息;
- 排序: 消息按每个发送方的发送顺序投递;
- 去重: 消息
id(UUID)用于幂等投递; - 确认: 接收方发送
ack帧,Relay 从 inbox 删除。
11.4 心跳
{
"v": 1,
"type": "heartbeat",
"from": "did:agentmesh:sender",
"ts": "2026-04-21T19:00:00Z"
}
间隔:30 秒。Relay 在 3 次心跳未收到(90 秒)后将 Agent 标记为离线。
11.5 仅密文存储
Relay 只存储密文,无法解密消息。Relay 能看到:发送方 DID、接收方 DID、消息 ID、时间戳和不可读的密文。这是刻意设计——Relay 对内容不可信。
源码印证:TypeScript MeshClient.connect()(mesh-client.ts)连接后发送含 public_key/timestamp/signature 的 connect 帧,随后发送 fetch_pending 帧请求离线期间排队的消息;收到 pending_messages 帧后逐条走标准 handleMessage 路径解密(handlePendingMessages,L961-L993)。同时,中继在另一连接以相同 DID 认证时会发送 WebSocket 关闭码 4006(WS_CLOSE_SESSION_REPLACED,L144),客户端据此识别"会话被顶替"且不得自动重连,以免两个连接互相顶替形成死循环。
12. 认证:Ed25519-Timestamp 与 SPIFFE/SVID
12.1 Ed25519-Timestamp(默认)
所有 registry 与 relay 请求的默认认证方案:
Authorization: Ed25519-Timestamp <did> <iso8601_timestamp> <base64url(signature)>
其中 signature = Ed25519.sign(private_key, utf8(iso8601_timestamp))。
服务端验证:
- 时间戳在重放窗口(±5 分钟)内;
- DID 已注册;
- 签名对已注册公钥有效。
12.2 SPIFFE/SVID(企业版)
适用于具备 PKI 基础设施的企业部署:
Authorization: Bearer <SVID-JWT>
其中 SVID JWT 包含映射到 DID 的 Agent SPIFFE ID。
12.3 认证模式选择
部署在 relay/registry 配置中声明认证模式:
auth_mode: "ed25519" # 默认 — 随处可用
# auth_mode: "svid" # 企业 — 需要 SPIFFE 基础设施
# auth_mode: "hybrid" # 两种都接受
13. 治理集成:策略在加解密前后介入
13.1 发送前策略检查
加密和发送消息前,治理层评估:
result = policy_engine.evaluate({
"action": "agentmesh.send",
"sender": sender_did,
"recipient": recipient_did,
"intent": knock_intent, # 来自打开本会话的 KNOCK
"message_number": n_send,
"session_age_seconds": elapsed,
})
if not result.allowed:
raise PermissionError(result.reason)
13.2 接收后策略检查
将解密内容返回应用之前:
result = policy_engine.evaluate({
"action": "agentmesh.receive",
"sender": sender_did,
"recipient": self_did,
"content_hash": sha256(plaintext),
})
13.3 审计
每次消息发送/接收尝试都记录到 AGT 审计追踪:
{
"event": "agentmesh.message",
"direction": "send",
"sender": "did:agentmesh:...",
"recipient": "did:agentmesh:...",
"message_id": "...",
"session_id": "...",
"policy_decision": "allow",
"timestamp": "..."
}
14. 协议版本化
14.1 版本字段
每个帧都包含 "v": <integer>。本规范定义 v: 1。
14.2 版本协商
connect 帧中,客户端声明支持的版本:
{
"v": 1,
"type": "connect",
"supported_versions": [1],
...
}
Relay 以双方共同支持的最高版本响应。
14.3 未来版本
| 版本 | 描述 |
|---|---|
| 1 | 本规范(Signal Protocol,点对点) |
| 2(规划中) | MLS 群组消息(RFC 9420) |
| 3(规划中) | 后量子密钥封装(ML-KEM) |
15. 安全考量
15.1 信任模型
- Relay 对内容不可信(只见密文),但对投递可信(可以丢弃或延迟消息);
- Registry 对预密钥分发可信(被攻破的注册表可通过替换预密钥执行中间人攻击);
- Agent 通过绑定到其 DID 的 Ed25519 签名认证。
15.2 前向保密
Double Ratchet 提供前向保密:每个消息密钥从棘轮状态派生、用后即弃。攻破当前棘轮状态只泄露未来消息(未来消息由 DH 棘轮步骤的后泄露安全保护)。
15.3 重放保护
- 每个消息密钥单次使用(由链棘轮派生);
- Relay 按消息
id(UUID)去重; - 跳过的消息密钥有可配置上限(默认 100)。
15.4 拒绝服务(DoS)
- Relay 实施每 Agent 速率限制(可配置);
- Registry 实施预密钥上传速率限制;
- KNOCK 协议允许接收方在密钥交换前拒绝会话。
15.5 已知限制
- v1 无群组消息——仅点对点;
- v1 无后量子密钥交换——仅 X25519;
- Relay 可观察流量模式(谁和谁通信、何时、消息大小);
- 无工作流级关联——治理评估单条消息,不评估消息序列。
16. 测试向量(Test Vectors)
16.1 X3DH 测试向量
规范当前给出的是占位框架(Alice/Bob 密钥对与期望共享密钥待填入),并注明:完整测试向量将从参考 Python 实现生成,并在规范定稿前与 TypeScript 实现交叉验证。值得注意,上文提到的 TypeScript kdf() 已导出以便测试套件对照与 AGT Python SDK 共享的跨运行时已知答案向量固定派生密钥(见 x3dh.ts),这正是交叉验证机制在源码中的落地。
16.2 Double Ratchet 测试向量
一次完整的 5 消息会话(含期望的中间棘轮状态)将作为 JSON 文件提供于 tests/vectors/ratchet-v1.json。
16.3 信封序列化测试向量
每种帧类型的规范 JSON 序列化将提供于 tests/vectors/envelope-v1.json。
17. 附录要点
17.1 知识产权与在先技术(Appendix A)
本规范是独立的洁净室设计(clean-room design),完全基于公开、自由许可的标准构建:IETF RFC(BCP 78 可自由实现)、CC0 许可的 Signal Foundation 规范、W3C 规范(免版税)以及 AGT 团队对 Agent 特有功能(KNOCK 协议、治理集成、Registry API、Relay 语义)的原创设计。规范不声称密码学原语上的新颖性,其创新贡献在于将成熟原语与 Agent 特有治理相结合:策略门控会话、携带意图的握手、信任评分身份、确定性审计追踪。
17.2 推荐密码学库(Appendix B)
实现必须使用经过审计的知名密码学库,禁止自研加密实现:
- Python:PyNaCl(libsodium,Apache 2.0,已是 AGT 依赖)提供 X25519/Ed25519;
cryptography(Apache 2.0 / BSD,已是 AGT 依赖)提供 HKDF、ChaCha20-Poly1305; - TypeScript/JavaScript:
@noble/curves(MIT,审计过、零依赖)提供 X25519/Ed25519;@noble/ciphers(MIT)提供 ChaCha20-Poly1305;@noble/hashes(MIT)提供 HKDF、SHA-256、HMAC; - Rust:
x25519-dalek(BSD-3-Clause)、ed25519-dalek(BSD-3-Clause,已是 AGT 依赖)、chacha20poly1305与hkdf(RustCrypto 项目,MIT / Apache 2.0); - .NET:
libsodium-core或NSec(MIT,libsodium 绑定); - Go:
golang.org/x/crypto(BSD-3-Clause)提供 X25519、Ed25519、HKDF、ChaCha20-Poly1305。
17.3 教程与演示路线图(Appendix C)
规范实现后计划提供的文档:E2E 加密 Agent 消息教程(5 种语言)、KNOCK 协议与基于意图的会话教程、Relay + Registry 部署教程(Docker Compose + Helm)、双 Agent 加密对话演示、多 Agent 任务委派演示(KNOCK → 加密信道 → 任务交接 → 审计追踪)、离线 Agent 投递演示、Registry REST API 参考(OpenAPI)、Relay WebSocket 协议参考。
18. 参考资料
- Signal X3DH 规范(CC0);
- Signal Double Ratchet 规范(CC0);
- RFC 7748 — Elliptic Curves for Security(X25519);
- RFC 5869 — HKDF;
- RFC 8439 — ChaCha20 and Poly1305;
- RFC 8032 — Ed25519;
- RFC 9420 — MLS;
- W3C DID Core 规范;
- SPIFFE/SVID 规范。
延伸阅读: 与本文密切相关的还有 docs/specs/AGENTMESH-IDENTITY-TRUST-1.0.md(身份与信任评分)、docs/specs/AGENTMESH-TRUST-COORDINATION-1.0.md(信任协调)与 docs/specs/MCP-SECURITY-GATEWAY-1.0.md(MCP 安全网关);Python 参考实现的加密模块位于 agent-governance-python/agent-mesh/src/agentmesh/encryption/,TypeScript 实现位于 agent-governance-typescript/src/encryption/(含 x3dh.ts、ratchet.ts、mesh-client.ts、registry-client.ts),Rust 实现位于 agent-governance-rust/agentmesh/src/。