multi-agent-comm

Zhenbin Huang@ncepuee

Multi-Agent Communication Protocol — 通用多智能体通信框架。用于在 OpenClaw 中编排多个 Agent 之间的结构化通信、任务委派和协同工作。适用场景：(1) 在主 Agent 与子 Agent 之间传递消息 (2) 多个独立 Agent（如 QClaw、学术助手、学生工作助理等）之间的双向通信 (3) 将大任务分解为并行子任务并收集结果 (4) 跨 Agent 共享上下文和记忆。关键词：agent communication, ACP, multi-agent, subagent, session spawn, agent 间通信, 多智能体协同, 任务委派。

Install

openclaw skills install @ncepuee/multi-agent-comm

Multi-Agent Communication

通用多智能体通信框架，基于 OpenClaw 的 session 机制实现 Agent 间结构化通信。

通信架构概览

text

┌──────────────┐
│   Main Agent  │ (QClaw / 主 Agent)
│  (编排中心)    │
└──┬───┬───┬───┘
   │   │   │
   ▼   ▼   ▼
┌────┐┌────┐┌────┐
│Sub1││Sub2││Sub3│  (subagent / acp runtime)
└────┘└────┘└────┘

三种通信模式，按复杂度递增：

模式	方式	适用场景
1. Subagent 委派	`sessions_spawn` (runtime=subagent)	单向任务下发，等结果
2. 持久会话通信	`sessions_spawn` (mode=session) + `sessions_send`	双向持续对话
3. 跨 Agent ACP	`sessions_spawn` (runtime=acp) + agent 配置	独立 Agent 间协议通信

模式 1：Subagent 委派（最常用）

一次性任务委派，子 agent 完成后自动销毁。

markdown

1. 用 `sessions_spawn` 创建子 agent：
   - runtime: "subagent"
   - mode: "run"（一次性）或 "session"（持久）
   - task: 任务描述（越具体越好）
   - model/thinking: 可选覆盖
   - cwd: 可指定工作目录
   - timeoutSeconds: 超时保护

2. 子 agent 完成后自动返回结果到当前会话

3. 如需查看/管理子 agent：
   - subagents(action="list") — 列出运行中的子 agent
   - subagents(action="steer", target=id, message=...) — 向子 agent 发送消息
   - subagents(action="kill", target=id) — 终止子 agent

最佳实践：

Task 描述必须自包含，子 agent 无继承主会话上下文（除非 lightContext=true）
大任务拆为多个并行 subagent 时，用 sessions_yield 等待结果
用 label 给子 agent 命名便于后续管理

模式 2：持久会话通信

需要双向持续对话时使用。

markdown

1. 创建持久会话：
   sessions_spawn(mode="session", task="初始指令", label="my-assistant")

2. 后续通过 session key 通信：
   sessions_send(sessionKey="...", message="后续指令")

3. 查看会话列表和状态：
   sessions_list(kinds=["session"])

适用场景：

需要多轮交互的长期协作 agent
有状态的工作流（如项目管理、持续监控）

模式 3：跨 Agent ACP 通信

用于独立的、有自己 system prompt 和配置的 Agent 之间通信。

详细配置和架构参考：references/acp-setup.md

快速开始

markdown

1. 在 gateway.yaml 的 agents 部分定义新 agent（见 acp-setup.md）

2. 通过 acp runtime 通信：
   sessions_spawn(
     runtime="acp",
     agentId="student-assistant",
     task="任务描述",
     mode="run"  # 或 "session"
   )

3. 恢复已有 ACP 会话：
   sessions_spawn(
     runtime="acp",
     resumeSessionId="session-uuid"
   )

并行编排模式

同时启动多个子 agent 处理不同子任务，然后汇总结果。

markdown

1. 依次 spawn 多个 subagent（每个处理独立子任务）
2. 调用 sessions_yield() 让出当前 turn
3. 子 agent 完成后结果自动返回
4. 汇总各子 agent 结果，生成最终回复

规则：

各子任务必须相互独立（无数据依赖）
每个 subagent 的 task 必须自包含
子 agent 数量建议 2-5 个，避免资源耗尽
每个都设置合理的 timeoutSeconds

共享状态策略

Agent 间不自动共享内存，需要手动传递：

策略	方法	适用场景
文件系统	读写 workspace 中的共享文件	大量数据、持久化
任务描述	在 task/message 中包含必要上下文	小量上下文
文件引用	通过 cwd 或 attachments 传递文件	输入文件处理
环境变量	子 agent 继承父进程环境变量	配置信息

常见模式参考

分治汇总：将大任务拆分为 N 个子任务 → 并行 spawn → yield → 汇总
审查链：Agent A 生成内容 → Agent B 审查/修改 → 返回结果
专家协商：多个领域专家 agent 各自分析 → 汇总决策
监控上报：后台 agent 持续监控 → 有事时通过 sessions_send 上报

跨设备复用

本 skill 无硬编码路径，可直接通过 junction/symlink 链接到任意设备的 skills 目录。Agent 定义在 gateway config 中，跟随各自实例配置。

将此 skill 放入公共 skills 库 ~/.agents/skills/ 后，所有 agent 共享：

powershell

# junction 链接示例
cmd /c mklink /J "~\.claude\skills\multi-agent-comm" "~\.agents\skills\multi-agent-comm"