灵隙 Synapse # 灵隙(Synapse)— 智能体协作协议栈 > **灵隙之间,万物相连** > 一套开放、安全、可扩展的 AI 智能体协作协议栈 --- ## 什么是灵隙? 灵隙,英文名 **Synapse**,是一套专为 AI 智能体(Agent)设计的**协作协议栈**。 "灵隙"的含义: - **灵** — 智能体的智慧与能力 - **隙** — 智能体之间的空间与连接 灵隙不是某一个 Agent 的实现,而是**定义了 Agent 之间如何对话、如何协作、如何信任**的通用规则。 --- ## 用它来做什么? 灵隙解决的核心问题:**AI 智能体之间如何协同完成复杂任务?** ### 典型场景 | 场景 | 说明 | |------|------| | 🤖 **多 Agent 协作** | 一个 Agent 负责分析,另一个负责生成,第三个负责审核,协同完成一份报告 | | 🔗 **系统集成** | 后端服务通过 REST API 调用 Agent 能力,无需实现完整协议 | | 🧩 **任务分解** | 复杂任务拆分为多个子任务,分配给不同 Agent 并行执行 | | 👥 **群体决策** | 多个 Agent 对同一问题进行投票,达成共识后再执行 | | 🛡️ **人工兜底** | Agent 遇到无法决策的情况时,升级给人类做最终决定 | --- ## 核心协议 灵隙协议栈包含三个子协议和一个公共基础: ### A2A — 点对点通信 两个 Agent 之间直接的任务协作: ```go import "synapse/sdk" client := sdk.NewClient(sdk.Config{ Protocol: sdk.ProtoA2A, AgentEndpoint: myEndpoint, }) taskID, _ := client.SendTaskRequest(ctx, targetAgent, "text_generation", payload) result, _ := client.WaitForTaskA2A(ctx, taskID, 5*time.Minute) ``` ### A2N — 群组协作 一个 Coordinator 协调多个 Worker 协同工作: ```go client := sdk.NewClient(sdk.Config{ Protocol: sdk.ProtoA2N, AgentEndpoint: myEndpoint, }) group, _ := client.CreateGroup(ctx, "分析小组", topology, nil, members) subtasks, _ := client.SubmitGroupTask(ctx, group.GroupID, "analysis", req, "majority") ``` ### P2A — 外部调用 非 Agent 系统通过 REST API 调用 Agent: ```go client := sdk.NewClient(sdk.Config{ Protocol: sdk.ProtoP2A, BaseURL: "http://agent-service:8080", APIKey: "sk-xxx", }) result, _ := client.CreateAndWait(ctx, "text_generation", payload, 5*time.Second) ``` ### RAW — 原始协议(基础) 所有协议共享的基础设施:统一消息信封、Agent 身份标识、HMAC 签名、时间格式。 --- ## 七大组件层 | 组件 | 名称 | 职责 | |------|------|------| | 灵脉 | Meridian | 寻址与路由 | | 灵玺 | Sigil | 身份与凭证 | | 灵鉴 | Speculum | 共识与裁决 | | 灵泊 | Harbor | 异步队列与暂存 | | 灵瞰 | Panorama | 可观测与度量 | | 灵衡 | Libra | 价值结算与激励 | | 灵枢 | Pivot | 紧急制动与治理 | --- ## 特色能力 | 能力 | 说明 | |------|------| | 🔐 **去中心化身份** | 公钥派生 AgentID,无需中心化注册 | | 🧠 **三级 HiL 升级** | Agent 建议 → 人工决策 → 专家仲裁 | | 📦 **内容类型系统** | 文本 / JSON / 代码 / 文件 / 内容包 | | 🔢 **数字分段错误码** | 9 大类 35+ 个错误码,便于国际化 | | 🛤️ **双传输模式** | gRPC + HTTP REST,gRPC-Gateway 桥接 | | ⚡ **熔断与治理** | 熔断器 + 5 级治理级别,保障系统稳定 | --- ## 快速开始 ```bash # 初始化项目 go mod init my-agent # 引入灵隙 SDK go get github.com/synapse/sdk # 编写 Agent ``` ```go package main import ( "context" "synapse/sdk" "synapse/pkg/types" ) func main() { cfg := sdk.Config{ Protocol: sdk.ProtoA2A, AgentEndpoint: types.AgentEndpoint{ AgentID: "agent-001", Endpoint: "http://localhost:8080", }, AuthSecret: "my-secret-key", } client := sdk.NewClient(cfg) // 发送任务 taskID, _ := client.SendTaskRequest( context.Background(), types.AgentEndpoint{AgentID: "agent-002", Endpoint: "http://agent-002:8080"}, "text_generation", map[string]any{"prompt": "写一首诗"}, ) // 等待结果 result, _ := client.WaitForTaskA2A(context.Background(), taskID, 5*time.Minute) println(result.Message) } ``` --- ## 协议文档 | 文档 | 说明 | |------|------| | [docs/v1/index.md](docs/v1/index.md) | 协议索引与概览 | | [docs/v1/raw-protocol.md](docs/v1/raw-protocol.md) | 原始协议(公共基础) | | [docs/v1/a2a-protocol.md](docs/v1/a2a-protocol.md) | A2A 协议(点对点) | | [docs/v1/a2n-protocol.md](docs/v1/a2n-protocol.md) | A2N 协议(群组协作) | | [docs/v1/p2a-protocol.md](docs/v1/p2a-protocol.md) | P2A 协议(外部调用) | | [docs/v1/identity-protocol-draft.md](docs/v1/identity-protocol-draft.md) | 去中心化身份与寻址(草案) | | [docs/v1/components.md](docs/v1/components.md) | 七大组件层规范 | | [docs/v1/error-codes.md](docs/v1/error-codes.md) | 数字分段错误码 | --- ## 许可证 Apache 2.0 --- *灵隙之间,万物相连 — Synapse Protocol Suite v1.0.0*