灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-29 02:12:44 +08:00
parent 2c59efe0ca
commit 65710a4536
27 changed files with 1819 additions and 760 deletions

View File

@@ -15,12 +15,14 @@ P2A 协议定义**非 Agent 调用方**(如普通后端服务、前端应用
本协议将 A2A 协议的复杂性封装起来,提供简洁的 RESTful API,使调用方无需了解 A2A 协议细节即可使用 Agent 能力。
**适用场景**:
- 前端应用直接调用 Agent 能力
- 后端业务系统集成 Agent 服务
- 第三方开发者通过 API 接入
- 无需实现完整 A2A 协议的调用方
**设计原则**:
- **简单易用**:标准 RESTful API,JSON 格式
- **两种模式**:回调模式 + 轮询模式,调用方按需选择
- **认证简单**:API Key 认证,无需 HMAC 签名
@@ -33,44 +35,44 @@ P2A 协议定义**非 Agent 调用方**(如普通后端服务、前端应用
### 2.1 任务提交
| 功能 | 说明 |
|-----|------|
| JSON 提交 | application/json 格式提交任务 |
| Multipart 提交 | 带文件上传的任务提交 |
| 功能 | 说明 |
|--------------|-------------------------|
| JSON 提交 | application/json 格式提交任务 |
| Multipart 提交 | 带文件上传的任务提交 |
### 2.2 任务查询
| 功能 | 说明 |
|-----|------|
| 功能 | 说明 |
|------|---------------|
| 任务详情 | 获取完整任务信息(含结果) |
| 任务状态 | 简化版状态查询 |
| 任务列表 | 分页查询任务列表 |
| 任务状态 | 简化版状态查询 |
| 任务列表 | 分页查询任务列表 |
### 2.3 任务控制
| 功能 | 说明 |
|-----|------|
| 功能 | 说明 |
|------|-----------|
| 任务取消 | 取消正在执行的任务 |
### 2.4 能力查询
| 功能 | 说明 |
|-----|------|
| 功能 | 说明 |
|------|------------------|
| 能力清单 | 获取 Agent 支持的任务类型 |
### 2.5 通知机制
| 功能 | 说明 |
|-----|------|
| 功能 | 说明 |
|------|--------------|
| 回调通知 | 任务完成后主动回调调用方 |
| 轮询查询 | 调用方主动查询状态 |
| 轮询查询 | 调用方主动查询状态 |
### 2.6 认证
| 功能 | 说明 |
|-----|------|
| API Key 认证 | X-API-Key 头部认证 |
| 回调验证 | X-Callback-Token 验证回调来源 |
| 功能 | 说明 |
|------------|-------------------------|
| API Key 认证 | X-API-Key 头部认证 |
| 回调验证 | X-Callback-Token 验证回调来源 |
---
@@ -80,15 +82,15 @@ P2A 协议定义**非 Agent 调用方**(如普通后端服务、前端应用
### 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 | `/task` | 提交任务(JSON) |
| POST | `/task/multipart` | 提交任务(带文件上传) |
| GET | `/task/{task_id}` | 获取任务详情 |
| GET | `/task/{task_id}/status` | 获取任务状态(简化版) |
| GET | `/tasks` | 获取任务列表 |
| POST | `/task/{task_id}/cancel` | 取消任务 |
| GET | `/capabilities` | 获取能力清单 |
---
@@ -96,13 +98,13 @@ P2A 协议定义**非 Agent 调用方**(如普通后端服务、前端应用
P2A 协议使用简化状态(5 种):
| 状态 | 说明 |
|------|------|
| `received` | 已接收 |
| `processing` | 处理中 |
| `completed` | 已完成(终态) |
| `failed` | 已失败(终态) |
| `cancelled` | 已取消(终态) |
| 状态 | 说明 |
|--------------|---------|
| `received` | 已接收 |
| `processing` | 处理中 |
| `completed` | 已完成(终态) |
| `failed` | 已失败(终态) |
| `cancelled` | 已取消(终态) |
状态流转:
@@ -119,6 +121,7 @@ received → processing → completed
### 5.1 API Key 认证
传递方式:
- HTTP Header:`X-API-Key: {api_key}`
- URL Query:`?api_key={api_key}`
@@ -134,26 +137,26 @@ received → processing → completed
### 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 |
| 字段 | 类型 | 必填 | 说明 |
|--------------------|--------|:--:|------------------------------------------------|
| `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 | - | 上传的文件(可多个) |
| 字段 | 类型 | 必填 | 说明 |
|--------------------|--------------|:--:|----------------|
| `task_type` | string | ✓ | 任务类型 |
| `payload` | string(JSON) | ✓ | 任务参数(JSON 字符串) |
| `external_task_id` | string | - | 外部任务 ID |
| `priority` | string | - | 优先级 |
| `callback_url` | string | - | 回调 URL |
| `callback_token` | string | - | 回调 token |
| `file` | file | - | 上传的文件(可多个) |
---
@@ -161,77 +164,77 @@ received → processing → completed
### 7.1 任务提交响应
| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 是否成功 |
| `task_id` | string | 服务端生成的任务 ID |
| `status` | string | 初始状态(通常为 `received`) |
| `message` | string | 提示信息 |
| `error` | object | 错误信息(失败时) |
| 字段 | 类型 | 说明 |
|-----------|---------|----------------------|
| `success` | boolean | 是否成功 |
| `task_id` | string | 服务端生成的任务 ID |
| `status` | string | 初始状态(通常为 `received`) |
| `message` | string | 提示信息 |
| `error` | object | 错误信息(失败时) |
### 7.2 任务详情响应
| 字段 | 类型 | 说明 |
|------|------|------|
| 字段 | 类型 | 说明 |
|-----------|---------|------|
| `success` | boolean | 是否成功 |
| `task` | object | 任务详情 |
| `error` | object | 错误信息 |
| `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 | 错误信息 |
| 字段 | 类型 | 说明 |
|----------------|---------|------------------------|
| `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 | 偏移量 |
| 字段 | 类型 | 说明 |
|------------|---------|-------|
| `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 | 是否支持群组协作 |
| 字段 | 类型 | 说明 |
|----------------------------|---------|------------|
| `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 | 描述 |
| 字段 | 类型 | 说明 |
|------------------|--------|--------------------|
| `type` | string | 任务类型标识 |
| `name` | string | 任务类型名称 |
| `description` | string | 描述 |
| `estimated_time` | string | 预估耗时(如 "30s-2min") |
| `input_schema` | string | 输入 Schema |
| `output_schema` | string | 输出 Schema |
| `capabilities` | array | 所需能力列表 |
| `input_schema` | string | 输入 Schema |
| `output_schema` | string | 输出 Schema |
| `capabilities` | array | 所需能力列表 |
---
@@ -241,40 +244,40 @@ received → processing → completed
当任务完成时,服务端向调用方提供的 `callback_url` 发送回调:
| 字段 | 类型 | 说明 |
|------|------|------|
| `task_id` | string | 任务 ID |
| `external_task_id` | string | 外部任务 ID(如有) |
| `status` | string | 任务状态 |
| `progress` | integer | 进度 |
| `result` | object | 任务结果 |
| `error` | object | 错误信息 |
| `timestamp` | string | 时间戳(RFC3339) |
| 字段 | 类型 | 说明 |
|--------------------|---------|--------------|
| `task_id` | string | 任务 ID |
| `external_task_id` | string | 外部任务 ID(如有) |
| `status` | string | 任务状态 |
| `progress` | integer | 进度 |
| `result` | object | 任务结果 |
| `error` | object | 错误信息 |
| `timestamp` | string | 时间戳(RFC3339) |
### 8.2 回调 Header
| Header | 说明 |
|--------|------|
| Header | 说明 |
|--------------------|------------------------------------|
| `X-Callback-Token` | 回调验证 token(如调用方提供了 callback_token) |
| `Content-Type` | `application/json` |
| `Content-Type` | `application/json` |
---
## 9. 错误响应结构
| 字段 | 类型 | 说明 |
|------|------|------|
| 字段 | 类型 | 说明 |
|-----------|---------|-------|
| `success` | boolean | false |
| `error` | object | 错误详情 |
| `error` | object | 错误详情 |
错误详情结构:
| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | integer | 数字错误码 |
| `category` | string | 错误类别 |
| `message` | string | 错误描述 |
| `details` | object | 详细信息 |
| 字段 | 类型 | 说明 |
|---------------|---------|-----------|
| `code` | integer | 数字错误码 |
| `category` | string | 错误类别 |
| `message` | string | 错误描述 |
| `details` | object | 详细信息 |
| `retry_after` | integer | 重试等待时间(秒) |
---
@@ -284,6 +287,7 @@ received → processing → completed
### 10.1 回调模式
调用方提供 `callback_url`:
- 任务状态变化时主动回调
- 无需轮询
- 适用于实时性要求高的场景
@@ -291,6 +295,7 @@ received → processing → completed
### 10.2 轮询模式
调用方不提供 `callback_url`:
- 需主动调用 `/task/{task_id}/status` 查询
- 适用于无法接收回调的场景
- 推荐轮询间隔:5-10 秒
@@ -298,6 +303,7 @@ received → processing → completed
### 10.3 混合模式
调用方提供 `callback_url`,同时支持轮询:
- 回调为主,轮询兜底
- 适用于高可靠性场景
@@ -311,13 +317,13 @@ received → processing → completed
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` 等 |
| 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` 等 |
---
@@ -325,11 +331,11 @@ P2A 协议是 A2A 协议的"简化入口":
实现 P2A 协议的服务端必须提供:
| 接口 | 说明 |
|------|------|
| 任务接收端点 | 接收任务提交请求 |
| 任务查询端点 | 提供任务状态和结果查询 |
| 任务取消端点 | 支持任务取消 |
| 能力查询端点 | 提供能力清单 |
| 回调发送器 | 支持向调用方回调 |
| 接口 | 说明 |
|---------|--------------------|
| 任务接收端点 | 接收任务提交请求 |
| 任务查询端点 | 提供任务状态和结果查询 |
| 任务取消端点 | 支持任务取消 |
| 能力查询端点 | 提供能力清单 |
| 回调发送器 | 支持向调用方回调 |
| A2A 转换器 | 将 P2A 请求转换为 A2A 消息 |