395 lines
11 KiB
Markdown
395 lines
11 KiB
Markdown
# A2N 协议（Agent-to-N Protocol）
|
||
|
||
> 版本：1.0.0
|
||
> 状态：规范
|
||
> 层级：子协议层
|
||
> 基于：[灵隙原始协议](01_raw-protocol.md)、[A2A 协议](02_a2a-protocol.md)
|
||
> 前缀：`group:` / `inter_group:`
|
||
|
||
---
|
||
|
||
## 1. 定位
|
||
|
||
A2N 协议定义多个 Agent 组成群组进行协同工作的规范，包括群组管理、任务拆分与合并、群体决策、角色与权限、升级机制等。
|
||
|
||
**适用场景**：
|
||
- 复杂任务的拆分与并行执行（MapReduce 模式）
|
||
- 多 Agent 协同完成单一目标
|
||
- 群体投票与共识决策
|
||
- 临时或永久的 Agent 工作组
|
||
- 分级升级机制
|
||
|
||
**依赖关系**：
|
||
- 群组内成员间的单播通信复用 A2A 协议
|
||
|
||
---
|
||
|
||
## 2. 功能定义
|
||
|
||
### 2.1 群组管理
|
||
|
||
| 功能 | 说明 |
|
||
|-----|------|
|
||
| 群组创建 | Coordinator 创建群组，定义拓扑结构 |
|
||
| 群组解散 | Coordinator 解散群组 |
|
||
| 加入群组 | Agent 主动申请加入 |
|
||
| 离开群组 | 成员主动离开 |
|
||
| 邀请加入 | Coordinator 或成员邀请其他 Agent |
|
||
| 接受邀请 | 被邀请者接受邀请 |
|
||
| 拒绝邀请 | 被邀请者拒绝邀请 |
|
||
| 成员更新通知 | 成员变动时广播通知 |
|
||
| 角色变更 | Coordinator 调整成员角色 |
|
||
| 群组冻结 | 暂停群组活动 |
|
||
| 群组解冻 | 恢复群组活动 |
|
||
|
||
### 2.2 群组通信
|
||
|
||
| 功能 | 说明 |
|
||
|-----|------|
|
||
| 广播 | 发送给所有成员 |
|
||
| 组播 | 发送给指定成员列表 |
|
||
| 单播 | 群内点对点（复用 A2A） |
|
||
| 消息中继 | 通过其他成员转发消息 |
|
||
|
||
### 2.3 任务协作
|
||
|
||
| 功能 | 说明 |
|
||
|-----|------|
|
||
| 任务拆分 | Coordinator 将大任务拆分为子任务 |
|
||
| 任务分配 | 子任务分配给指定 Worker |
|
||
| 子任务进度 | Worker 上报子任务进度 |
|
||
| 结果合并 | Coordinator 合并子任务结果 |
|
||
|
||
### 2.4 共识投票
|
||
|
||
| 功能 | 说明 |
|
||
|-----|------|
|
||
| 发起投票 | Coordinator 或 Reviewer 发起投票 |
|
||
| 提交投票 | 成员提交选项及理由 |
|
||
| 达成共识 | 公布投票结果 |
|
||
|
||
### 2.5 升级机制
|
||
|
||
| 功能 | 说明 |
|
||
|-----|------|
|
||
| 共识僵局升级 | 投票无法达成共识时升级给人类 |
|
||
| 子任务阻塞升级 | 子任务阻塞时升级给人类 |
|
||
| 跨群组升级 | 升级到更高层级群组 |
|
||
|
||
---
|
||
|
||
## 3. 消息类型定义
|
||
|
||
### 3.1 群组管理消息（前缀 `group:`）
|
||
|
||
| 消息类型 | 说明 |
|
||
|---------|------|
|
||
| `group:create` | 创建群组 |
|
||
| `group:disband` | 解散群组 |
|
||
| `group:join` | 加入群组 |
|
||
| `group:leave` | 离开群组 |
|
||
| `group:invite` | 邀请加入 |
|
||
| `group:accept_invite` | 接受邀请 |
|
||
| `group:reject_invite` | 拒绝邀请 |
|
||
| `group:member_update` | 成员更新通知 |
|
||
| `group:role_change` | 角色变更 |
|
||
|
||
### 3.2 群组通信消息（前缀 `group:`）
|
||
|
||
| 消息类型 | 说明 |
|
||
|---------|------|
|
||
| `group:broadcast` | 广播（所有成员） |
|
||
| `group:multicast` | 组播（指定成员） |
|
||
| `group:direct` | 群内单播 |
|
||
| `group:relay` | 消息中继 |
|
||
|
||
### 3.3 任务协作消息（前缀 `group:`）
|
||
|
||
| 消息类型 | 说明 |
|
||
|---------|------|
|
||
| `group:task_split` | 任务拆分 |
|
||
| `group:task_assign` | 任务分配 |
|
||
| `group:task_merge` | 结果合并 |
|
||
| `group:task_progress` | 子任务进度 |
|
||
|
||
### 3.4 共识投票消息（前缀 `group:`）
|
||
|
||
| 消息类型 | 说明 |
|
||
|---------|------|
|
||
| `group:vote` | 发起投票 |
|
||
| `group:vote_submit` | 提交投票 |
|
||
| `group:consensus` | 达成共识 |
|
||
|
||
### 3.5 HiL 升级消息（前缀 `group:` / `inter_group:`）
|
||
|
||
| 消息类型 | 说明 |
|
||
|---------|------|
|
||
| `group:consensus_escalate` | 共识僵局升级给人类 |
|
||
| `group:subtask_escalate` | 子任务阻塞升级给人类 |
|
||
| `group:human_decision` | 人类决策结果 |
|
||
| `inter_group:escalate` | 跨群组升级 |
|
||
|
||
---
|
||
|
||
## 4. 核心概念定义
|
||
|
||
### 4.1 群组拓扑结构
|
||
|
||
| 拓扑类型 | 说明 | 适用场景 |
|
||
|---------|------|---------|
|
||
| `star` | 星型，中心 coordinator 协调 | 简单任务分发 |
|
||
| `mesh` | 网状，成员间可直接通信 | 对等协作 |
|
||
| `chain` | 链式，流水线模式 | 顺序处理 |
|
||
| `hierarchical` | 层级型，多层管理 | 大型复杂任务 |
|
||
| `fullmesh` | 全连接网状 | 高可靠协作 |
|
||
|
||
### 4.2 成员角色
|
||
|
||
| 角色 | 说明 | 权限 |
|
||
|------|------|------|
|
||
| `coordinator` | 协调者 | 创建/解散群组、任务拆分、发起投票、角色变更 |
|
||
| `worker` | 工作者 | 执行子任务、提交结果、投票 |
|
||
| `reviewer` | 审核者 | 审核结果、发起投票、升级请求 |
|
||
| `observer` | 观察者 | 只读，查看进度 |
|
||
|
||
### 4.3 群组状态
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| `creating` | 创建中 |
|
||
| `active` | 活跃 |
|
||
| `frozen` | 冻结（不可执行新任务） |
|
||
| `disbanded` | 已解散（终态） |
|
||
|
||
### 4.4 合并策略
|
||
|
||
| 策略 | 说明 |
|
||
|------|------|
|
||
| `first_success` | 首个成功结果即返回 |
|
||
| `majority` | 多数结果合并 |
|
||
| `weighted` | 按权重加权合并 |
|
||
| `custom` | 自定义合并逻辑 |
|
||
|
||
### 4.5 共识类型
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| `majority` | 多数投票（>50%） |
|
||
| `supermajority` | 绝对多数（>67%） |
|
||
| `unanimity` | 一致同意（100%） |
|
||
| `weighted` | 加权投票 |
|
||
|
||
---
|
||
|
||
## 5. 群组生命周期
|
||
|
||
### 5.1 状态流转
|
||
|
||
```
|
||
creating → active → frozen → disbanded
|
||
↑ ↓
|
||
└─────────┘
|
||
解冻
|
||
```
|
||
|
||
### 5.2 群组创建流程
|
||
|
||
```
|
||
创建者(Coordinator) 被邀请成员
|
||
| |
|
||
|---- group:invite ---------------->| 发送邀请
|
||
| |
|
||
|<--- group:accept_invite ----------| 接受邀请
|
||
| |
|
||
|---- group:member_update --------->| 通知成员更新
|
||
| |
|
||
[群组状态变为 active] |
|
||
```
|
||
|
||
### 5.3 群组解散流程
|
||
|
||
```
|
||
Coordinator 所有成员
|
||
| |
|
||
|---- group:disband --------------->| 通知解散
|
||
| |
|
||
[群组状态变为 disbanded] |
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 任务协作流程
|
||
|
||
### 6.1 MapReduce 模式
|
||
|
||
```
|
||
Coordinator
|
||
│
|
||
group:task_split（拆分任务）
|
||
│
|
||
┌─────────────────┼─────────────────┐
|
||
▼ ▼ ▼
|
||
Worker1 Worker2 Worker3
|
||
│ │ │
|
||
│ 执行子任务 │ 执行子任务 │ 执行子任务
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
子任务结果 子任务结果 子任务结果
|
||
└─────────────────┼─────────────────┘
|
||
│
|
||
group:task_merge（合并结果）
|
||
▼
|
||
最终结果
|
||
```
|
||
|
||
### 6.2 流程步骤
|
||
|
||
1. **任务拆分阶段**
|
||
- Coordinator 接收原始任务
|
||
- 将任务拆分为多个子任务
|
||
- 为每个子任务指定执行的 Worker
|
||
- 定义合并策略
|
||
|
||
2. **并行执行阶段**
|
||
- 各 Worker 并行执行子任务
|
||
- 定期上报进度
|
||
- 子任务完成后上报结果
|
||
|
||
3. **结果合并阶段**
|
||
- Coordinator 收集所有子任务结果
|
||
- 按合并策略合并结果
|
||
- 返回最终结果
|
||
|
||
---
|
||
|
||
## 7. 共识投票流程
|
||
|
||
```
|
||
发起者(vote发起) 所有成员
|
||
| |
|
||
|---- group:vote ------------------>| 发起投票
|
||
| |
|
||
|<--- group:vote_submit (各成员) ---| 提交投票
|
||
| |
|
||
|---- group:consensus ------------->| 公布结果
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 载荷结构定义
|
||
|
||
### 8.1 群组创建载荷
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:----:|------|
|
||
| `group_id` | string | ✓ | 群组唯一标识 |
|
||
| `group_name` | string | - | 群组名称 |
|
||
| `topology` | string | ✓ | 拓扑结构 |
|
||
| `config` | object | - | 群组配置 |
|
||
|
||
### 8.2 群组配置
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `max_members` | integer | 最大成员数 |
|
||
| `vote_threshold` | float | 投票阈值 |
|
||
| `default_consensus_type` | string | 默认共识类型 |
|
||
|
||
### 8.3 子任务结构
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:----:|------|
|
||
| `subtask_id` | string | ✓ | 子任务标识 |
|
||
| `description` | string | ✓ | 子任务描述 |
|
||
| `assigned_to` | string | ✓ | 执行者 Agent ID |
|
||
| `dependencies` | array | - | 依赖的子任务 ID 列表 |
|
||
| `status` | string | ✓ | 子任务状态 |
|
||
| `payload` | object | ✓ | 子任务参数 |
|
||
|
||
### 8.4 投票载荷
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:----:|------|
|
||
| `vote_id` | string | ✓ | 投票标识 |
|
||
| `question` | string | ✓ | 投票问题 |
|
||
| `options` | array | ✓ | 选项列表 |
|
||
| `consensus_type` | string | ✓ | 共识类型 |
|
||
| `deadline` | string | - | 截止时间 |
|
||
|
||
### 8.5 投票提交载荷
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:----:|------|
|
||
| `vote_id` | string | ✓ | 投票标识 |
|
||
| `voter_id` | string | ✓ | 投票者 ID |
|
||
| `option_id` | string | ✓ | 选择的选项 |
|
||
| `reasoning` | string | - | 投票理由 |
|
||
|
||
### 8.6 共识结果载荷
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:----:|------|
|
||
| `vote_id` | string | ✓ | 投票标识 |
|
||
| `winner` | string | ✓ | 获胜选项 |
|
||
| `vote_counts` | object | ✓ | 各选项票数 |
|
||
| `passed` | boolean | ✓ | 是否通过阈值 |
|
||
|
||
---
|
||
|
||
## 9. 升级机制
|
||
|
||
### 9.1 升级场景
|
||
|
||
| 场景 | 消息类型 | 说明 |
|
||
|------|---------|------|
|
||
| 共识僵局 | `group:consensus_escalate` | 投票超时未达成共识 |
|
||
| 子任务阻塞 | `group:subtask_escalate` | 子任务执行受阻 |
|
||
| 跨群组 | `inter_group:escalate` | 升级到上级群组 |
|
||
|
||
### 9.2 升级载荷
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|:----:|------|
|
||
| `escalation_id` | string | ✓ | 升级标识 |
|
||
| `escalation_type` | string | ✓ | 升级类型 |
|
||
| `escalation_level` | integer | ✓ | 升级级别（1/2/3） |
|
||
| `context` | object | ✓ | 升级上下文 |
|
||
| `options` | array | - | 可选方案 |
|
||
|
||
---
|
||
|
||
## 10. 错误处理
|
||
|
||
群组错误码分段：7000-7999
|
||
|
||
| 错误码 | 名称 | 说明 |
|
||
|------|------|------|
|
||
| 7001 | 群组不存在 | |
|
||
| 7002 | 群组未激活 | |
|
||
| 7003 | 成员不存在 | |
|
||
| 7004 | 不是群组成员 | |
|
||
| 7005 | 未达成共识 | |
|
||
| 7006 | 角色不存在 | |
|
||
| 7007 | 已是成员 | |
|
||
| 7008 | 群组已满 | |
|
||
|
||
---
|
||
|
||
## 11. 接口要求
|
||
|
||
Agent 实现 A2N 协议时必须提供：
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| 群组管理处理器 | 处理群组创建、加入、离开等 |
|
||
| 子任务处理器 | 执行分配的子任务 |
|
||
| 投票处理器 | 处理投票相关消息 |
|
||
| 升级处理器 | 处理升级请求 |
|
||
|
||
---
|
||
|
||
## 12. 与其他协议的关系
|
||
|
||
- **依赖原始协议**：使用统一消息信封
|
||
- **依赖 A2A 协议**：群内单播通信复用 A2A
|
||
- **被 P2A 协议封装**：外部调用可触发群组任务 |