504 lines
12 KiB
Markdown
504 lines
12 KiB
Markdown
# P2A 协议（Person/Program-to-Agent Protocol）
|
||
|
||
> 版本：1.0.0
|
||
> 状态：草案
|
||
> 类型：实现规范
|
||
> 基于：[灵隙原始协议（Synapse Raw Protocol） v1.0.0](./01-a2a-raw-protocol.md)
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
P2A（Person/Program-to-Agent）调用协议定义了**非 Agent 调用方**（如普通后端服务、前端应用、第三方系统、人类用户）如何调用 Agent 能力的规范。
|
||
|
||
本协议将 A2A 协议的复杂性封装起来，提供简洁的 RESTful API，使调用方无需了解 A2A 协议细节即可使用 Agent 能力。
|
||
|
||
### 1.1 适用场景
|
||
- 前端应用直接调用 Agent 能力
|
||
- 后端业务系统集成 Agent 服务
|
||
- 第三方开发者通过 API 接入
|
||
- 无需实现完整 A2A 协议的调用方
|
||
|
||
### 1.2 设计原则
|
||
- **简单易用**：标准 RESTful API，JSON 格式
|
||
- **两种模式**：回调模式 + 轮询模式，调用方按需选择
|
||
- **认证简单**：API Key 认证，无需 HMAC 签名
|
||
- **文件支持**：支持 multipart/form-data 上传文件
|
||
- **错误友好**：清晰的错误码和错误信息
|
||
|
||
### 1.3 与 A2A 协议的关系
|
||
|
||
```
|
||
外部调用方 ──P2A 协议──▶ External API Layer ──A2A 协议──▶ Agent
|
||
```
|
||
|
||
P2A 协议是 A2A 协议的"简化入口"，所有请求最终会转换为 灵隙消息发送给 Agent。
|
||
|
||
---
|
||
|
||
## 2. 认证方式
|
||
|
||
### 2.1 API Key 认证
|
||
- 在 HTTP Header 中传递：`X-API-Key: {api_key}`
|
||
- 或在 URL Query 中传递：`?api_key={api_key}`
|
||
- 如果服务端未配置 API Key，则跳过认证
|
||
|
||
### 2.2 回调验证（可选）
|
||
如果调用方提供了 `callback_token`，则服务端在回调时会在 Header 中带上 `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` | 获取能力清单 |
|
||
| POST | `/callback` | 接收回调（调用方实现） |
|
||
|
||
---
|
||
|
||
## 4. 任务提交
|
||
|
||
### 4.1 提交任务（JSON）
|
||
|
||
**请求：**
|
||
```http
|
||
POST /api/v1/synapse/task
|
||
Content-Type: application/json
|
||
X-API-Key: your-api-key
|
||
|
||
{
|
||
"task_type": "text_generation",
|
||
"payload": {
|
||
"prompt": "写一首诗",
|
||
"style": "古典"
|
||
},
|
||
"external_task_id": "my-task-001",
|
||
"priority": "normal",
|
||
"callback_url": "https://your-domain.com/callback",
|
||
"callback_token": "your-callback-token"
|
||
}
|
||
```
|
||
|
||
**请求字段说明：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `task_type` | string | 是 | 任务类型，如 `video_generation`, `image_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 |
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"task_id": "task-abc123",
|
||
"status": "received",
|
||
"message": "任务已接收"
|
||
}
|
||
```
|
||
|
||
**响应字段说明：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `success` | bool | 是否成功 |
|
||
| `task_id` | string | 服务端生成的任务 ID |
|
||
| `status` | string | 初始状态，通常为 `received` |
|
||
| `message` | string | 提示信息 |
|
||
| `error` | string | 错误信息（失败时） |
|
||
|
||
### 4.2 提交任务（Multipart 带文件）
|
||
|
||
**请求：**
|
||
```http
|
||
POST /api/v1/synapse/task/multipart
|
||
Content-Type: multipart/form-data
|
||
X-API-Key: your-api-key
|
||
|
||
------WebKitFormBoundary
|
||
Content-Disposition: form-data; name="task_type"
|
||
|
||
image_generation
|
||
|
||
------WebKitFormBoundary
|
||
Content-Disposition: form-data; name="payload"
|
||
|
||
{"prompt":"一只猫","style":"写实"}
|
||
|
||
------WebKitFormBoundary
|
||
Content-Disposition: form-data; name="priority"
|
||
|
||
normal
|
||
|
||
------WebKitFormBoundary
|
||
Content-Disposition: form-data; name="file"; filename="reference.jpg"
|
||
Content-Type: image/jpeg
|
||
|
||
[二进制数据]
|
||
|
||
------WebKitFormBoundary--
|
||
```
|
||
|
||
**表单字段：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `task_type` | string | 是 | 任务类型 |
|
||
| `payload` | string(JSON) | 是 | 任务参数（JSON 字符串） |
|
||
| `external_task_id` | string | 否 | 外部任务 ID |
|
||
| `priority` | string | 否 | 优先级 |
|
||
| `callback_url` | string | 否 | 回调 URL |
|
||
| `callback_token` | string | 否 | 回调 token |
|
||
| `file` | file | 否 | 上传的文件（可多个） |
|
||
|
||
**响应：** 同 JSON 提交方式
|
||
|
||
---
|
||
|
||
## 5. 任务查询
|
||
|
||
### 5.1 获取任务详情
|
||
|
||
**请求：**
|
||
```http
|
||
GET /api/v1/synapse/task/{task_id}
|
||
X-API-Key: your-api-key
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"task": {
|
||
"id": "task-abc123",
|
||
"type": "text_generation",
|
||
"status": "completed",
|
||
"progress": 100,
|
||
"message": "任务已完成",
|
||
"created_at": "2026-01-01T00:00:00Z",
|
||
"updated_at": "2026-01-01T00:01:00Z",
|
||
"completed_at": "2026-01-01T00:01:00Z",
|
||
"eta": "2026-01-01T00:01:00Z",
|
||
"result": {
|
||
"text": "生成的文本...",
|
||
"metadata": { "tokens": 1024 }
|
||
},
|
||
"error": null,
|
||
"external_task_id": "my-task-001"
|
||
}
|
||
}
|
||
```
|
||
|
||
**任务状态：**
|
||
|
||
| 状态 | 说明 |
|
||
|------|------|
|
||
| `received` | 已接收 |
|
||
| `processing` | 处理中 |
|
||
| `completed` | 已完成 |
|
||
| `failed` | 已失败 |
|
||
| `cancelled` | 已取消 |
|
||
|
||
### 5.2 获取任务状态（简化版）
|
||
|
||
**请求：**
|
||
```http
|
||
GET /api/v1/synapse/task/{task_id}/status
|
||
X-API-Key: your-api-key
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"task_id": "task-abc123",
|
||
"status": "processing",
|
||
"progress": 50
|
||
}
|
||
```
|
||
|
||
### 5.3 获取任务列表
|
||
|
||
**请求：**
|
||
```http
|
||
GET /api/v1/synapse/tasks?status=processing&limit=20&offset=0
|
||
X-API-Key: your-api-key
|
||
```
|
||
|
||
**查询参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `status` | string | 否 | 按状态过滤 |
|
||
| `limit` | int | 否 | 每页数量，默认 20 |
|
||
| `offset` | int | 否 | 偏移量，默认 0 |
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"tasks": [
|
||
{
|
||
"id": "task-abc123",
|
||
"type": "text_generation",
|
||
"status": "completed",
|
||
"progress": 100,
|
||
"created_at": "2026-01-01T00:00:00Z",
|
||
"updated_at": "2026-01-01T00:01:00Z"
|
||
}
|
||
],
|
||
"total": 1,
|
||
"limit": 20,
|
||
"offset": 0,
|
||
"has_more": false
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 任务取消
|
||
|
||
**请求：**
|
||
```http
|
||
POST /api/v1/synapse/task/{task_id}/cancel
|
||
X-API-Key: your-api-key
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"task_id": "task-abc123",
|
||
"status": "cancelled",
|
||
"message": "任务已取消"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 能力查询
|
||
|
||
**请求：**
|
||
```http
|
||
GET /api/v1/synapse/capabilities
|
||
X-API-Key: your-api-key
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"capabilities": {
|
||
"agent_id": "my-agent",
|
||
"agent_name": "我的Agent",
|
||
"system_id": "my-system",
|
||
"protocol_version": "1.0.0",
|
||
"supported_task_types": [
|
||
{
|
||
"type": "text_generation",
|
||
"name": "文本生成",
|
||
"description": "生成各种类型的文本内容",
|
||
"estimated_time": "30s",
|
||
"input_schema": "...",
|
||
"output_schema": "..."
|
||
}
|
||
],
|
||
"supported_transport_modes": ["callback", "polling"],
|
||
"max_file_size": 104857600,
|
||
"max_concurrent_tasks": 10,
|
||
"support_progress_updates": true,
|
||
"support_streaming": false,
|
||
"support_hil": true,
|
||
"support_groups": true
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 回调机制
|
||
|
||
如果调用方提供了 `callback_url`，服务端会在任务状态变化时主动回调。
|
||
|
||
### 8.1 回调请求
|
||
|
||
```http
|
||
POST {callback_url}
|
||
Content-Type: application/json
|
||
X-Callback-Token: {callback_token}
|
||
|
||
{
|
||
"task_id": "task-abc123",
|
||
"status": "completed",
|
||
"progress": 100,
|
||
"message": "任务已完成",
|
||
"result": {
|
||
"text": "生成的文本..."
|
||
},
|
||
"error": null,
|
||
"timestamp": "2026-01-01T00:01:00Z"
|
||
}
|
||
```
|
||
|
||
### 8.2 回调类型
|
||
|
||
| 触发时机 | 说明 |
|
||
|---------|------|
|
||
| 任务开始处理 | `status=processing`, `progress=0` |
|
||
| 进度更新 | `status=processing`, `progress=N` |
|
||
| 任务完成 | `status=completed`, `progress=100`, 包含 result |
|
||
| 任务失败 | `status=failed`, 包含 error |
|
||
| 任务取消 | `status=cancelled` |
|
||
|
||
### 8.3 回调响应
|
||
|
||
调用方应返回 2xx 状态码表示成功接收。如果返回非 2xx，服务端会重试（指数退避，最多 5 次）。
|
||
|
||
---
|
||
|
||
## 9. 错误处理
|
||
|
||
### 9.1 错误响应格式
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "invalid_task_type",
|
||
"message": "不支持的任务类型"
|
||
}
|
||
```
|
||
|
||
### 9.2 错误码列表
|
||
|
||
| 错误码 | HTTP 状态码 | 说明 |
|
||
|--------|------------|------|
|
||
| `unauthorized` | 401 | API Key 无效或缺失 |
|
||
| `invalid_request` | 400 | 请求格式无效 |
|
||
| `invalid_task_type` | 400 | 任务类型不支持 |
|
||
| `invalid_params` | 400 | 参数无效 |
|
||
| `task_not_found` | 404 | 任务不存在 |
|
||
| `task_already_completed` | 409 | 任务已完成，无法取消 |
|
||
| `file_too_large` | 413 | 文件过大 |
|
||
| `rate_limited` | 429 | 请求过于频繁 |
|
||
| `internal_error` | 500 | 服务内部错误 |
|
||
| `service_unavailable` | 503 | 服务不可用 |
|
||
|
||
---
|
||
|
||
## 10. SDK 客户端接口
|
||
|
||
为方便调用方集成，提供 SDK 客户端。
|
||
|
||
### 10.1 SDK 初始化
|
||
|
||
```go
|
||
client := sdk.NewClient(sdk.ClientConfig{
|
||
BaseURL: "https://agent-api.example.com",
|
||
APIKey: "your-api-key",
|
||
Timeout: 30 * time.Second,
|
||
})
|
||
```
|
||
|
||
### 10.2 SDK 方法清单
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| `SubmitTask(ctx, req)` | 提交任务（JSON） |
|
||
| `SubmitTaskWithFiles(ctx, req, files)` | 提交任务（带文件） |
|
||
| `GetTask(ctx, taskID)` | 获取任务详情 |
|
||
| `GetTaskStatus(ctx, taskID)` | 获取任务状态 |
|
||
| `ListTasks(ctx, status, limit, offset)` | 获取任务列表 |
|
||
| `CancelTask(ctx, taskID)` | 取消任务 |
|
||
| `GetCapabilities(ctx)` | 获取能力清单 |
|
||
| `WaitForTask(ctx, taskID, interval)` | 等待任务完成（轮询） |
|
||
|
||
### 10.3 数据结构
|
||
|
||
```go
|
||
type TaskRequest struct {
|
||
TaskType string
|
||
Payload map[string]any
|
||
ExternalTaskID string
|
||
Priority string
|
||
CallbackURL string
|
||
CallbackToken string
|
||
}
|
||
|
||
type TaskInfo struct {
|
||
ID string
|
||
Type string
|
||
Status string
|
||
Progress int
|
||
Message string
|
||
CreatedAt string
|
||
UpdatedAt string
|
||
CompletedAt string
|
||
ETA string
|
||
Result map[string]any
|
||
Error *TaskError
|
||
ExternalTaskID string
|
||
}
|
||
```
|
||
|
||
**完整 SDK 实现：** [sdk/client.go](../sdk/client.go)
|
||
|
||
---
|
||
|
||
## 11. 参考实现
|
||
|
||
本协议的参考实现：
|
||
|
||
| 模块 | 文件路径 | 说明 |
|
||
|------|---------|------|
|
||
| 服务端 | [externalapi/handler.go](../externalapi/handler.go) | External API Handler |
|
||
| 客户端 SDK | [sdk/client.go](../sdk/client.go) | Go 语言 SDK |
|
||
|
||
---
|
||
|
||
## 附录 A：调用模式选择
|
||
|
||
### 回调模式 vs 轮询模式
|
||
|
||
| 对比项 | 回调模式 | 轮询模式 |
|
||
|--------|---------|---------|
|
||
| 实时性 | 高，状态变化即时通知 | 低，取决于轮询间隔 |
|
||
| 实现复杂度 | 调用方需提供公网可访问的回调接口 | 简单，只需调用 GET 接口 |
|
||
| 网络要求 | 调用方需要公网可达 | 只需调用方能访问服务端 |
|
||
| 适用场景 | 生产环境、需要实时通知 | 开发测试、内网环境 |
|
||
|
||
### 选择建议
|
||
|
||
- **有公网服务器**：使用回调模式
|
||
- **本地开发 / 内网环境**：使用轮询模式
|
||
- **长时间任务**：建议回调模式，避免频繁轮询
|
||
- **短任务（<10s）**：可直接同步等待或高频轮询
|
||
|
||
---
|
||
|
||
## 附录 B：从 A2A 协议到 P2A 协议的映射
|
||
|
||
| 灵隙概念 | P2A 对应 | 说明 |
|
||
|---------|---------|------|
|
||
| `p2p:task_request` | `POST /task` | 任务提交 |
|
||
| `p2p:task_status_update` | 回调 / GET /task | 状态更新 |
|
||
| `p2p:task_complete` | 回调（status=completed） | 任务完成 |
|
||
| `p2p:task_failed` | 回调（status=failed） | 任务失败 |
|
||
| `p2p:task_cancel` | `POST /task/{id}/cancel` | 任务取消 |
|
||
| `p2p:capability_query` | `GET /capabilities` | 能力查询 |
|
||
| Agent 身份 | API Key | 简化认证 |
|
||
| HMAC 签名 | Callback Token | 简化验证 |
|