ai/synapse

Fork 0

Files

lychang 88b606b9ca 灵隙(synapse) v1.0.0 版本

2026-06-27 22:17:15 +08:00

12 KiB

Raw Blame History

A2A 协议（Agent-to-Agent Protocol）

版本：1.0.0
状态：草案
类型：实现规范
基于：灵隙原始协议（Synapse Raw Protocol） v1.0.0

1. 概述

A2A 协议定义了两个 Agent 之间进行点对点（P2P）任务协作的完整规范，包括消息类型、交互流程、状态机、接口定义与错误处理。

1.1 适用场景

单个任务请求与响应
任务状态实时同步
任务取消
信息补全交互
人类介入决策

1.2 非适用场景

多 Agent 群组协作（参见 A2N 组群协议）
非 Agent 调用方接入（参见 P2A 调用协议）

2. 消息类型

2.1 消息类型清单

所有消息类型前缀：p2p:

消息类型	方向	说明
`p2p:task_request`	请求方 → 执行方	提交任务请求
`p2p:task_confirm`	执行方 → 请求方	确认接受任务
`p2p:task_reject`	执行方 → 请求方	拒绝任务
`p2p:task_need_info`	执行方 → 请求方	请求补充信息
`p2p:task_info_provided`	请求方 → 执行方	提供补充信息
`p2p:task_status_update`	执行方 → 请求方	任务进度更新
`p2p:task_complete`	执行方 → 请求方	任务完成
`p2p:task_failed`	执行方 → 请求方	任务失败
`p2p:task_cancel`	请求方 → 执行方	取消任务
`p2p:task_ack`	双向	任务级确认
`p2p:ack`	双向	通用确认
`p2p:nack`	双向	通用否定确认（错误）
`p2p:heartbeat`	双向	心跳保活
`p2p:capability_query`	双向	查询对方能力
`p2p:capability_response`	双向	返回能力清单
`p2p:task_need_human`	执行方 → 请求方	请求人类介入
`p2p:human_decision`	请求方 → 执行方	人类决策结果

2.2 消息类型完整定义

参见代码：types/types.go

3. 任务状态机

3.1 状态定义

状态	说明
`idle`	空闲（初始状态）
`pending`	待确认（已发送请求，等待确认）
`confirmed`	已确认（对方接受任务）
`executing`	执行中
`info_needed`	需要信息
`info_provided`	信息已提供
`need_human`	需要人类介入
`human_deciding`	人类决策中
`human_approved`	人类已批准
`human_rejected`	人类已拒绝
`completed`	已完成（终态）
`failed`	已失败（终态）
`cancelled`	已取消（终态）
`rejected`	已拒绝（终态）

3.2 状态流转图

请求方视角：

idle → pending → confirmed → executing → completed
                   ↓            ↓         → failed
              rejected     info_needed    → cancelled
                                ↑↓
                           info_provided
                                ↓
                            need_human
                                ↑↓
                           human_decision

4. 核心交互流程

4.1 正常任务提交流程

请求方 Agent                          执行方 Agent
    |                                     |
    |-------- task_request ------------->|  1. 提交任务
    |                                     |
    |<------- task_confirm / task_reject -|  2. 确认/拒绝
    |                                     |
    |<------- task_status_update --------|  3. 进度更新（多次）
    |                                     |
    |<------- task_complete -------------|  4. 完成通知
    |                                     |
    |-------- task_ack ----------------->|  5. 确认收到
    |                                     |

4.2 信息补全流程

请求方 Agent                          执行方 Agent
    |                                     |
    |-------- task_request ------------->|
    |                                     |
    |<------- task_need_info ------------|  发现信息缺失
    |                                     |
    |-------- task_info_provided ------->|  补充信息
    |                                     |
    |<------- task_status_update --------|  继续执行
    |                                     |

4.3 人类介入流程

请求方 Agent                          执行方 Agent
    |                                     |
    |-------- task_request ------------->|
    |                                     |
    |<------- task_need_human -----------|  需要人类决策
    |                                     |
    |  [人类做出决策]                      |
    |                                     |
    |-------- human_decision ----------->|  决策结果
    |                                     |
    |<------- task_status_update --------|  继续执行
    |                                     |

4.4 任务取消流程

请求方 Agent                          执行方 Agent
    |                                     |
    |-------- task_request ------------->|
    |                                     |
    |-------- task_cancel -------------->|  取消任务
    |                                     |
    |<------- task_ack ------------------|  确认取消
    |                                     |

5. 接口规范

5.1 P2P 协议处理器接口

接口定义：

type P2PProtocol interface {
    // 处理收到的消息
    HandleMessage(ctx context.Context, msg *UnifiedSynapseMessage) (*UnifiedSynapseMessage, error)
    
    // 设置任务处理器
    SetTaskHandler(h TaskHandler)
    
    // 设置回调发送器
    SetCallbackSender(s CallbackSender)
    
    // 获取 Agent 端点
    AgentEndpoint() AgentEndpoint
    
    // 查询任务状态
    GetTaskStatus(taskID string) (P2PTaskStatus, bool)
    
    // 列出所有任务
    ListTasks() map[string]P2PTaskStatus
}

参考实现： p2p/protocol.go

5.2 任务处理器接口

type TaskHandler interface {
    // 执行任务并返回结果
    ExecuteTask(ctx context.Context, taskType string, payload map[string]interface{}) (any, error)
    
    // 验证任务是否可执行，返回缺失字段列表和是否可处理
    ValidateTask(taskType string, payload map[string]interface{}) ([]MissingField, bool)
    
    // 获取能力列表
    GetCapabilities() []string
}

说明：

ExecuteTask：实际执行业务逻辑的入口
ValidateTask：在任务确认前调用，用于判断是否接受任务或需要补充信息
GetCapabilities：返回 Agent 支持的任务类型列表

5.3 回调发送器接口

type CallbackSender interface {
    // 向远程 Agent 发送消息
    SendCallback(ctx context.Context, endpoint string, msg *UnifiedSynapseMessage) error
}

说明：

传输层实现此接口
支持多种传输方式（HTTP、gRPC、WebSocket 等）

5.4 配置项

type P2PConfig struct {
    MaxRetries        int           // 最大重试次数（默认 5）
    RetryBaseDelay    time.Duration // 重试基础延迟（默认 2s，指数退避）
    TaskTimeout       time.Duration // 任务执行超时（默认 5 分钟）
    HeartbeatInterval time.Duration // 心跳间隔（默认 30 秒）
}

6. 载荷格式

6.1 TaskRequestPayload（任务请求）

{
  "task": {
    "id": "task-xxx",
    "type": "text_generation",
    "priority": "normal",
    "deadline": "2026-01-01T00:00:00Z",
    "payload": {
      "prompt": "写一首诗",
      "style": "古典"
    }
  },
  "context": {
    "session_id": "sess-xxx",
    "parent_task_id": "parent-xxx",
    "correlation_id": "corr-xxx",
    "metadata": {}
  }
}

6.2 TaskConfirmPayload（任务确认）

{
  "task_id": "task-xxx",
  "confirmed": true,
  "estimated_duration": 120,
  "expected_completion": "2026-01-01T00:02:00Z",
  "capabilities_used": ["text_generation"],
  "constraints": {
    "max_retries": 3,
    "fallback_enabled": true
  }
}

6.3 TaskRejectPayload（任务拒绝）

{
  "task_id": "task-xxx",
  "reason": {
    "code": "capability_lacking",
    "message": "不支持该任务类型",
    "details": null
  },
  "alternatives": {
    "suggested_agent_id": "other-agent",
    "retry_after": 300,
    "partial_support": false
  }
}

6.4 TaskStatusUpdatePayload（状态更新）

{
  "task_id": "task-xxx",
  "status": "executing",
  "progress": 50,
  "message": "正在生成内容",
  "intermediate_result": null
}

6.5 TaskCompletePayload（任务完成）

{
  "task_id": "task-xxx",
  "result": {
    "output_type": "text",
    "output": "生成的文本内容...",
    "metadata": {
      "tokens": 1024,
      "model": "gpt-4"
    }
  },
  "summary": "任务已完成"
}

6.6 TaskFailedPayload（任务失败）

{
  "task_id": "task-xxx",
  "error": {
    "code": "execution_error",
    "message": "模型调用超时",
    "recoverable": true,
    "details": null
  },
  "partial_result": null
}

6.7 TaskNeedInfoPayload（需要信息）

{
  "task_id": "task-xxx",
  "missing_fields": [
    {
      "field": "style",
      "reason": "未指定生成风格",
      "suggested_value": "古典",
      "alternatives": ["现代", "浪漫"]
    }
  ],
  "question": "请选择生成风格",
  "required_by": "2026-01-01T00:01:00Z"
}

6.8 TaskNeedHumanPayload（需要人类）

{
  "task_id": "task-xxx",
  "reason": {
    "code": "ethical_decision",
    "message": "涉及伦理决策需要人工审核"
  },
  "context": {
    "task_summary": "生成一张人物肖像",
    "current_progress": 30,
    "blocked_reason": "需要确认肖像使用授权"
  },
  "options": [
    {
      "field": "authorized",
      "value": true,
      "pros_cons": "继续生成，假设已授权",
      "confidence": 70
    }
  ],
  "escalation_level": 1,
  "deadline": "2026-01-01T00:05:00Z"
}

6.9 HumanDecisionPayload（人类决策）

{
  "task_id": "task-xxx",
  "decision_id": "dec-xxx",
  "reply_to": "msg-xxx",
  "decided_by": {
    "user_id": "user-123",
    "user_name": "张三",
    "role": "reviewer"
  },
  "decision": {
    "action": "approve",
    "approved_fields": {
      "authorized": true
    },
    "rejection_reason": ""
  },
  "notes": "已确认授权",
  "timestamp": "2026-01-01T00:03:00Z"
}

完整载荷定义： types/types.go

7. 错误码

错误码	说明	HTTP 状态码（如适用）
`message_format_invalid`	消息格式无效	400
`capability_lacking`	能力不足	403
`agent_not_ready`	Agent 未就绪	503
`task_not_found`	任务不存在	404
`task_already_completed`	任务已完成	409
`execution_timeout`	执行超时	504
`execution_failed`	执行失败	500
`permission_denied`	权限不足	403
`invalid_params`	参数无效	400
`rate_limited`	限流	429

完整错误定义： types/errors.go

8. 传输要求

8.1 HTTP 传输

Content-Type: application/json
请求方法：POST
端点路径：由 Agent 自行定义，建议 /synapse/callback
超时：建议 30 秒

8.2 签名验证（可选）

使用 HMAC-SHA256 签名
签名放在 Header：X-Synapse-Signature
或放在消息体：signature 字段

9. 参考实现

本协议的参考实现位于 p2p/ 目录：

文件	说明
p2p/protocol.go	P2P 协议核心实现
types/types.go	数据类型定义
types/errors.go	错误定义
transport/transport.go	HTTP 传输实现

附录 A：能力声明格式

参见灵隙原始协议（Synapse Raw Protocol） - Capability

12 KiB Raw Blame History Unescape Escape