ai/synapse

Fork 0

Files

lychang 65710a4536 灵隙(synapse) v1.0.0 版本

2026-06-29 02:12:44 +08:00

12 KiB

Raw Permalink Blame History

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

版本：1.0.0 状态：规范层级：子协议层基于：灵隙原始协议前缀：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 消息

12 KiB Raw Permalink Blame History Unescape Escape