Skill: openlark/multi-agent-communication (version 1.0.0)

--- name: multi-agent-communication description: Based on two core tools, sessions_spawn and sessions_send, to help users build, manage, and optimize distributed Agent systems, enabling task decomposition, parallel processing, and efficient coordination among Agents. --- # Multi-Agent Communication Core tools: `sessions_spawn` (launch child Agents) and `sessions_send` (send messages to existing Agents). ## Use Cases - Launching child Agents for background tasks - Multi-Agent collaboration and negotiation - Configuring Agent permissions and concurrency limits - Choosing the appropriate communication mode (run/session/send) - Designing Agent team workflows ## Two Core Tools ### sessions_spawn — Create a new Agent instance ``` sessions_spawn({ task: "Review PR #123", agent: "code-reviewer", // Agent ID (not SOUL name) mode: "run", // run=one-shot, session=persistent thread: false, // Whether to bind to a message thread runTimeoutSeconds: 300 // Optional, timeout duration }) ``` **Essence: Fork a new process.** Creates an independent session and execution environment, automatically pushing results back to the parent Agent upon completion. In mode="run", the child Agent's execution process is not visible to the user by default. ### sessions_send — Send a message to an existing Agent ``` sessions_send({ sessionKey: "agent:main:subagent:abc", label: "security", // Use sessionKey or label message: "Check security", timeoutSeconds: 30 // Synchronous wait; 0=asynchronous delivery }) ``` **Essence: Inter-Process Communication (IPC).** Sends messages to an existing session, supporting multi-round A2A negotiation (up to 5 rounds of ping-pong). ## Core Decision: Which One to Choose? | Scenario | Tool | Mode | |----------|------|------| | Background data processing, one-shot analysis | sessions_spawn | mode: "run" | | Parallel task decomposition (multiple spawns) | sessions_spawn | mode: "run" | | Multi-round code review (user-visible) | sessions_spawn | mode: "session", thread: true | | Real-time collaborative Q&A between Agents | sessions_send | timeoutSeconds > 0 | | Asynchronous delivery, no reply needed | sessions_send | timeoutSeconds: 0 | **Quick Judgment:** - Need to **create a new Agent** → sessions_spawn - Need to communicate with an **existing Agent** → sessions_send ## Spawn Execution Flow (10 Stages) ``` User Request → Main Agent → sessions_spawn ↓ [1. Permission Check] → Verify depth, concurrency, whitelist ↓ [2. Session Creation] → Generate unique sessionKey ↓ [3. Thread Binding] → (Optional) Bind to Discord/Slack thread ↓ [4. Attachment Handling] → Snapshot transfer (independent lifecycle) ↓ [5. System Prompt] → Inject task context ↓ [6. Working Directory] → Inherit parent Agent or use target Agent config ↓ [7. Agent Launch] → Via Gateway RPC ↓ [8. Runtime Registration] → Record in SubagentRegistry ↓ [9. Hook Trigger] → Notify plugins ↓ [10. Result Return] → Return childSessionKey ``` Results are automatically pushed back to the parent Agent via Sweeper (checks every 1-8 seconds), no manual polling required. ## Session Key Design ``` Main Agent: agent:main:main Child Agent: agent:main:subagent:<uuid> Grandchild: agent:main:subagent:<uuid>:subagent:<uuid> ``` UUID ensures global uniqueness; the hierarchical structure facilitates routing and traceability. ## mode="run" vs. mode="session" | Feature | run | session | |---------|-----|---------| | Lifecycle | One-shot, deleted upon completion | Persistent, awaits subsequent messages | | Thread Binding | Not supported | Required (thread=true) | | User Visibility | ❌ Completely invisible | ✅ Visible in thread | | Applicable Scenarios | Background data processing | Multi-turn conversations, code reviews | **⚠️ Note: mode="session" must also have thread=true set**, otherwise subsequent messages cannot be routed correctly. ## Three-Tier Security Protection | Constraint | Default Value | Purpose | |------------|---------------|---------| | Max Recursion Depth | 1 | Prevent infinite recursion | | Max Child Processes | 5/session | Prevent resource exhaustion | | Whitelist Mechanism | Configurable | Cross-Agent permission control | ## A2A Multi-Round Negotiation (sessions_send) ``` Agent A ──"Format this code"──→ Agent B ←─"Which style do you prefer?" Agent A ──"Use Prettier"─────→ Agent B ←─"Done" Agent A ──REPLY_SKIP──────────→ Agent B ``` - Maximum 5 rounds (configurable) - Either party replies with REPLY_SKIP_TOKEN to end - Final result delivered to the user channel ## Key Design Decisions - **Snapshots over References**: Attachments are copied to the child Agent; the child can still access them even after the parent deletes them. - **Push over Polling**: Zero polling cost; a 30-second task saves approximately 15,000 tokens. - **Cross-Agent Workspace Isolation**: Same-type child Agents inherit the parent directory; cross-type ones use the target Agent's configuration. ## Configuration Suggestions See [references/config.md](references/config.md) for details. ## Design Patterns See [references/patterns.md](references/patterns.md) for details.

path: references/config.md
content: # Agent Configuration Reference

## Basic Configuration

```json5
{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 1,         // Child Agent depth (recommended 1-2)
        maxChildrenPerAgent: 5,   // Max parallel child processes
        runTimeoutSeconds: 300    // Default timeout of 5 minutes
      }
    },
    list: [
      {
        id: "main",
        subagents: {
          allowAgents: ["code-reviewer", "doc-writer"]  // Whitelist
        }
      }
    ]
  },
  session: {
    agentToAgent: {
      enabled: true,
      allow: ["*"],              // Allow all cross-Agent communication
      maxPingPongTurns: 5        // A2A negotiation capped at 5 rounds
    }
  }
}
```

## Advanced Configuration (Complex Tasks)

```json5
{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2,         // Two levels of nesting
        maxChildrenPerAgent: 10,  // More parallel processes
        runTimeoutSeconds: 600    // 10-minute timeout
      }
    }
  }
}
```

## Permission Configuration (Whitelist)

```json5
{
  agents: {
    list: [
      {
        id: "main",
        subagents: {
          allowAgents: ["analyzer", "reviewer", "writer"]  // Only allow these child Agents
        }
      }
    ]
  }
}
```

## Constraint Type Summary

| Constraint | Type | Default | Purpose |
|------------|------|---------|---------|
| maxSpawnDepth | int | 1 | Prevent infinite recursion |
| maxChildrenPerAgent | int | 5 | Prevent resource exhaustion |
| allowAgents | string[] | Configurable | Whitelist permission control |
| runTimeoutSeconds | int | 300 | Single task timeout |
| maxPingPongTurns | int | 5 | A2A negotiation round cap |

path: references/patterns.md
content: # Design Pattern Reference

## Fork-Join (Parallel Processing)

Multiple child Agents process sharded tasks in parallel, with results aggregated before replying to the user.

```
Main Agent
  ├─ spawn analyzer-1 (Shard A) ──→ [1. announcement]
  ├─ spawn analyzer-2 (Shard B) ──→ [2. announcement]
  └─ spawn analyzer-3 (Shard C) ──→ [3. announcement]
                                      ↓
                              Aggregate results → Reply to user
```

**Applicable Scenarios:** Parallel data analysis, large file shard processing, batch review.

## Master-Worker (Master-Slave Collaboration)

Create persistent expert Agents; the main Agent queries each expert and synthesizes their opinions.

```javascript
// 1. Create expert Agents (persistent)
sessions_spawn({ agent: "security-expert", label: "security", mode: "session" });
sessions_spawn({ agent: "perf-expert",     label: "performance", mode: "session" });

// 2. Main Agent queries the experts
const security = await sessions_send({ label: "security", message: "Are there any security risks?" });
const perf = await sessions_send({ label: "performance", message: "Where are the performance bottlenecks?" });

// 3. Synthesize expert opinions
return synthesize(security, perf);
```

**Applicable Scenarios:** Code requires both security and performance reviews, multi-dimensional evaluation.

## Pipeline (Assembly Line)

At each stage, spawn an Agent; the output of one serves as the input for the next, akin to a factory assembly line.

```
PDF → Extractor ─→ Raw Text → Cleaner ─→ Clean Text → Summarizer ─→ Summary
     (spawn)                     (spawn)                     (spawn)
```

**Applicable Scenarios:** Data processing pipelines, multi-stage content refinement.

## Comparative Summary

| Pattern | Spawn Count | Parallel | Communication Method | Typical Scenario |
|---------|-------------|----------|----------------------|------------------|
| Fork-Join | N in parallel | ✅ | announcement | Parallel data analysis |
| Master-Worker | N persistent | ❌ | sessions_send | Expert collaboration |
| Pipeline | N sequential | ❌ | announce chaining | Multi-stage processing |

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)