灵隙(synapse) v1.0.0 版本
This commit is contained in:
335
docs/v1/04_p2a-protocol.md
Normal file
335
docs/v1/04_p2a-protocol.md
Normal file
@@ -0,0 +1,335 @@
|
||||
# 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 消息 |
|
||||
Reference in New Issue
Block a user