# P2A 协议（Person/Program-to-Agent Protocol）

> 版本：1.0.0
> 状态：规范
> 层级：子协议层
> 基于：[灵隙原始协议](01_raw-protocol.md)
> 前缀：`caller:`（内部转换）

---

## 1. 定位

P2A 协议定义**非 Agent 调用方**（如普通后端服务、前端应用、第三方系统、人类用户）如何调用 Agent 能力的规范。

本协议将 A2A 协议的复杂性封装起来，提供简洁的 RESTful API，使调用方无需了解 A2A 协议细节即可使用 Agent 能力。

**适用场景**：
- 前端应用直接调用 Agent 能力
- 后端业务系统集成 Agent 服务
- 第三方开发者通过 API 接入
- 无需实现完整 A2A 协议的调用方

**设计原则**：
- **简单易用**：标准 RESTful API，JSON 格式
- **两种模式**：回调模式 + 轮询模式，调用方按需选择
- **认证简单**：API Key 认证，无需 HMAC 签名
- **文件支持**：支持 multipart/form-data 上传文件
- **错误友好**：清晰的错误码和错误信息

---

## 2. 功能定义

### 2.1 任务提交

| 功能 | 说明 |
|-----|------|
| JSON 提交 | application/json 格式提交任务 |
| Multipart 提交 | 带文件上传的任务提交 |

### 2.2 任务查询

| 功能 | 说明 |
|-----|------|
| 任务详情 | 获取完整任务信息（含结果） |
| 任务状态 | 简化版状态查询 |
| 任务列表 | 分页查询任务列表 |

### 2.3 任务控制

| 功能 | 说明 |
|-----|------|
| 任务取消 | 取消正在执行的任务 |

### 2.4 能力查询

| 功能 | 说明 |
|-----|------|
| 能力清单 | 获取 Agent 支持的任务类型 |

### 2.5 通知机制

| 功能 | 说明 |
|-----|------|
| 回调通知 | 任务完成后主动回调调用方 |
| 轮询查询 | 调用方主动查询状态 |

### 2.6 认证

| 功能 | 说明 |
|-----|------|
| API Key 认证 | X-API-Key 头部认证 |
| 回调验证 | X-Callback-Token 验证回调来源 |

---

## 3. API 端点定义

所有端点默认前缀：`/api/v1/synapse`

### 3.1 端点清单

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/task` | 提交任务（JSON） |
| POST | `/task/multipart` | 提交任务（带文件上传） |
| GET | `/task/{task_id}` | 获取任务详情 |
| GET | `/task/{task_id}/status` | 获取任务状态（简化版） |
| GET | `/tasks` | 获取任务列表 |
| POST | `/task/{task_id}/cancel` | 取消任务 |
| GET | `/capabilities` | 获取能力清单 |

---

## 4. 任务状态定义

P2A 协议使用简化状态（5 种）：

| 状态 | 说明 |
|------|------|
| `received` | 已接收 |
| `processing` | 处理中 |
| `completed` | 已完成（终态） |
| `failed` | 已失败（终态） |
| `cancelled` | 已取消（终态） |

状态流转：

```
received → processing → completed
                       → failed
                       → cancelled
```

---

## 5. 认证方式

### 5.1 API Key 认证

传递方式：
- HTTP Header：`X-API-Key: {api_key}`
- URL Query：`?api_key={api_key}`

如果服务端未配置 API Key，则跳过认证。

### 5.2 回调验证（可选）

如果调用方提供了 `callback_token`，则服务端在回调时会在 Header 中带上 `X-Callback-Token`，用于调用方验证回调来源。

---

## 6. 请求结构定义

### 6.1 任务提交请求（JSON）

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_type` | string | ✓ | 任务类型（如 `text_generation`） |
| `payload` | object | ✓ | 任务参数（结构由 task_type 决定） |
| `external_task_id` | string | - | 调用方的任务 ID，用于关联 |
| `priority` | string | - | 优先级：`low`/`normal`/`high`/`urgent`，默认 `normal` |
| `callback_url` | string | - | 回调 URL，不提供则需轮询 |
| `callback_token` | string | - | 回调验证 token |

### 6.2 任务提交请求（Multipart）

| 字段 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `task_type` | string | ✓ | 任务类型 |
| `payload` | string(JSON) | ✓ | 任务参数（JSON 字符串） |
| `external_task_id` | string | - | 外部任务 ID |
| `priority` | string | - | 优先级 |
| `callback_url` | string | - | 回调 URL |
| `callback_token` | string | - | 回调 token |
| `file` | file | - | 上传的文件（可多个） |

---

## 7. 响应结构定义

### 7.1 任务提交响应

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 是否成功 |
| `task_id` | string | 服务端生成的任务 ID |
| `status` | string | 初始状态（通常为 `received`） |
| `message` | string | 提示信息 |
| `error` | object | 错误信息（失败时） |

### 7.2 任务详情响应

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 是否成功 |
| `task` | object | 任务详情 |
| `error` | object | 错误信息 |

### 7.3 任务详情结构

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 任务 ID |
| `type` | string | 任务类型 |
| `status` | string | 任务状态 |
| `progress` | integer | 进度百分比（0-100） |
| `message` | string | 状态说明 |
| `created_at` | string | 创建时间（RFC3339） |
| `updated_at` | string | 更新时间（RFC3339） |
| `completed_at` | string | 完成时间（RFC3339） |
| `eta` | string | 预估完成时间 |
| `result` | object | 任务结果（结构由 task_type 决定） |
| `error` | object | 错误信息 |

### 7.4 任务列表响应

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 是否成功 |
| `tasks` | array | 任务列表 |
| `total` | integer | 总数 |
| `limit` | integer | 每页数量 |
| `offset` | integer | 偏移量 |
| `has_more` | boolean | 是否有更多 |

### 7.5 能力清单响应

| 字段 | 类型 | 说明 |
|------|------|------|
| `agent_id` | string | Agent 唯一标识 |
| `agent_name` | string | Agent 名称 |
| `protocol_version` | string | 协议版本 |
| `supported_task_types` | array | 支持的任务类型列表 |
| `supported_content_types` | array | 支持的内容类型 |
| `max_file_size` | integer | 最大文件大小（字节） |
| `max_concurrent_tasks` | integer | 最大并发任务数 |
| `max_task_duration` | integer | 最大任务时长（秒） |
| `support_progress_updates` | boolean | 是否支持进度更新 |
| `support_streaming` | boolean | 是否支持流式传输 |
| `support_hil` | boolean | 是否支持人类介入 |
| `support_groups` | boolean | 是否支持群组协作 |

### 7.6 任务类型能力

| 字段 | 类型 | 说明 |
|------|------|------|
| `type` | string | 任务类型标识 |
| `name` | string | 任务类型名称 |
| `description` | string | 描述 |
| `estimated_time` | string | 预估耗时（如 "30s-2min"） |
| `input_schema` | string | 输入 Schema |
| `output_schema` | string | 输出 Schema |
| `capabilities` | array | 所需能力列表 |

---

## 8. 回调结构定义

### 8.1 回调请求

当任务完成时，服务端向调用方提供的 `callback_url` 发送回调：

| 字段 | 类型 | 说明 |
|------|------|------|
| `task_id` | string | 任务 ID |
| `external_task_id` | string | 外部任务 ID（如有） |
| `status` | string | 任务状态 |
| `progress` | integer | 进度 |
| `result` | object | 任务结果 |
| `error` | object | 错误信息 |
| `timestamp` | string | 时间戳（RFC3339） |

### 8.2 回调 Header

| Header | 说明 |
|--------|------|
| `X-Callback-Token` | 回调验证 token（如调用方提供了 callback_token） |
| `Content-Type` | `application/json` |

---

## 9. 错误响应结构

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | false |
| `error` | object | 错误详情 |

错误详情结构：

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 数字错误码 |
| `category` | string | 错误类别 |
| `message` | string | 错误描述 |
| `details` | object | 详细信息 |
| `retry_after` | integer | 重试等待时间（秒） |

---

## 10. 传输模式

### 10.1 回调模式

调用方提供 `callback_url`：
- 任务状态变化时主动回调
- 无需轮询
- 适用于实时性要求高的场景

### 10.2 轮询模式

调用方不提供 `callback_url`：
- 需主动调用 `/task/{task_id}/status` 查询
- 适用于无法接收回调的场景
- 推荐轮询间隔：5-10 秒

### 10.3 混合模式

调用方提供 `callback_url`，同时支持轮询：
- 回调为主，轮询兜底
- 适用于高可靠性场景

---

## 11. 与 A2A 协议的关系

```
外部调用方 ──P2A REST API──▶ External API Layer ──A2A 消息──▶ Agent
```

P2A 协议是 A2A 协议的"简化入口"：

| P2A API | A2A 消息映射 |
|---------|-------------|
| POST `/task` | `p2p:task_request` |
| GET `/task/{id}` | 内部状态查询 |
| POST `/task/{id}/cancel` | `p2p:task_cancel` |
| GET `/capabilities` | `p2p:capability_query` + `p2p:capability_response` |
| 回调发送 | `p2p:task_complete` / `p2p:task_failed` 等 |

---

## 12. 接口要求

实现 P2A 协议的服务端必须提供：

| 接口 | 说明 |
|------|------|
| 任务接收端点 | 接收任务提交请求 |
| 任务查询端点 | 提供任务状态和结果查询 |
| 任务取消端点 | 支持任务取消 |
| 能力查询端点 | 提供能力清单 |
| 回调发送器 | 支持向调用方回调 |
| A2A 转换器 | 将 P2A 请求转换为 A2A 消息 |