灵隙(synapse) v1.0.0 版本
This commit is contained in:
519
docs/05-sdk-implementation.md
Normal file
519
docs/05-sdk-implementation.md
Normal file
@@ -0,0 +1,519 @@
|
||||
# SDK 实现说明
|
||||
|
||||
> 版本:1.0.0
|
||||
> 更新日期:2026-06-27
|
||||
> 协议版本:1.0.0
|
||||
> 关联协议:
|
||||
> - [A2A 协议](./02-a2a-protocol.md)
|
||||
> - [A2N 协议](./03-a2n-protocol.md)
|
||||
> - [P2A 协议](./04-p2a-protocol.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. 概述
|
||||
|
||||
SDK 按照灵隙协议族(Synapse Protocol Suite)的三个子协议进行了模块化设计,分为三个子包,命名与协议名保持一致:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ SDK (sdk/) │
|
||||
├──────────────┬───────────────────┬───────────────────────────┤
|
||||
│ sdk/p2a │ sdk/a2a │ sdk/a2n │
|
||||
│ P2A 协议 │ A2A 协议 │ A2N 协议 │
|
||||
│ (外部调用) │ (Agent间通信) │ (群组协作) │
|
||||
│ ✅ 完整实现 │ ✅ 完整实现 │ ✅ 完整实现 │
|
||||
└──────────────┴───────────────────┴───────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. SDK 目录结构
|
||||
|
||||
```
|
||||
sdk/
|
||||
├── doc.go # SDK 包文档(使用说明)
|
||||
├── p2a/
|
||||
│ └── client.go # P2A 协议 - 外部调用客户端
|
||||
├── a2a/
|
||||
│ └── client.go # A2A 协议 - Agent间通信客户端
|
||||
└── a2n/
|
||||
└── client.go # A2N 协议 - 群组协作客户端
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 第一部分:sdk/p2a - P2A 协议
|
||||
|
||||
**协议对应**:[P2A 协议](./04-p2a-protocol.md)
|
||||
**版本**:1.0.0
|
||||
**用途**:非 Agent 调用方(前端、后端服务、第三方应用)通过 REST API 调用 Agent 能力
|
||||
|
||||
### 3.1 实现对应关系
|
||||
|
||||
| P2A 协议功能 | SDK 方法 | 位置 |
|
||||
|-------------|---------|------|
|
||||
| 认证方式 | `setHeaders()` | [sdk/p2a/client.go](../sdk/p2a/client.go) |
|
||||
| 提交任务(JSON) | `SubmitTask()` | [sdk/p2a/client.go](../sdk/p2a/client.go) |
|
||||
| 提交任务(Multipart) | `SubmitTaskWithFiles()` | [sdk/p2a/client.go](../sdk/p2a/client.go) |
|
||||
| 获取任务详情 | `GetTask()` | [sdk/p2a/client.go](../sdk/p2a/client.go) |
|
||||
| 获取任务状态(简化版) | `GetTaskStatus()` | [sdk/p2a/client.go](../sdk/p2a/client.go) |
|
||||
| 获取任务列表 | `ListTasks()` | [sdk/p2a/client.go](../sdk/p2a/client.go) |
|
||||
| 取消任务 | `CancelTask()` | [sdk/p2a/client.go](../sdk/p2a/client.go) |
|
||||
| 能力查询 | `GetCapabilities()` | [sdk/p2a/client.go](../sdk/p2a/client.go) |
|
||||
| 回调验证 | `VerifyCallback()` | [sdk/p2a/client.go](../sdk/p2a/client.go) |
|
||||
| 轮询等待 | `WaitForTask()` | [sdk/p2a/client.go](../sdk/p2a/client.go) |
|
||||
|
||||
### 3.2 核心数据结构
|
||||
|
||||
```go
|
||||
// Client 客户端
|
||||
type Client struct {
|
||||
baseURL string
|
||||
apiKey string
|
||||
httpClient *http.Client
|
||||
}
|
||||
|
||||
// 配置
|
||||
type ClientConfig struct {
|
||||
BaseURL string
|
||||
APIKey string
|
||||
Timeout time.Duration
|
||||
MaxRetries int
|
||||
}
|
||||
|
||||
// 任务请求
|
||||
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
|
||||
Result map[string]any
|
||||
Error *TaskError
|
||||
}
|
||||
|
||||
// 文件上传参数
|
||||
type FileParam struct {
|
||||
FieldName string
|
||||
Filename string
|
||||
Data []byte
|
||||
MimeType string
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 使用示例
|
||||
|
||||
```go
|
||||
import "dp-headless/synapse/sdk/p2a"
|
||||
|
||||
client := p2a.NewClient(p2a.ClientConfig{
|
||||
BaseURL: "https://agent-api.example.com",
|
||||
APIKey: "your-api-key",
|
||||
})
|
||||
|
||||
// 提交任务并等待完成
|
||||
taskInfo, err := client.CreateAndWait(ctx, "text_generation", map[string]any{
|
||||
"prompt": "写一首诗",
|
||||
"style": "古典",
|
||||
}, 5*time.Second)
|
||||
|
||||
// 使用回调模式
|
||||
resp, err := client.CreateWithCallback(ctx, "image_generation", payload,
|
||||
"https://your-domain.com/callback",
|
||||
"callback-token",
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 第二部分:sdk/a2a - A2A 协议
|
||||
|
||||
**协议对应**:[A2A 协议](./02-a2a-protocol.md)
|
||||
**版本**:1.0.0
|
||||
**用途**:Agent 之间的点对点通信,包含消息发送、签名验证、回调处理
|
||||
|
||||
### 4.1 实现对应关系
|
||||
|
||||
| A2A 协议功能 | SDK 方法 | 位置 |
|
||||
|------------|---------|------|
|
||||
| 发送任务请求 | `SendTaskRequest()` | [sdk/a2a/client.go](../sdk/a2a/client.go) |
|
||||
| 发送任务取消 | `SendTaskCancel()` | [sdk/a2a/client.go](../sdk/a2a/client.go) |
|
||||
| 发送人类决策 | `SendHumanDecision()` | [sdk/a2a/client.go](../sdk/a2a/client.go) |
|
||||
| 查询能力 | `SendCapabilityQuery()` | [sdk/a2a/client.go](../sdk/a2a/client.go) |
|
||||
| 消息签名 | `signMessage()` | [sdk/a2a/client.go](../sdk/a2a/client.go) |
|
||||
| 签名验证 | `verifySignature()` | [sdk/a2a/client.go](../sdk/a2a/client.go) |
|
||||
| 任务状态管理 | `GetTaskState()`, `ListTasks()` | [sdk/a2a/client.go](../sdk/a2a/client.go) |
|
||||
| 等待任务完成 | `WaitForTask()` | [sdk/a2a/client.go](../sdk/a2a/client.go) |
|
||||
| 回调服务 | `startCallbackServer()` | [sdk/a2a/client.go](../sdk/a2a/client.go) |
|
||||
|
||||
### 4.2 核心数据结构
|
||||
|
||||
```go
|
||||
// Client A2A客户端
|
||||
type Client struct {
|
||||
agentEndpoint types.AgentEndpoint
|
||||
authSecret string
|
||||
callbackHandler MessageCallbackHandler
|
||||
tasks map[string]*A2ATaskState
|
||||
}
|
||||
|
||||
// 配置
|
||||
type ClientConfig struct {
|
||||
AgentEndpoint types.AgentEndpoint
|
||||
AuthSecret string
|
||||
CallbackPort int
|
||||
Timeout time.Duration
|
||||
MaxRetries int
|
||||
}
|
||||
|
||||
// 消息回调处理器接口
|
||||
type MessageCallbackHandler interface {
|
||||
HandleTaskRequest(ctx context.Context, msg *types.UnifiedSynapseMessage) (*types.UnifiedSynapseMessage, error)
|
||||
HandleTaskStatusUpdate(ctx context.Context, msg *types.UnifiedSynapseMessage) error
|
||||
HandleTaskComplete(ctx context.Context, msg *types.UnifiedSynapseMessage) error
|
||||
HandleTaskFailed(ctx context.Context, msg *types.UnifiedSynapseMessage) error
|
||||
HandleNeedHuman(ctx context.Context, msg *types.UnifiedSynapseMessage) error
|
||||
}
|
||||
|
||||
// 任务状态
|
||||
type A2ATaskState struct {
|
||||
TaskID string
|
||||
Status types.P2PTaskStatus
|
||||
Progress int
|
||||
Message string
|
||||
Result any
|
||||
Error *types.SynapseError
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 使用示例
|
||||
|
||||
```go
|
||||
import "dp-headless/synapse/sdk/a2a"
|
||||
|
||||
a2aClient, err := a2a.NewClient(&a2a.ClientConfig{
|
||||
AgentEndpoint: types.AgentEndpoint{
|
||||
AgentID: "my-agent",
|
||||
AgentName: "我的Agent",
|
||||
SystemID: "my-system",
|
||||
Endpoint: "http://localhost:8080/synapse/callback",
|
||||
},
|
||||
AuthSecret: "my-hmac-secret",
|
||||
CallbackPort: 8080,
|
||||
})
|
||||
|
||||
// 设置消息处理器
|
||||
a2aClient.SetMessageHandler(&myHandler{})
|
||||
|
||||
// 发送任务请求给其他Agent
|
||||
taskID, err := a2aClient.SendTaskRequest(ctx, targetAgent, "video_generation", map[string]any{
|
||||
"prompt": "生成一段视频",
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 第三部分:sdk/a2n - A2N 协议
|
||||
|
||||
**协议对应**:[A2N 协议](./03-a2n-protocol.md)
|
||||
**版本**:1.0.0
|
||||
**用途**:多 Agent 群组协作,包含群组管理、任务拆分合并、投票、升级
|
||||
|
||||
### 5.1 实现对应关系
|
||||
|
||||
| A2N 协议功能 | SDK 方法 | 位置 |
|
||||
|------------|---------|------|
|
||||
| 创建群组 | `CreateGroup()` | [sdk/a2n/client.go](../sdk/a2n/client.go) |
|
||||
| 加入群组 | `JoinGroup()` | [sdk/a2n/client.go](../sdk/a2n/client.go) |
|
||||
| 离开群组 | `LeaveGroup()` | [sdk/a2n/client.go](../sdk/a2n/client.go) |
|
||||
| 解散群组 | `DisbandGroup()` | [sdk/a2n/client.go](../sdk/a2n/client.go) |
|
||||
| 提交群组任务 | `SubmitGroupTask()` | [sdk/a2n/client.go](../sdk/a2n/client.go) |
|
||||
| 发送子任务结果 | `SendSubtaskResult()` | [sdk/a2n/client.go](../sdk/a2n/client.go) |
|
||||
| 发起投票 | `InitiateVote()` | [sdk/a2n/client.go](../sdk/a2n/client.go) |
|
||||
| 提交投票 | `SubmitVote()` | [sdk/a2n/client.go](../sdk/a2n/client.go) |
|
||||
| 广播消息 | `Broadcast()` | [sdk/a2n/client.go](../sdk/a2n/client.go) |
|
||||
| 升级到人类 | `EscalateToHuman()` | [sdk/a2n/client.go](../sdk/a2n/client.go) |
|
||||
|
||||
### 5.2 核心数据结构
|
||||
|
||||
```go
|
||||
// Client A2N客户端
|
||||
type Client struct {
|
||||
a2aClient *a2a.Client
|
||||
groups map[string]*GroupState
|
||||
eventHandler GroupEventHandler
|
||||
}
|
||||
|
||||
// 配置
|
||||
type ClientConfig struct {
|
||||
A2AClient *a2a.Client
|
||||
EventHandler GroupEventHandler
|
||||
}
|
||||
|
||||
// 群组状态
|
||||
type GroupState struct {
|
||||
GroupID string
|
||||
Name string
|
||||
Topology types.GroupTopology
|
||||
Status types.GroupStatus
|
||||
Members []types.GroupMember
|
||||
Role string // "coordinator" | "worker"
|
||||
}
|
||||
|
||||
// 群组事件处理器接口
|
||||
type GroupEventHandler interface {
|
||||
OnGroupCreated(ctx context.Context, groupID string) error
|
||||
OnGroupDisbanded(ctx context.Context, groupID string) error
|
||||
OnMemberJoined(ctx context.Context, groupID string, member types.GroupMember) error
|
||||
OnMemberLeft(ctx context.Context, groupID string, agentID string) error
|
||||
OnTaskSplit(ctx context.Context, groupID string, originalTaskID string, subtasks []types.Subtask) error
|
||||
OnSubtaskProgress(ctx context.Context, groupID string, subtaskID string, progress int) error
|
||||
OnTaskMerged(ctx context.Context, groupID string, originalTaskID string, result any) error
|
||||
OnVoteInitiated(ctx context.Context, groupID string, vote types.GroupVotePayload) error
|
||||
OnVoteResult(ctx context.Context, groupID string, voteID string, option string, passed bool) error
|
||||
OnEscalation(ctx context.Context, groupID string, escalationID string, level int) error
|
||||
OnBroadcast(ctx context.Context, groupID string, sender types.AgentEndpoint, message []byte) error
|
||||
}
|
||||
```
|
||||
|
||||
### 5.3 使用示例
|
||||
|
||||
```go
|
||||
import (
|
||||
"dp-headless/synapse/sdk/a2n"
|
||||
"dp-headless/synapse/sdk/a2a"
|
||||
)
|
||||
|
||||
// 创建A2A客户端
|
||||
a2aClient, _ := a2a.NewClient(&a2a.ClientConfig{
|
||||
AgentEndpoint: myEndpoint,
|
||||
})
|
||||
|
||||
// 创建A2N客户端
|
||||
a2nClient, err := a2n.NewClient(&a2n.ClientConfig{
|
||||
A2AClient: a2aClient,
|
||||
EventHandler: &myGroupHandler{},
|
||||
})
|
||||
|
||||
// 创建群组
|
||||
group, err := a2nClient.CreateGroup(ctx, "视频制作组", types.GroupTopologyStar, nil, members)
|
||||
|
||||
// 作为Coordinator,提交任务
|
||||
subtasks, err := a2nClient.SubmitGroupTask(ctx, group.GroupID, "video_generation",
|
||||
map[string]any{"script": "..."},
|
||||
types.MergeAllSuccess,
|
||||
)
|
||||
|
||||
// 发起投票
|
||||
voteID, err := a2nClient.InitiateVote(ctx, group.GroupID,
|
||||
"选择哪个方案?",
|
||||
[]string{"方案A", "方案B"},
|
||||
voterIDs,
|
||||
0.5,
|
||||
5*time.Minute,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. SDK 架构总览
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ SDK (dp-headless/synapse/sdk) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ doc.go │
|
||||
│ ├── 包文档和使用说明 │
|
||||
│ └── 指向各子包的链接 │
|
||||
├────────────────┬────────────────┬─────────────────────────┤
|
||||
│ sdk/p2a │ sdk/a2a │ sdk/a2n │
|
||||
│ │ │ │
|
||||
│ P2A协议 │ 灵隙协议 │ A2N协议 │
|
||||
│ │ │ │
|
||||
│ ├── Client │ ├── Client │ ├── Client │
|
||||
│ ├── 配置 │ ├── 配置 │ ├── 配置 │
|
||||
│ ├── 任务操作 │ ├── 消息发送 │ ├── 群组管理 │
|
||||
│ ├── 能力查询 │ ├── 任务状态 │ ├── 任务协作 │
|
||||
│ └── 回调验证 │ ├── 回调服务 │ ├── 投票 │
|
||||
│ │ └── 签名 │ └── 升级 │
|
||||
└────────────────┴────────────────┴─────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 快速开始
|
||||
|
||||
### 7.1 P2A 调用(外部调用者)
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
"dp-headless/synapse/sdk/p2a"
|
||||
)
|
||||
|
||||
func main() {
|
||||
client := p2a.NewClient(p2a.ClientConfig{
|
||||
BaseURL: "https://agent.example.com",
|
||||
APIKey: "your-api-key",
|
||||
})
|
||||
|
||||
ctx := context.Background()
|
||||
|
||||
// 方式1: 轮询等待
|
||||
result, err := client.CreateAndWait(ctx, "text_generation", map[string]any{
|
||||
"prompt": "写一首诗",
|
||||
}, 5*time.Second)
|
||||
if err != nil {
|
||||
fmt.Println("Error:", err)
|
||||
}
|
||||
fmt.Printf("Result: %v\n", result.Result)
|
||||
|
||||
// 方式2: 回调模式
|
||||
resp, err := client.CreateWithCallback(ctx, "image_generation",
|
||||
map[string]any{"prompt": "一只猫"},
|
||||
"https://your-domain.com/callback",
|
||||
"token",
|
||||
)
|
||||
fmt.Printf("Task ID: %s\n", resp.TaskID)
|
||||
}
|
||||
```
|
||||
|
||||
### 7.2 灵隙 通信(Agent 间)
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
"dp-headless/synapse/sdk/a2a"
|
||||
"dp-headless/synapse/types"
|
||||
)
|
||||
|
||||
func main() {
|
||||
client, _ := a2a.NewClient(&a2a.ClientConfig{
|
||||
AgentEndpoint: types.AgentEndpoint{
|
||||
AgentID: "agent-001",
|
||||
AgentName: "Agent 001",
|
||||
SystemID: "my-system",
|
||||
Endpoint: "http://localhost:8080/synapse/callback",
|
||||
},
|
||||
AuthSecret: "secret-key",
|
||||
CallbackPort: 8080,
|
||||
})
|
||||
|
||||
ctx := context.Background()
|
||||
target := types.AgentEndpoint{
|
||||
AgentID: "agent-002",
|
||||
Endpoint: "http://agent-002:8080/synapse/callback",
|
||||
}
|
||||
|
||||
// 发送任务请求
|
||||
taskID, err := client.SendTaskRequest(ctx, target, "data_analysis", map[string]any{
|
||||
"dataset": "sales.csv",
|
||||
})
|
||||
fmt.Printf("Task ID: %s\n", taskID)
|
||||
|
||||
// 等待完成
|
||||
state, err := client.WaitForTask(ctx, taskID, 5*time.Minute)
|
||||
fmt.Printf("Status: %s\n", state.Status)
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 A2N 群组协作
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
"dp-headless/synapse/sdk/a2n"
|
||||
"dp-headless/synapse/sdk/a2a"
|
||||
"dp-headless/synapse/types"
|
||||
)
|
||||
|
||||
func main() {
|
||||
a2aClient, _ := a2a.NewClient(&a2a.ClientConfig{
|
||||
AgentEndpoint: myEndpoint,
|
||||
})
|
||||
|
||||
a2nClient, _ := a2n.NewClient(&a2n.ClientConfig{
|
||||
A2AClient: a2aClient,
|
||||
})
|
||||
|
||||
ctx := context.Background()
|
||||
|
||||
// 创建群组
|
||||
group, _ := a2nClient.CreateGroup(ctx, "协作组", types.GroupTopologyStar, nil, []types.AgentEndpoint{
|
||||
{AgentID: "member-1", Endpoint: "http://member-1:8080"},
|
||||
{AgentID: "member-2", Endpoint: "http://member-2:8080"},
|
||||
})
|
||||
|
||||
fmt.Printf("Group ID: %s\n", group.GroupID)
|
||||
|
||||
// 提交任务
|
||||
subtasks, _ := a2nClient.SubmitGroupTask(ctx, group.GroupID, "video_generation",
|
||||
map[string]any{"script": "..."},
|
||||
types.MergeAllSuccess,
|
||||
)
|
||||
|
||||
fmt.Printf("Split into %d subtasks\n", len(subtasks))
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 协议与包名对应关系
|
||||
|
||||
| 协议名称 | 协议文档 | SDK 包名 | 包路径 |
|
||||
|---------|---------|---------|--------|
|
||||
| 灵隙原始协议(Synapse Raw Protocol) | [01-a2a-raw-protocol.md](./01-a2a-raw-protocol.md) | - | 纲领性文档 |
|
||||
| A2A 协议 | [02-a2a-protocol.md](./02-a2a-protocol.md) | `a2a` | `sdk/a2a/` |
|
||||
| A2N 协议 | [03-a2n-protocol.md](./03-a2n-protocol.md) | `a2n` | `sdk/a2n/` |
|
||||
| P2A 协议 | [04-p2a-protocol.md](./04-p2a-protocol.md) | `p2a` | `sdk/p2a/` |
|
||||
|
||||
**所有协议版本:1.0.0**
|
||||
|
||||
---
|
||||
|
||||
## 9. 扩展建议
|
||||
|
||||
| 优先级 | 扩展项 | 说明 |
|
||||
|-------|-------|------|
|
||||
| 高 | gRPC 传输 | 添加 gRPC 协议支持 |
|
||||
| 高 | WebSocket | 添加 WebSocket 流式传输 |
|
||||
| 中 | 批量操作 | 批量任务提交、批量查询 |
|
||||
| 中 | 指标监控 | 内置指标收集 |
|
||||
| 低 | 多语言 SDK | Python、JavaScript 等 |
|
||||
|
||||
---
|
||||
|
||||
## 附录:相关文件索引
|
||||
|
||||
| 文件路径 | 说明 |
|
||||
|---------|------|
|
||||
| [sdk/doc.go](../sdk/doc.go) | SDK 包文档 |
|
||||
| [sdk/p2a/client.go](../sdk/p2a/client.go) | P2A 客户端实现 |
|
||||
| [sdk/a2a/client.go](../sdk/a2a/client.go) | A2A 客户端实现 |
|
||||
| [sdk/a2n/client.go](../sdk/a2n/client.go) | A2N 客户端实现 |
|
||||
| [externalapi/handler.go](../externalapi/handler.go) | P2A 协议服务端实现 |
|
||||
| [p2p/protocol.go](../p2p/protocol.go) | A2A 协议核心实现 |
|
||||
| [group/protocol.go](../group/protocol.go) | A2N 协议核心实现 |
|
||||
| [types/types.go](../types/types.go) | 公共类型定义 |
|
||||
| [transport/transport.go](../transport/transport.go) | HTTP 传输层实现 |
|
||||
Reference in New Issue
Block a user