sanguo_quant_live/zhaoyun-data/research/task-20260401-a2a-multiagent-research/final/REPORT.md

# A2A/多代理方案调研报告："所有A2A消息进入目标agent的main会话"

## 任务背景

**需求：** 在三国量化团队架构中，我们需要一个A2A/多代理方案满足：
> "所有 A2A 消息都进入目标 agent 的 main 会话，避免业务会话爆炸"

具体来说：
- 每个agent有一个固定的**main会话**（如 `agent:zhaoyun-data:main`）
- 所有A2A消息都应该路由到这个固定的main会话
- 避免每次消息都创建新的临时会话，导致会话爆炸
- 保持对话连续性，main会话可以接收排队的任务

## 调研对象

| # | 方案 | 说明 |
|---|------|------|
| 1 | **Network-AI** | 多代理协调层，带共享黑板和并发控制 |
| 2 | **ClawTeam** | 团队协作A2A，专为OpenClaw设计 |
| 3 | **OpenAkita** | 轻量A2A执行框架，成熟开源 |
| 4 | **openclaw-a2a-gateway** | 我们已经修复的方案 |

---

## 逐个方案分析

### 1️⃣ Network-AI（多代理协调层）

**项目地址：** https://github.com/jovanSAPFIONEER/Network-AI

#### 架构概述

Network-AI 是一个**多代理协调层**，核心特点：
- 提供 `LockedBlackboard` 共享状态，原子提交防止竞态条件
- `SwarmOrchestrator` 协调多个代理并行工作
- 内置质量检查、权限控制、预算管理
- 支持14+种AI框架适配器（含OpenClaw）

#### 会话模型分析

| 维度 | 分析 |
|------|------|
| **会话模型** | 每个agent一个固定身份，支持有状态会话 |
| **路由机制** | AdapterRegistry按agentId路由，支持复用现有会话 |
| **会话爆炸风险** | 低 — 协调层不主动新建会话，由下层处理 |
| **适配我们需求** | ⚠️ 可以适配，但较重 |
| **代码复杂度** | 中等，架构清晰 |

**关键发现：**
- Network-AI 本身是协调层，**不负责sessionId的生成和复用**
- 它提供 `OpenClawAdapter`，会调用下层 `callSkill`
- session管理还是由OpenClaw处理
- Network-AI 最大价值在**并发控制和共享状态**，对我们"固定main会话"需求帮助不大

#### 适配结论

Network-AI 不冲突，但它解决的是**并发协调问题**，不是**会话路由问题**。我们的问题在A2A网关层，不是协调层。

---

### 2️⃣ ClawTeam（团队协作 A2A）

**项目地址：** https://github.com/win4r/ClawTeam-OpenClaw

#### 架构概述

ClawTeam 是专为 OpenClaw 设计的**团队多代理协作框架**：
- 支持团队自组织，任务拆分委派
- 文件系统持久化存储会话状态
- 支持多种后端（subprocess/tmux）
- 专为OpenClaw优化

#### 会话模型分析

| 维度 |分析 |
|------|------|
| **会话模型** | ✅ **每个agent持久化保存sessionId，支持复用** |
| **路由机制** | `SessionStore` 按 `(team_name, agent_name)` 保存sessionId |
| **会话爆炸风险** | ✅ 极低 — 同一个agent复用同一个session |
| **适配我们需求** | ✅ **完美适配！** |
| **代码复杂度** | 低，Python实现，简洁清晰 |

**关键代码：`clawteam/spawn/sessions.py`**

```python
class SessionStore:
    """File-based session store.
    Each agent's session is stored at:
    ``{data_dir}/sessions/{team}/{agent}.json``
    """

    def save(agent_name, session_id, ...): ...
    def load(agent_name) -> SessionState | None: ...
```

**设计非常符合我们需求：**
- 每个agent（如赵云）的sessionId**持久化保存**
- 下次发送A2A消息时**直接加载复用**，不会新建
- 完全满足"所有消息进同一个main会话"

#### 适配结论

✅ **ClawTeam 原生设计就符合我们需求！** 它本身就是为"团队固定agent + 持续协作"设计的，session持久化复用是内置功能。

---

### 3️⃣ OpenAkita（轻量 A2A 执行框架）

**项目地址：** https://github.com/openakita/openakita

#### 架构概述

OpenAkita 是一个成熟开源的**AI助手框架**，内置完整的多代理支持：
- `SessionManager` 统一管理所有会话
- 按 `(channel, chat_id, user_id)` 索引会话
- 完整的持久化和生命周期管理
- 支持过期清理

#### 会话模型分析

| 维度 |分析 |
|------|------|
| **会话模型** | ✅ **完全按key复用会话** |
| **路由机制** | `get_session()` 先查缓存，存在就复用，不存在才新建 |
| **会话爆炸风险** | ✅ 极低 — 相同key永远复用同一个会话 |
| **适配我们需求** | ✅ **完美适配！** |
| **代码复杂度** | 中等，TypeScript架构清晰 |

**核心代码 `src/openakita/sessions/manager.py`：**

```python
def get_session(channel, chat_id, user_id):
    session_key = f"{channel}:{chat_id}:{user_id}"
    
    # ✅ 先检查缓存，存在就复用
    if session_key in self._sessions:
        session = self._sessions[session_key]
        session.touch()
        return session
    
    # ❌ 只有不存在才新建
    if create_if_missing:
        session = self._create_session(...)
        self._sessions[session_key] = session
        return session
```

**这个设计完全就是我们需要的！**

- 相同 `(channel, agentId, ...)` → 同一个session
- 不新建，只复用
- 完全避免会话爆炸

#### 适配结论

✅ **OpenAkita 原生完美满足我们需求！** 它的会话管理设计从第一天就是"相同key复用会话"，完全符合我们需求。

---

### 4️⃣ openclaw-a2a-gateway（我们已修复）

**项目地址：** https://github.com/win4r/openclaw-a2a-gateway

#### 架构概述

专为OpenClaw设计的A2A网关，让OpenClaw agents可以互相发消息。

#### 问题背景

**原问题：** 每次对话都会产生一个新session

**根因：** 在 `client.ts/doSendMessage()` 中，发送消息时：
- ✅ 每次正确生成新 `messageId`
- ❌ **没有传递已有的 `contextId`**
- 所以A2A SDK每次都会生成一个新的 `contextId = uuidv4()`
- 导致每次新建session

#### 修复方案

我们已经找到并修复了问题：在 `outboundMessage` 添加一行：

```typescript
const outboundMessage: any = {
  kind: "message",
  messageId: (message.messageId as string) || uuidv4(),
  contextId: (message.contextId as string) || uuidv4(),  // ✅ 添加这行
  role: ...,
  parts: ...,
};
```

**修复效果：**
- 如果调用方提供 `contextId` → 复用它
- 如果没有提供 → 新建
- 完全符合需求

**第三次测试验证：** ✅ 已经通过！消息正确进入赵云main会话，不新建session。

#### 适配结论

✅ **已经修复，完全满足我们需求！** 修复后工作正常，就是我们现在正在使用的方案。

---

## 对比总结表

| 方案 | 会话模型 | 是否支持固定main会话 | 是否避免会话爆炸 | 适配我们需求 | 复杂度 | 推荐度 |
|------|----------|----------------------|------------------|--------------|--------|--------|
| **Network-AI** | 协调层，不管理session | ⚠️ 可以适配，但不直接解决 | ✅ 低风险 | ⚠️ 间接适配 | 中 | ⭐⭐⭐ |
| **ClawTeam** | 每个agent持久化保存sessionId | ✅ 原生支持 | ✅ 完全避免 | ✅ 完美适配 | 低 | ⭐⭐⭐⭐⭐ |
| **OpenAkita** | 按key索引，存在就复用 | ✅ 原生支持 | ✅ 完全避免 | ✅ 完美适配 | 中 | ⭐⭐⭐⭐⭐ |
| **openclaw-a2a-gateway (fixed)** | contextId复用 | ✅ 修复后支持 | ✅ 完全避免 | ✅ 完美适配 | 低 | ⭐⭐⭐⭐⭐ |

---

## 结论与推荐

### 推荐方案优先级

| 优先级 | 方案 | 理由 |
|--------|------|------|
| 1️⃣ | **openclaw-a2a-gateway (已修复)** | 我们已经在使用，修复验证完成，工作正常，最贴合OpenClaw原生架构 |
| 2️⃣ | **ClawTeam** | 专为OpenClaw团队协作设计，session持久化复用原生支持，非常轻量 |
| 3️⃣ | **OpenAkita** | 开源成熟，设计完美，如果需要更完整的框架可以选 |
| 4️⃣ | **Network-AI** | 如果需要并发协调和共享黑板才需要，否则不需要额外层 |

### 当前最佳选择

✅ **推荐继续使用 `openclaw-a2a-gateway` 修复后的版本**

理由：
1. **已经修复并验证** — 第三次测试通过，工作正常
2. **最贴合OpenClaw** — 专为OpenClaw A2A网关设计
3. **轻量无侵入** — 只做A2A路由，不改变现有架构
4. **完全满足需求** — 修复后正确复用contextId，不会新建session，避免会话爆炸
5. **我们已经在生产使用** — 赵云主会话就是例子，工作正常

### 如果需要更完整的团队协作

如果未来需要更完整的**多代理团队协作功能**，推荐：
- **ClawTeam** — 专为OpenClaw设计，原生支持session复用，轻量简洁
- **OpenAkita** — 如果需要全功能AI助手框架，会话管理设计完美

---

## 已完成工作

- [x] Network-AI 文档代码精读 ✓
- [x] ClawTeam 文档代码精读 ✓
- [x] OpenAkita 文档代码精读 ✓
- [x] openclaw-a2a-gateway 回顾 ✓
- [x] 对比分析 ✓
- [x] 推荐结论 ✓

---

## 负责人

**赵云 子龙** 数据护军 🐎⚔️📊

**调研完成时间：** 2026-04-01