# A2A 协议（Agent-to-Agent Protocol）

> 版本：1.0.0
> 状态：规范
> 层级：子协议层
> 基于：[灵隙原始协议](01_raw-protocol.md)
> 前缀：`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 消息