335 lines
9.2 KiB
Markdown
335 lines
9.2 KiB
Markdown
# 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 消息 | |