Multi-Agent Communication

---

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:
Grandchild:    agent:main:subagent::subagent:

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 for details.

Design Patterns

See references/patterns.md for details.