⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v4.1

agent-bridge

canxia-hub@canxia-hub⭐ 0 stars· last commit 7mo ago· 0 open issues

OpenClaw 多 Agent 间正式通信技能。提供通信纪律指导、身份识别协议、对话控制规范。技能只提供指导,Agent 使用 OpenClaw 内置工具执行通信。

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 0 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Agent Bridge

OpenClaw 多 Agent 正式通信技能。

agent-bridge 用于在 独立 Agent 之间建立正式、双向、可追溯的通信链路。它不是 sub-agent 的临时任务分身方案,而是面向长期协作、任务交接、状态同步与多轮会话管理的通信层。

适用场景

  • 主 Agent 与专职 Agent 的正式协作
  • 多 Agent 团队中的任务交接与状态汇报
  • 跨会话的长期对话线程管理
  • 需要保留通信历史、上下文与可追溯性的场景

核心特性

  • 基于 OpenClaw 原生 sessions_* 工具集
  • 支持四种通信类型:NOTIFY / QUERY / DELEGATE / COLLABORATE
  • 支持多轮对话与线程管理(最多 5 轮)
  • 完整错误处理与熔断保护
  • 消息状态追踪(pending / delivered / replied / timeout)
  • 静默规则:避免死循环的关键机制
  • 会话生命周期管理:处理 done 状态的超时问题
  • 适用于双 Agent 也适用于未来 3+ Agent 协作扩展

项目结构

agent-bridge/
├── SKILL.md
├── README.md
├── DESIGN.md
├── LICENSE
├── docs/
│   ├── QUICKSTART.md
│   └── AGENT-INSTALL.md
├── examples/
│   ├── basic_send.py
│   └── multi_turn_conv.py
└── scripts/
    ├── agent_bridge.py
    ├── bridge_api.py
    ├── bridge_core.py
    ├── conversation_manager.py
    └── message_tracker.py

快速开始

1. 前置配置

确保 openclaw.json 中启用了 Agent 间通信:

{
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["main", "su-er"]
    },
    "sessions": {
      "visibility": "all"
    }
  }
}

2. 基础调用

from bridge_api import AgentBridge

bridge = AgentBridge(source_agent="main")
reply = await bridge.ask("su-er", "当前状态如何?")
print(reply)

3. 多轮对话

thread = await bridge.start_conversation("su-er", max_turns=5)
await bridge.continue_conversation(thread.thread_id, "你好,素儿")
await bridge.continue_conversation(thread.thread_id, "请汇报当前任务")
await bridge.end_conversation(thread.thread_id)

文档

注意事项

1. 这不是 Sub-agent 替代品

如果你的需求是“临时委派一个分身做脏活累活”,请使用 sessions_spawn。
如果你的需求是“让两个独立 Agent 正式对话并留痕”,才使用 agent-bridge。

2. 必须启用白名单

没有加入 tools.agentToAgent.allow 的 Agent,无法进行通信。

3. 会话可见性需要放开

建议配置:

{
  "tools": {
    "sessions": {
      "visibility": "all"
    }
  }
}

否则你可能无法正常查看跨 Agent 会话历史。

4. 注意结束 ping-pong

多轮对话结束时,建议显式发送 REPLY_SKIP 或主动关闭线程,避免不必要的往返回复。

5. 这是 OpenClaw 技能,不是通用 Python 库

scripts/ 中的代码虽然是 Python,但它的核心价值依赖 OpenClaw 的 sessions_send / sessions_history / sessions_list 环境。脱离 OpenClaw,功能会退化为说明模式或无法真正通信。

6. 静默规则(v4.1 新增)

重要:不发送消息和发送消息一样重要。

以下场景应保持静默,不回复:

  • 任务完成后收到确认消息
  • 收到重复 MSG_ID
  • 收到纯 ACK/COMPLETED 消息
  • 用户明确要求静默时

避免回复 → 对方回复 → 死循环。

7. 会话生命周期(v4.1 新增)

Agent 完成任务后会话自动进入 "done" 状态,此时 sessions_send 会超时。解决方案:

  • 发送前检查会话状态
  • 发现超时后重新激活会话
  • 简化流程:由 main 直接传递已知结果

版本

v4.1.0 (2026-03-31)

  • 🆕 新增「静默规则」章节,避免死循环
  • 🆕 新增会话生命周期管理说明
  • ✨ 优化群发消息指导
  • ✨ 优化 DELEGATE 静默等待机制
  • 📝 更新消息头格式规范

v4.0.0

  • 重构通信纪律为 4 种类型:NOTIFY / QUERY / DELEGATE / COLLABORATE
  • 新增 AGENTS.md 精简模板
  • 新增群发消息规则

v3.2.0

  • 新增任务分类机制
  • 优化重试流程(倍数退避)

v2.0.0

  • 新增 bridge_core.py
  • 新增 bridge_api.py
  • 新增 message_tracker.py
  • 重构 conversation_manager.py
  • 增强错误处理、重试机制、消息状态管理
  • 补充示例与文档

License

MIT-0. See LICENSE.

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md13 KBupstream ↗
    ---
    name: agent-bridge
    description: "OpenClaw 多 Agent 间正式通信技能。提供通信纪律指导、身份识别协议、对话控制规范。技能只提供指导,Agent 使用 OpenClaw 内置工具执行通信。"
    version: "4.1"
    ---
    
    # Agent Bridge - 多 Agent 间通信技能
    
    > 💡 **技能版本**: v4.1  
    > 📅 **更新时间**: 2026-03-31  
    > 👤 **维护者**: 小千 👡  
    > 🎯 **核心原则**: 技能只提供指导,Agent 使用 OpenClaw 内置工具执行通信
    
    ---
    
    ## 🔒 前置规则:AGENTS.md 必备通信规范
    
    **重要**:本技能要求在 AGENTS.md 中写入以下精简通信规范,确保 Agent 每次启动时自动加载核心规则。
    
    ### 标准模板(必须写入 AGENTS.md)
    
    将以下精简内容添加到 AGENTS.md:
    
    ```xml
    <agent_communication_discipline>
      <purpose>Agent 间通信核心纪律 — 详细规则见 agent-bridge 技能</purpose>
      
      <basic_rules>
        <rule>用户消息用 message 工具回复,Agent 消息用 sessions_send 回复,绝不混淆。</rule>
        <rule>sessionKey 格式:agent:&lt;id&gt;:main,禁止用 label 寻址。</rule>
        <rule>多轮对话最多 5 轮,发起方负责发送 [END] 结束。</rule>
        <rule>每次发送/回复消息只能执行一次 sessions_send,禁止重复发送。</rule>
        <rule>收到消息后,只调用一次 sessions_send 回复,禁止重试。</rule>
        <rule>禁止在 thinking 中"调试"通信问题后重复发送。</rule>
      </basic_rules>
      
      <communication_flow>
        发送消息时携带消息头:
        [MSG_ID:msg:&lt;sender&gt;:&lt;timestamp&gt;:&lt;random&gt;]
        [FROM:AGENT:&lt;sender&gt;]
        [TO:AGENT:&lt;receiver&gt;]
        [TASK_TYPE:NOTIFY|QUERY|DELEGATE|COLLABORATE]
        
        收到消息时:验证 FROM 与来源一致 → 检查 MSG_ID 是否重复 → 处理消息 → 发送一次回复(只一次)。
      </communication_flow>
      
      <silent_wait>
        DELEGATE 类型:timeoutSeconds=0,发送后静默等待。
        接收方:处理完成后必须主动回复,携带 [TASK_STATUS] 和 [TASK_RESULT]。
        发送方:维护 pending_tasks 列表,超时未收到回复则通知用户。
      </silent_wait>
      
      <timeout_reference>
        NOTIFY=0(即发即弃)
        QUERY=30(等待回复)
        DELEGATE=0(静默等待,对方主动回复)
        COLLABORATE=60(多轮对话)
      </timeout_reference>
    </agent_communication_discipline>
    ```
    
    **设计原则**:AGENTS.md 只包含核心纪律骨架,详细规则(熔断保护、幂等性、错误处理等)由本技能提供指导。
    
    ### 实施步骤
    
    1. **检查 AGENTS.md**:确认是否存在 `<agent_communication_discipline>` 章节
    2. **添加或更新**:将上述模板写入 AGENTS.md
    3. **位置建议**:放在 `<agent_communication_guide>` 章节之后
    4. **所有 Agent**:确保每个独立 Agent 的 AGENTS.md 都包含此规范
    
    ---
    
    ## 📢 群发消息指导
    
    ### 群发场景
    
    当需要向多个 Agent 同时发送消息时(如广播通知、任务分配),必须遵循以下规则:
    
    ### 规则 1:禁止并行发送
    
    **问题**:并行向多个 Agent 发送消息会导致响应超时,因为每个 Agent 处理时间不同。
    
    **错误做法**:
    ```python
    # ❌ 错误:并行发送,会导致超时
    for agent in ["su-er", "tuan", "intel-analyst"]:
        sessions_send({
            "sessionKey": f"agent:{agent}:main",
            "message": "...",
            "timeoutSeconds": 30
        })  # 累计等待时间可能超过 90 秒
    ```
    
    **正确做法**:串行发送,使用 NOTIFY 类型(timeoutSeconds=0)
    ```python
    # ✅ 正确:串行发送,即发即弃
    for agent in ["su-er", "tuan", "intel-analyst"]:
        sessions_send({
            "sessionKey": f"agent:{agent}:main",
            "message": "[TASK_TYPE:NOTIFY]\n...",
            "timeoutSeconds": 0  # 即发即弃,不等待回复
        })
    ```
    
    ### 规则 2:群发使用 NOTIFY 类型
    
    群发消息应使用 `TASK_TYPE:NOTIFY`,`timeoutSeconds=0`:
    
    ```
    特点:
    - 即发即弃,不等待回复
    - 发送后立即继续处理其他任务
    - 避免累积超时
    
    接收方行为:
    - 收到后处理消息
    - 如需回复,主动使用 sessions_send 回复
    - 回复时携带 [TASK_TYPE:NOTIFY] 和 [TASK_STATUS]
    ```
    
    ### 规则 3:静默等待机制
    
    **场景**:发送 DELEGATE 类型任务后,需要等待结果。
    
    **发送方规则**:
    ```python
    # 发送 DELEGATE 任务
    sessions_send({
        "sessionKey": "agent:tuan:main",
        "message": "[TASK_TYPE:DELEGATE]\n...",
        "timeoutSeconds": 0  # 静默等待,不在此处阻塞
    })
    
    # 发送后:
    # 1. 记录到 pending_tasks 列表
    # 2. 继续处理其他事务
    # 3. 不轮询、不重复发送
    # 4. 等待接收方主动回复
    ```
    
    **接收方规则**:
    ```python
    # 处理完成后主动回复
    sessions_send({
        "sessionKey": "agent:main:main",
        "message": """[TASK_TYPE:NOTIFY]
    [TASK_ID:原任务ID]
    [TASK_STATUS:COMPLETED]
    [TASK_RESULT:SUCCESS]
    ---
    任务已完成,结果:...""",
        "timeoutSeconds": 0
    })
    ```
    
    ### 规则 4:禁止的行为
    
    | 禁止行为 | 原因 | 正确做法 |
    |---|---|---|
    | 群发时使用 timeoutSeconds > 0 | 累积超时 | 使用 timeoutSeconds=0 |
    | 发送后立即轮询检查 | 浪费资源 | 静默等待对方主动回复 |
    | 超时后立即重发 | 可能造成重复处理 | 记录 pending,等待对方回复 |
    | 同一任务多次发送 | 消息堆积 | 每个任务只发送一次 |
    | 并行向多 Agent 发送 | 响应不可控 | 串行发送或使用 NOTIFY |
    
    ### 规则 5:超时处理
    
    **如果发送方超时未收到回复**:
    
    1. **检查 pending_tasks**:确认任务是否已记录
    2. **不要立即重发**:接收方可能仍在处理
    3. **等待合理时间**:根据任务复杂度设置等待时间
    4. **主动询问**:超过预期时间后,发送 QUERY 类型询问状态
    5. **上报用户**:如果多次询问无响应,通知用户
    
    ```python
    # 超时处理流程
    def handle_timeout(task_id, target_agent):
        # 1. 检查是否在 pending_tasks 中
        if task_id not in pending_tasks:
            return  # 任务可能已完成,忽略
        
        # 2. 不要重发,而是询问状态
        sessions_send({
            "sessionKey": f"agent:{target_agent}:main",
            "message": f"[TASK_TYPE:QUERY]\n询问任务 {task_id} 的处理状态",
            "timeoutSeconds": 30
        })
        
        # 3. 如果再次超时,通知用户
        # ...
    ```
    
    ### 群发消息模板
    
    ```
    [MSG_ID:msg:main:20260330T210000:bcast001]
    [FROM:AGENT:main]
    [TO:AGENT:{receiver}]
    [TASK_TYPE:NOTIFY]
    [TIMESTAMP:2026-03-30T21:00:00+08:00]
    [BROADCAST:true]
    ---
    【群发通知】
    
    通知内容...
    
    (此消息为群发,无需回复确认)
    ```
    
    ---
    
    ## ⚠️ 核心原则
    
    **本技能不包含任何实际调用工具的代码。**
    
    本技能提供:
    - ✅ 通信纪律规范
    - ✅ 身份识别协议
    - ✅ 对话控制规则
    - ✅ 消息格式模板
    - ✅ 错误处理指导
    
    Agent 应使用 OpenClaw 内置工具执行通信:
    - `sessions_send` - 发送消息
    - `sessions_history` - 查询历史
    - `sessions_list` - 列出会话
    
    ---
    
    ## 🔇 静默规则:什么时候不要发送消息
    
    > ⚠️ **重要**:不发送消息和发送消息一样重要。错误的回复可能造成死循环。
    
    ### 规则 1:任务完成后保持静默
    
    **场景**:任务已明确完成,收到确认消息后。
    
    **行为**:保持静默,不再回复。
    
    ```
    ❌ 错误做法:
    收到:[TASK_STATUS:COMPLETED]
    回复:收到完成确认!  ← 不必要
    
    ✅ 正确做法:
    收到:[TASK_STATUS:COMPLETED]
    行为:静默,不回复
    ```
    
    **原因**:
    - 任务已闭环,回复会开启新循环
    - 对方收到确认后也会回复 → 死循环
    
    ### 规则 2:收到重复消息保持静默
    
    **场景**:收到的消息 MSG_ID 已在缓存中(5 分钟内处理过)。
    
    **行为**:静默拒绝,不回复。
    
    ```
    ❌ 错误做法:
    收到重复 MSG_ID → 回复"已处理过"  ← 会触发对方回复
    
    ✅ 正确做法:
    收到重复 MSG_ID → 静默跳过,不回复
    ```
    
    **判断方法**:
    1. 检查 MSG_ID 是否在 `processed_msg_ids` 缓存中
    2. 检查消息时间戳是否在合理窗口内
    3. 检查是否是队列中的历史消息(已处理过的任务)
    
    ### 规则 3:确认类消息不回复
    
    **场景**:收到纯粹的确认消息(ACK、已完成通知等)。
    
    **行为**:静默,除非需要继续推进任务。
    
    ```
    需要静默的消息类型:
    - [TASK_STATUS:COMPLETED] + 无后续动作
    - [TASK_STATUS:ACK_RECEIVED]
    - [TASK_RESULT:已交付]
    - 纯通知类消息(无问题、无请求)
    ```
    
    ```
    ❌ 错误做法:
    收到:任务已完成!
    回复:好的收到!  ← 不必要
    
    ✅ 正确做法:
    收到:任务已完成!
    行为:静默,记录到日志
    ```
    
    ### 规则 4:检测死循环并熔断
    
    **场景**:短时间内收到同一 Agent 多条相似消息。
    
    **行为**:停止回复,上报用户。
    
    ```
    死循环信号:
    - 同一 MSG_ID 重复出现
    - 同一任务多次确认
    - 短时间内收到 3+ 条相似内容消息
    
    熔断行为:
    1. 停止回复
    2. 记录异常到日志
    3. 必要时通知用户
    ```
    
    ### 规则 5:用户明确要求静默
    
    **场景**:用户明确指示"不要回复其他消息"。
    
    **行为**:严格遵守,忽略所有 Agent 消息。
    
    ```
    用户指令示例:
    - "不要再回复了"
    - "忽略其他消息"
    - "完成后不要回复"
    
    执行:
    - 不回复任何 Agent 消息
    - 继续处理用户的新指令
    ```
    
    ### 静默规则速查表
    
    | 场景 | 行为 | 原因 |
    |------|------|------|
    | 任务已完成确认 | 🔇 静默 | 避免开启新循环 |
    | 重复 MSG_ID | 🔇 静默 | 已处理,回复会死循环 |
    | 纯 ACK 消息 | 🔇 静默 | 无需继续对话 |
    | 收到 [END] 标记 | 🔇 静默 | 对话已结束 |
    | 历史队列消息 | 🔇 静默 | 任务已归档 |
    | 用户要求静默 | 🔇 静默 | 用户指令优先 |
    | 需要推进任务 | ✅ 回复 | 继续工作流 |
    | 收到新任务 | ✅ 回复 | 开始处理 |
    | 收到问题 | ✅ 回复 | 提供答案 |
    
    ### 实现示例
    
    ```python
    # 消息处理逻辑
    def handle_inter_session_message(msg):
        msg_id = extract_msg_id(msg)
        
        # 1. 检查是否是重复消息
        if msg_id in processed_msg_ids:
            return  # 静默跳过,不回复
        
        # 2. 检查是否是任务完成确认
        if is_task_completion_ack(msg):
            log(f"任务完成: {msg_id}")
            return  # 静默,不回复
        
        # 3. 检查是否是历史队列消息
        if is_stale_message(msg):
            return  # 静默跳过
        
        # 4. 检查用户是否要求静默
        if user_requested_silence:
            return  # 遵守用户指令
        
        # 5. 检查是否需要回复
        if requires_response(msg):
            # 只发送一次回复
            send_single_response(msg)
        
        # 记录已处理
        processed_msg_ids.add(msg_id)
    ```
    
    ---
    
    ## 🎯 七大通信挑战与解决方案
    
    ### 1. 身份清晰问题
    
    **问题**:Agent 间收发身份信息不清晰,容易混淆。
    
    **解决方案**:标准化消息头协议
    
    ```
    所有 Agent 间消息必须携带消息头:
    
    [MSG_ID:msg:main:20260330T120000:abc123]
    [FROM:AGENT:main]
    [TO:AGENT:su-er]
    [TASK_TYPE:DELEGATE]
    [TIMESTAMP:2026-03-30T12:00:00+08:00]
    ---
    <消息正文>
    ```
    
    ### 2. 身份验证问题
    
    **问题**:如何确保 Agent 准确识别对方身份,防止伪造。
    
    **解决方案**:身份注册表 + 身份验证协议
    
    ```
    1. 身份注册表:agents/INDEX.md 作为权威来源
    2. 接收消息时验证 FROM 与 sessionKey 来源一致
    3. sessionKey 格式由 Gateway 控制,不可伪造
    ```
    
    ### 3. 用户 Agent 混淆问题
    
    **问题**:Agent 可能混淆用户身份与 Agent 身份。
    
    **解决方案**:身份类型区分 + 渠道隔离
    
    | 身份类型 | 标识格式 | 回复渠道 |
    |---|---|---|
    | 用户 | `feishu:user:ou_xxx` | `message` 工具 |
    | Agent | `agent:su-er:main` | `sessions_send` 工具 |
    
    **铁律**:
    - 用户消息 → 通过原渠道回复(message 工具)
    - Agent 消息 → 通过 sessions_send 回复
    - **永远不要把 Agent 消息回复给用户渠道**
    - **永远不要把用户消息回复给 Agent 渠道**
    
    ### 4. 对话死循环问题
    
    **问题**:Agent 互相对话陷入无限循环。
    
    **解决方案**:轮次限制 + 结束标记
    
    ```yaml
    对话限制:
      max_turns: 5          # 最大轮次
      turn_timeout: 60      # 单轮超时(秒)
      total_timeout: 300    # 总超时(秒)
    
    结束标记:
      [END] - 正常结束
      [TIMEOUT] - 超时结束
      [ERROR] - 错误结束
    ```
    
    **责任分配**:
    - 发起方:监控轮次,在接近上限时主动发送 [END]
    - 响应方:收到 [END] 后停止发送
    
    ### 5. 消息堆积问题
    
    **问题**:Agent 重复发送消息导致大量消息堆积。
    
    **解决方案**:消息 ID + 去重机制
    
    ```
    消息 ID 格式:msg:<agentId>:<timestamp>:<random>
    示例:msg:main:20260330T120000:abc123
    
    去重规则:
    - 维护已处理消息 ID 缓存
    - 缓存窗口:5 分钟
    - 收到重复 ID 时跳过处理
    
    重试限制:
    - NOTIFY 类型:不重试
    - 其他类型:最多重试 2 次
    ```
    
    ### 6. 静默等待问题
    
    **问题**:复杂任务需要发送方静默等待,接收方主动回复。
    
    **解决方案**:任务类型驱动
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/canxia-hub-agent-bridge.md

// REPO STATS

0 stars
0 open issues
Last commit: 7mo ago