ai/synapse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4aa746f2c99d098ea4b2dbaf37c8a11928811da3
synapse/docs/v1/02_a2a-protocol.md
lychang 812f68d5aa 灵隙(synapse) v1.0.0 版本
2026-06-28 03:24:26 +08:00

10 KiB
Raw Blame History

A2A 协议（Agent-to-Agent Protocol）

版本：1.0.0 状态：规范 层级：子协议层 基于：灵隙原始协议 前缀：p2p:

1. 定位

A2A 协议定义两个 Agent 之间进行点对点任务协作的规范，包括任务提交、进度同步、信息补全、人类介入、能力发现等核心交互。

适用场景：

  • 单个任务请求与响应
  • 任务状态实时同步
  • 任务取消
  • 信息补全交互
  • 人类介入决策

非适用场景：

  • 多 Agent 群组协作（参见 A2N 协议）
  • 非 Agent 调用方接入（参见 P2A 协议）

2. 功能定义

2.1 任务管理

功能 说明
任务提交 请求方向执行方提交任务
任务确认 执行方接受任务
任务拒绝 执行方拒绝任务（附带原因）
任务取消 请求方中途取消任务
任务进度 执行方实时上报进度
任务完成 执行方上报成功结果
任务失败 执行方上报失败原因

2.2 信息补全

功能 说明
信息请求 执行方发现缺少必要信息时请求补充
信息提供 请求方提供补充信息

2.3 人类介入（HiL）

功能 说明
HiL 请求 执行方请求人类决策
HiL 响应 请求方返回人类决策结果

2.4 能力发现

功能 说明
能力查询 查询对方支持的任务类型和能力
能力响应 返回能力清单

2.5 保活与确认

功能 说明
心跳 双向心跳保活
ACK 任务级确认
消息 ACK 消息级确认
消息 NACK 消息级否定确认（附带错误）

3. 消息类型定义

所有消息类型前缀：p2p:

3.1 任务类消息

消息类型 方向 说明
p2p:task_request 请求方 → 执行方 提交任务请求
p2p:task_confirm 执行方 → 请求方 确认接受任务
p2p:task_reject 执行方 → 请求方 拒绝任务
p2p:task_status_update 执行方 → 请求方 任务进度更新
p2p:task_complete 执行方 → 请求方 任务完成
p2p:task_failed 执行方 → 请求方 任务失败
p2p:task_cancel 请求方 → 执行方 取消任务
p2p:task_ack 双向 任务级确认

3.2 信息类消息

消息类型 方向 说明
p2p:task_need_info 执行方 → 请求方 请求补充信息
p2p:task_info_provided 请求方 → 执行方 提供补充信息

3.3 HiL 类消息

消息类型 方向 说明
p2p:task_need_human 执行方 → 请求方 请求人类介入
p2p:human_decision 请求方 → 执行方 人类决策结果

3.4 能力类消息

消息类型 方向 说明
p2p:capability_query 双向 查询对方能力
p2p:capability_response 双向 返回能力清单

3.5 保活与确认类消息

消息类型 方向 说明
p2p:heartbeat 双向 心跳保活
p2p:ack 双向 通用确认
p2p:nack 双向 通用否定确认

4. 任务状态机

4.1 状态定义

状态 说明
idle 空闲（初始状态）
pending 待确认（已发送请求）
confirmed 已确认（执行方接受）
executing 执行中
info_needed 需要信息
info_provided 信息已提供
need_human 需要人类介入
human_deciding 人类决策中
human_approved 人类已批准
human_rejected 人类已拒绝
completed 已完成（终态）
failed 已失败（终态）
cancelled 已取消（终态）
rejected 已拒绝（终态）

4.2 状态流转

请求方视角：

idle → pending → confirmed → executing → completed
                   ↓            ↓         → failed
              rejected     info_needed    → cancelled
                                ↑↓
                           info_provided
                                ↓
                            need_human
                                ↑↓
                           human_deciding
                                ↓
                         human_approved / human_rejected

5. 交互流程

5.1 正常任务流程

请求方                              执行方
  |                                   |
  |---- p2p:task_request ------------>|  提交任务
  |                                   |
  |<--- p2p:task_confirm -------------|  确认接受
  |                                   |
  |<--- p2p:task_status_update (多次) --|  进度更新
  |                                   |
  |<--- p2p:task_complete ------------|  完成通知
  |                                   |
  |---- p2p:task_ack ---------------->|  确认收到

5.2 信息补全流程

请求方                              执行方
  |                                   |
  |---- p2p:task_request ------------>|
  |                                   |
  |<--- p2p:task_need_info -----------|  发现信息缺失
  |                                   |
  |---- p2p:task_info_provided ------->|  补充信息
  |                                   |
  |<--- p2p:task_status_update -------|  继续执行

5.3 人类介入流程

请求方                              执行方
  |                                   |
  |---- p2p:task_request ------------>|
  |                                   |
  |<--- p2p:task_need_human ----------|  需要人类决策
  |                                   |
  |  [人类做出决策]                    |
  |                                   |
  |---- p2p:human_decision ---------->|  决策结果
  |                                   |
  |<--- p2p:task_status_update -------|  继续执行

5.4 任务取消流程

请求方                              执行方
  |                                   |
  |---- p2p:task_request ------------>|
  |                                   |
  |---- p2p:task_cancel ------------->|  取消任务
  |                                   |
  |<--- p2p:task_ack -----------------|  确认取消

5.5 任务拒绝流程

请求方                              执行方
  |                                   |
  |---- p2p:task_request ------------>|
  |                                   |
  |<--- p2p:task_reject --------------|  拒绝（附带原因）

6. 载荷结构定义

6.1 task_request 载荷

字段 类型 必填 说明
task_id string ✓ 任务唯一标识（请求方生成）
task_type string ✓ 任务类型
payload object ✓ 任务参数（结构由 task_type 决定）
priority string - 优先级：low/normal/high/urgent
transport_preferences object - 传输偏好（回调/轮询等）

6.2 task_confirm 载荷

字段 类型 必填 说明
task_id string ✓ 任务标识
estimated_time string - 预估耗时（如 "30s-2min"）

6.3 task_reject 载荷

字段 类型 必填 说明
task_id string ✓ 任务标识
reason object ✓ 拒绝原因（含错误码和描述）

6.4 task_status_update 载荷

字段 类型 必填 说明
task_id string ✓ 任务标识
status string ✓ 当前状态
progress integer - 进度百分比（0-100）
message string - 状态说明
eta string - 预估完成时间

6.5 task_complete 载荷

字段 类型 必填 说明
task_id string ✓ 任务标识
result object ✓ 任务结果（结构由 task_type 决定）
summary string - 结果摘要
metadata object - 结果元数据

6.6 task_failed 载荷

字段 类型 必填 说明
task_id string ✓ 任务标识
error object ✓ 错误信息（错误码 + 描述 + 详情）

6.7 task_need_info 载荷

字段 类型 必填 说明
task_id string ✓ 任务标识
missing_fields array ✓ 缺失的字段列表
reason string ✓ 缺失原因

6.8 task_info_provided 载荷

字段 类型 必填 说明
task_id string ✓ 任务标识
provided_info object ✓ 补充的信息

6.9 task_need_human 载荷

字段 类型 必填 说明
task_id string ✓ 任务标识
escalation_level integer ✓ 升级级别（1/2/3）
reason object ✓ 介入原因
options array - 可选方案列表
suggested_value object - Agent 建议值

6.10 human_decision 载荷

字段 类型 必填 说明
task_id string ✓ 任务标识
decision object ✓ 决策内容
decided_by object ✓ 决策者信息（用户 ID + 角色）

7. 错误处理

参见数字分段错误码系统（1000-9999）：

分段 类别
1000-1999 系统错误
2000-2999 任务错误
3000-3999 信息错误
4000-4999 能力错误
5000-5999 安全错误
6000-6999 通信错误

8. 接口要求

Agent 实现 A2A 协议时必须提供：

接口 说明
消息处理器 接收并处理 p2p:* 类型消息
任务处理器 执行具体任务逻辑
回调发送器 发送进度、完成、失败等回调
状态查询 支持任务状态查询

9. 与其他协议的关系

  • 依赖原始协议：使用统一消息信封、签名机制
  • 被 A2N 协议依赖：群组内单播通信复用 A2A
  • 被 P2A 协议封装：外部调用最终转换为 A2A 消息