🤝 Agent 协同分类规范 v1.0

# Maian OS Agent 协同分类规范 v1.0

> 定义 Agent 间协同的完整分类体系、协议和最佳实践

1. 协同场景分类

1.1 按组织边界分类

|------|------|---------|------|

1.2 按协作模式分类

|------|------|------|------|

1.3 按同步模式分类

|------|------|------|------|

---

2. Intra-OS 协同（机构内部）

2.1 架构

```

┌─────────────────────────────────┐

│ Maian OS (同一实例) │

│ │

│ ┌──────────┐ │

│ │ Gateway │ (8888) │

│ └────┬─────┘ │

│ │ │

│ ┌────▼──────────┐ │

│ │ Agent Factory │ (8877) │

│ │ │ │

│ │ ┌─────┐ ┌─────┐ ┌─────┐ │

│ │ │main │ │worker│ │tool │ │

│ │ └──┬──┘ └──┬──┘ └──┬──┘ │

│ └────┼───────┼───────┼─────────┘

│ │ │ │ │

│ ┌────▼───────▼───────▼─────────┐ │

│ │ 共享状态（可选） │ │

│ └────────────────────────────┘ │

└─────────────────────────────────┘

```

2.2 委托协议

**端点：** `POST /delegate/{from_agent}/{to_agent}`

**请求：**

{
  "action": "run_code",
  "code": "print(1+1)"
}

**响应（同步）：**

{
  "status": "completed",
  "result": {"output": "2\n", "error": null}
}

**响应（异步）：**

{
  "task_id": "uuid",
  "status": "pending",
  "message": "Task submitted, poll GET /tasks/uuid"
}

2.3 并行协同

**端点：** `POST /delegate/batch`

**请求：**

{
  "tasks": [
    {"to": "maian-worker", "payload": {"action": "run_code", "code": "print(1+1)"}},
    {"to": "maian-worker", "payload": {"action": "run_code", "code": "print(2+2)"}},
    {"to": "maian-main", "payload": {"prompt": "say hi"}}
  ]
}

**响应：**

{
  "task_ids": ["uuid1", "uuid2", "uuid3"],
  "status": "pending",
  "message": "Submitted 3 tasks"
}

2.4 会话上下文

**创建会话：** `POST /sessions` → `{"session_id": "uuid"}`

**带会话委托：** `POST /sessions/{session_id}/delegate/{to_agent}`

会话上下文会注入到 `payload._session_context`，支持多轮协同共享状态。

---

3. Inter-OS 协同（机构间）

3.1 架构

```

┌─────────────────┐ ┌─────────────────┐

│ OS-A │ │ OS-B │

│ │ │ │

│ Agent Factory │ │ Agent Factory │

│ (8877) │ │ (8877) │

│ │ │ │ │ │

│ Gateway (8888) │ ◄──A2A──►│ Gateway (8888)│

│ │ │ │ │ │

│ Soraecho Reg │ │ Soraecho Reg │

└───────┬─────────┘ └───────┬─────────┘

│ │

└──────────┬───────────────┘

│

┌───────▼────────┐

│ Soraecho 网络 │

│ (发现+注册) │

└────────────────┘

```

3.2 跨 OS 调用流程

• **发现：** OS-A 通过 Soraecho 查询 OS-B 的 AgentCard

• **获取端点：** 读取 `endpoints[]` 中的 A2A 地址

3. **签名：** OS-A Agent 用 Ed25519 私钥签名请求

4. **直连调用：** OS-A → OS-B Gateway（不经过 Soraecho 转发）

5. **验证：** OS-B 验证签名（DID Auth）

6. **执行：** OS-B 执行任务

7. **结算：** KOAN 结算（待集成）

3.3 DID 签名验证

**请求头：**

```

X-Maian-Signature: {

"signer_did": "did:key:maian-main-20260726",

"signer_name": "maian-main",

"public_key_b64": "base64...",

"signature_b64": "base64...",

"timestamp": 1785068782,

"payload_hash": "sha256..."

}

```

**验证规则：**

• ✅ 签名有效（Ed25519 验证通过）

• ✅ payload 未被篡改（hash 匹配）

• ⚠️ 时间戳在 ±5 分钟内（防重放，允许时钟偏差）

3.4 跨 OS 发现协议

**发现请求：**

```

GET /api/v1/agentcard/discover?capability=model.chat&limit=20

```

**AgentCard 格式（跨 OS）：**

{
  "did": "did:key:os-b-agent-001",
  "name": "OS-B-Agent",
  "capabilities": ["model.chat", "code.run"],
  "endpoints": ["http://os-b.example.com:8888/a2a/v1/task"],
  "public_key_b64": "base64...",
  "price_per_token": 0.00015,
  "os": "maian-os"
}

---

4. Agent-Human 协同

4.1 场景

|------|------|

4.2 协议（待实现）

```

Agent → Human: 请求审批（task_id + description）

Human → Agent: 审批结果（approve / reject / modify）

```

---

5. 任务状态机

```

┌─────────┐

│ pending │

└────┬────┘

│

▼

┌─────────┐

│ running │

└────┬────┘

│

┌──────┴──────┐

▼ ▼

┌─────────┐ ┌─────────┐

│completed│ │ error │

└─────────┘ └─────────┘

```

**状态查询：** `GET /tasks/{task_id}`

---

6. 安全机制

6.1 信任等级

|------|------|---------|

6.2 防篡改/防重放

• **防篡改：** payload 签名验证（Ed25519）

• **防重放：** timestamp 检查（±5 分钟窗口）

• **防伪造：** DID 公钥验证（从 Soraecho 查询）

---

7. 最佳实践

7.1 何时用同步 vs 异步

|------|---------|

7.2 错误处理

• 同步：返回 HTTP 错误码 + error 字段

• 异步：task.status = "error"，查询 task_id 获取错误

7.3 超时设置

|------|---------|

---

8. 版本历史

|------|------|------|