Skip to content

JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.

Python
19.7 KB
Raw Blame

E2A(Everything-to-Agent)协议说明

实现:jiuwenswarm/common/e2a/(models.py、adapters.py、constants.py、__init__.py)。版本:E2A_PROTOCOL_VERSION(默认 1.0)。冲突时:以 models.py 中 dataclass 字段为最终实现源,并回头修正本文。请求:E2AEnvelope;响应:E2AResponse。
English:../en/E2A-protocol.md


0. 文档位置与单一真源

位置 角色
docs/zh/E2A-protocol.md(本文,中文) 规范说明、易混点、示例
docs/en/E2A-protocol.md 同上,英文版
jiuwenswarm/common/e2a/models.py 请求 E2AEnvelope、响应 E2AResponse 与子结构;from_dict / to_dict
jiuwenswarm/common/e2a/constants.py E2A_SOURCE_PROTOCOL_*、E2A_RESPONSE_KINDS、E2A_RESPONSE_STATUS_*、ACP 方法名与 SessionUpdate 字符串(运行时以元组为准)
jiuwenswarm/common/e2a/adapters.py ACP / A2A → E2A;E2A → ACP JSON-RPC;E2AResponse → ACP / A2A 投影(见 §8)
jiuwenswarm/common/e2a/__init__.py 对外导出

1. 定位与边界

  • 经 Gateway 规范化之后发往 AgentServer 的载荷,用 E2A 表达;通道原始字段在 Gateway 入口映射到规范化字段(user_id、message_id、params 等),不要求把整包 channel JSON 当作 E2A 主路径。
  • channel_context:可选;仅过渡或无法落入规范化字段的残余键;from_dict 可将旧 metadata 迁入以兼容历史。
  • E2A 不规定传输层(WebSocket、HTTP 等)。

2. 易混点:method 的两种含义(必读)

同一字段 method 在不同来源下含义不同,不是两套字段,也不要与 request_id / message_id 混用。

来源 method 典型取值 说明
网关 → AgentServer chat.send、history.get、chat.interrupt、… 项目内 RPC 名;不在 constants.ACP_CLIENT_TO_AGENT_METHODS 中枚举
ACP 经 envelope_from_acp_jsonrpc 转入 session/prompt、initialize、… 与 JSON-RPC method 一致;完整列表以 constants.ACP_CLIENT_TO_AGENT_METHODS 为准
内部特殊 null 例如心跳等无 RPC 枚举的场景

出口转 ACP:envelope_to_acp_jsonrpc_call 仅在 method == "session/prompt" 时经 merge_params_to_acp_prompt 从 params 补全 prompt;若当前 method 为 chat.send,需另行在业务适配层映射为 ACP 的 session/prompt 与 params,否则生成的 JSON-RPC 对纯 ACP 端无效。


3. 与 ACP、A2A 的关系(摘要)

维度 ACP A2A E2A(对内)
角色 JSON-RPC 会话 Task / Message / Card 统一信封;外部经适配器转入
method JSON-RPC method 抽象操作(绑定层映射) 见 §2
扩展 _meta metadata 网关用规范化字段;a2a_metadata / acp_meta 仅互操作

4. E2AEnvelope 字段表

4.1 基础与关联

字段 类型 说明
protocol_version string 默认 1.0
request_id string / null 网关↔AgentServer 主 id(流式 chunk 对齐)
jsonrpc_id string / number / null ACP 转入时的 JSON-RPC id
correlation_id string / null 追踪链,与 request_id 分工不同
task_id / context_id string / null A2A 对齐
session_id string / null 会话
message_id string / null 平台或 A2A 消息 id;语义勿与 request_id 混
is_stream boolean 是否流式响应

4.2 provenance(E2AProvenance)

字段 说明
source_protocol e2a / acp / a2a(常量见 E2A_SOURCE_PROTOCOL_*)
converter / converted_at / details 转换组件、时间、线索(如 jsonrpc_method)

手工构造且未改默认时 source_protocol 为 e2a。旧字段 binding 会迁入 provenance.details.migrated_from_binding(兼容)。

4.3 时间、身份、入口

字段 说明
timestamp 规范:RFC 3339 UTC 字符串;from_dict 可接受 float/int 纪元秒并规范化
identity_origin system / user / agent / service
channel 入口名;只写 channel。from_dict 可读 channel_id
user_id / source_agent_id 用户或上游 Agent

timestamp(业务时刻)≠ provenance.converted_at(转入 E2A 时刻)。

4.4 method、params、桥接

字段 说明
method 见 §2;from_dict 可读 req_method
params 唯一业务参数字典(与 JSON-RPC params 对齐):RPC 选项、用户正文、多模态块、附件等全部放在此对象内,不再使用顶层 payload(见下表约定)
ext_method method == "ext" 时的真实名
session_update_kind 桥接 ACP session/update 时,与 constants.ACP_SESSION_UPDATE_KINDS 一致
expected_output_modes A2A acceptedOutputModes

params 常用键约定(可按业务扩展,以下为与 ACP 桥接协作的推荐名):

键 用途
prompt 已是 ACP ContentBlock 数组时直接使用(merge_params_to_acp_prompt 不覆盖)
content_blocks 与 ACP Vec<ContentBlock> 同构的 JSON 数组;在 method==session/prompt 且无 prompt 时可映射为 prompt
text / content / query 纯文本用户输入;无 prompt/content_blocks 时取第一个非空字符串生成单条 text block
files / attachments 附件列表,元素形状见 E2AFileRef(uri 必填)
其他 如 mode、page_idx、心跳文案等,随网关 RPC 自由扩展

4.5 auth、扩展槽

字段 说明
auth E2AAuth:凭据引用等
channel_context 可选溢出 / 旧 metadata 兼容,见 §1
a2a_metadata 仅 A2A 互操作(与适配器参数名 metadata 对应)
acp_meta 在 merge_params_to_acp_prompt 中合并入 params._meta(见 §7)

5. 子结构(摘要)

  • E2AFileRef:附件元素推荐形状(uri 必填;name、mime_type、size、_meta 可选);通常出现在 params.files 或 params.attachments 数组中。
  • E2AAuth:method_id、bearer_token、api_key_ref、credential_ref、extra_headers、_meta

6. constants.py 中的 ACP 字符串(桥接参考)

以下仅用于 ACP 桥接或文档对照,运行时以 jiuwenswarm.common.e2a.constants 中元组为准:

  • ACP_CLIENT_TO_AGENT_METHODS:客户端 → Agent 的 JSON-RPC method 名
  • ACP_AGENT_TO_CLIENT_METHODS、ACP_NOTIFICATION_NAMES:下行 / 通知
  • ACP_SESSION_UPDATE_KINDS:session_update_kind 取值
  • E2A_RESPONSE_KINDS、E2A_RESPONSE_STATUS_*、E2A_A2A_STREAM_BRANCHES:响应 response_kind / status / a2a.stream_event.branch(见 §12)

网关 RPC(chat.send 等)由项目自行约定,不放在上述元组中。


7. merge_params_to_acp_prompt

Python:jiuwenswarm.common.e2a.merge_params_to_acp_prompt(envelope)。

当且仅当 method == "session/prompt" 时:

  1. 若 params 已有 prompt,不覆盖。
  2. 否则若 params.content_blocks 为非空数组,用作 prompt。
  3. 否则若 params.text、params.content、params.query 中有非空字符串,生成单条 { "type": "text", "text": "..." } 作为 prompt。
  4. 若信封有 session_id 且 params 无 session_id,则写入。
  5. 将 envelope.acp_meta 合并进 params._meta。

其他 method 直接返回 params 的浅拷贝。


8. 适配器(adapters.py)

函数 作用
envelope_from_acp_jsonrpc ACP JSON-RPC → E2A,provenance.source_protocol=acp,method 为 ACP method
envelope_from_a2a_send_message A2A SendMessage 语义 → E2A;参数 metadata 写入 a2a_metadata(A2A 专用,不是网关 metadata)
envelope_to_acp_jsonrpc_call E2A → JSON-RPC 描述;不修改 provenance
e2a_response_to_acp_jsonrpc_response E2AResponse → 单条 JSON-RPC 响应对象(result 或 error);不适用时返回 None
e2a_response_to_a2a_stream_payload E2AResponse(a2a.stream_event)→ A2A StreamResponse 形 JSON(四选一);不适用时返回 None

9. 序列化与兼容键

  • E2AEnvelope.to_dict() / from_dict(data)
  • 只读兼容:channel_id→channel,req_method→method,metadata→channel_context(仅当 channel_context 为空),binding→provenance(见上)
  • 可选:若 JSON 顶层仍存在旧键 payload(对象),其键会合并进 params(不覆盖 params 已有键),便于极少数遗留载荷;新协议不应再发顶层 payload。

10. 替代 AgentRequest 的字段对应

AgentRequest E2AEnvelope
request_id request_id
channel_id channel
session_id session_id
service_id service_id(可选;网关在使用 SessionMap 的受控通道上可填充,与 session_id 同源,供企业多租户 / Runtime 路由;需企业版 JIUWENSWARM_EDITION=enterprise)
agent_id agent_id(可选;同上;WebSocket AgentServer 可忽略)
req_method method
params params
is_stream is_stream
timestamp(float) timestamp(字符串,自动规范化)
metadata 目标态:映射进规范化字段;兼容:from_dict→channel_context

11. 示例(JSON 形状)

11.1 网关规范化后 → AgentServer(聊天,流式)

{
  "protocol_version": "1.0",
  "request_id": "req_abc_01",
  "session_id": "sess_xyz",
  "channel": "web",
  "method": "chat.send",
  "is_stream": true,
  "timestamp": "2026-03-28T12:00:00+00:00",
  "identity_origin": "user",
  "user_id": "u_001",
  "params": {
    "content": "你好",
    "mode": "plan",
    "query": "你好"
  },
  "provenance": {
    "source_protocol": "e2a"
  }
}

channel_context 可省略(空对象序列化时可不出现或 {})。

11.2 旧 AgentRequest 形状(from_dict 可读)

{
  "request_id": "req_legacy_1",
  "channel_id": "feishu",
  "session_id": "sess_feishu_1",
  "req_method": "chat.send",
  "is_stream": true,
  "timestamp": 1774524781.15,
  "params": {
    "content": "查桌面文件",
    "mode": "plan",
    "query": "查桌面文件"
  },
  "metadata": {
    "feishu_open_id": "ou_xxx",
    "message_id": "om_xxx"
  }
}

解析后:channel=feishu,method=chat.send,timestamp 变为 RFC 3339 字符串;若未单独映射,metadata 会进入 channel_context(迁移期)。目标态应在 Gateway 把 feishu_open_id 等写入 user_id / message_id 等,并尽量清空 channel_context。

11.3 ACP 转入(逻辑示例,由 envelope_from_acp_jsonrpc 构造)

  • method = "session/prompt"
  • jsonrpc_id = 42
  • params = { "session_id": "s1", "prompt": [...] }
  • provenance.source_protocol = "acp",details 含 jsonrpc_method 等

11.4 导出 ACP JSON-RPC(envelope_to_acp_jsonrpc_call 输出形状)

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "session/prompt",
  "params": {
    "session_id": "s1",
    "prompt": [{"type": "text", "text": "hi"}]
  }
}

仅当信封 method == "session/prompt" 且 params 中尚无 prompt 时,merge_params_to_acp_prompt 才会根据 content_blocks 或 text/content/query 补全 prompt。

11.5 session/prompt + 多模态(全在 params)

{
  "method": "session/prompt",
  "session_id": "s1",
  "jsonrpc_id": 1,
  "params": {
    "content_blocks": [
      {"type": "text", "text": "请描述这张图"},
      {"type": "image", "mime_type": "image/png", "data": "<base64 omitted>"}
    ]
  }
}

经 merge_params_to_acp_prompt 后,params 会多出与 content_blocks 等价的 prompt(若原本无 prompt)。


12. E2A 响应协议(E2AResponse)

Agent → 网关 → 客户端的每一条出站记录(含流式多帧)使用 E2AResponse 表达,与 E2AEnvelope 字段命名对称(snake_case、RFC 3339 timestamp、复用 E2AProvenance)。

12.1 三层结构

层级 名称 说明
L1 响应信封 关联 id、顺序、流结束、状态、出处
L2 判别载荷 response_kind + body(由 kind 约束)
L3 projections(可选) acp / a2a 键下存放已组装的对外协议 JSON,仅辅助;业务解析不得依赖 L3 作为唯一真源

12.2 is_final 与 status

  • is_final:true 表示同一 request_id 下不再会有后续 E2AResponse 记录。仅表示传输序列结束,不表示业务一定成功(失败帧也可 is_final: true)。
  • status:取 constants.E2A_RESPONSE_STATUS_*(succeeded / failed / in_progress)。当 status == failed 时,response_kind 应为 e2a.error(若同时使用 acp.jsonrpc_error 作投影,以本文 §12.6 为准)。

12.3 不变量(规范)

  • 同一 request_id:sequence 从 0 起严格递增(0, 1, 2, …)。
  • 正常结束:恰好一条记录的 is_final 为 true。
  • 异常(对端断连、进程崩溃):可能无法发送 is_final: true;实现上应通过超时与连接状态补偿,本文不强制「必须补发结束帧」。

12.4 L1:信封字段表

字段 类型 必填 说明
protocol_version string 是 与请求一致;默认 1.0
response_id string 是 本记录唯一 id(建议 UUID)
request_id string 是 回显请求;流式 chunk 对齐
sequence integer 是 同 request_id 下从 0 递增
is_final boolean 是 最后一帧为 true
status string 是 succeeded / failed / in_progress
response_kind string 是 见 §12.5;运行时以 constants.E2A_RESPONSE_KINDS 为准
timestamp string 是 RFC 3339 UTC;本记录生成时刻
provenance object 是 E2AProvenance(与请求相同结构)
body object 是 L2 载荷
jsonrpc_id string / number / null 否 回显 ACP JSON-RPC id
correlation_id string 否 分布式追踪
task_id / context_id / session_id / message_id string 否 与请求信封同义
is_stream boolean 否 是否对应流式请求(回显或推断)
identity_origin string 否 默认倾向 agent(响应来自 Agent)
channel / user_id / source_agent_id 同请求 否 回显
method string / null 否 回显请求的 method(含心跳 null)
metadata object 否 通道/业务自定义键值字典;与旧版 AgentResponse.metadata 对齐;协议转换失败时可临时写入兜底。AgentServer→Gateway WebSocket 整包旧 JSON 使用 constants.E2A_WIRE_LEGACY_AGENT_RESPONSE_KEY / E2A_WIRE_LEGACY_AGENT_CHUNK_KEY(_e2a_wire_legacy_*),与业务自定义键建议用通道前缀区分
projections object 否 L3:acp、a2a 可选键,值为任意 JSON
channel_context / a2a_metadata / acp_meta object 否 与请求对称的溢出槽;注意:与 metadata 分工不同——a2a_metadata / acp_meta 仅 ACP/A2A 互操作,metadata 为通用业务与兜底

12.5 L2:response_kind 与 body 要点

运行时以 constants.E2A_RESPONSE_KINDS 为准;body 为 dict,下列为规范性说明。

response_kind body 要点
e2a.complete result:业务结果对象(与请求的 params 哲学对称,避免无关键散落 L1)
e2a.chunk delta_kind:text / reasoning / tool / custom;delta:字符串或结构化对象;可选 mime_type
e2a.error code、message、details;可选 external:{ "protocol": "acp"|"a2a", "type": string, "payload": object }
acp.session_update 贴近 ACP session/update 通知负载;sessionUpdate 等字段与 ACP_SESSION_UPDATE_KINDS 对齐
acp.prompt_result 对应 session/prompt 的 JSON-RPC result(如 stop_reason、可选 usage、_meta)
acp.jsonrpc_error 等价 JSON-RPC error 语义:code、message、可选 data(与 e2a.error 并存时:内核以 e2a.error 表达失败;acp.jsonrpc_error 可作 L3 或专用 kind 仅供 ACP 边界)
a2a.task A2A Task 形对象;JSON 键名与官方 proto 的 JSON 映射一致(snake_case,与 spec/a2a.proto 字段对应)
a2a.message A2A Message 形对象(同上)
a2a.stream_event branch:task / message / status_update / artifact_update(常量 E2A_A2A_STREAM_BRANCHES);payload:对应分支对象
ext ext_method + params(与请求 ext 对称)

推荐策略:网关 / AgentServer 内部优先使用 e2a.complete / e2a.chunk / e2a.error;在出口适配层生成 acp.* / a2a.* 或写入 projections。

12.6 与 ACP / A2A 的映射(摘要)

  • ACP:JSON-RPC 响应由 jsonrpc_id + acp.prompt_result(result)或 e2a.error / acp.jsonrpc_error(error)映射;acp.session_update 对应 session/update 通知的 params。详见 e2a_response_to_acp_jsonrpc_response(§8)。
  • A2A:a2a.stream_event 与 StreamResponse 四分支一一对应;e2a_response_to_a2a_stream_payload 产出单事件 JSON。 a2a.task / a2a.message 对应 SendMessage 两种返回。

12.7 日志建议(如 E:\logs)

  • 一行一条完整 E2AResponse JSON,便于检索与按 sequence 重放。
  • 每条至少含 request_id、response_id、sequence、is_final、response_kind、timestamp。
  • 勿记录 bearer_token、完整模型输出中的敏感内容;大 body 可将来扩展 body_ref(本版未定义)。

12.8 示例:流式两帧 + 结束帧

{"protocol_version":"1.0","response_id":"r1","request_id":"req_1","sequence":0,"is_final":false,"status":"in_progress","response_kind":"e2a.chunk","timestamp":"2026-03-29T12:00:00+00:00","provenance":{"source_protocol":"e2a"},"body":{"delta_kind":"text","delta":"你好"}}
{"protocol_version":"1.0","response_id":"r2","request_id":"req_1","sequence":1,"is_final":false,"status":"in_progress","response_kind":"e2a.chunk","timestamp":"2026-03-29T12:00:01+00:00","provenance":{"source_protocol":"e2a"},"body":{"delta_kind":"text","delta":"世界"}}
{"protocol_version":"1.0","response_id":"r3","request_id":"req_1","sequence":2,"is_final":true,"status":"succeeded","response_kind":"e2a.complete","timestamp":"2026-03-29T12:00:02+00:00","provenance":{"source_protocol":"e2a"},"body":{"result":{"content":"你好世界"}}}

与 E2A-AgentRequest-log-migration.md 中的请求日志收编可对照:响应侧将来可同样约定统一前缀与单行 JSON。


13. 安全建议

  • 优先 credential_ref / api_key_ref,由网关换票;日志勿完整打印 bearer_token。
  • 跨域使用 TLS 与最小权限。

本文与 jiuwenswarm/common/e2a/models.py(E2AEnvelope、E2AResponse)同步维护。