354 lines
10 KiB
Markdown
354 lines
10 KiB
Markdown
# 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 消息 |