- 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 childSessionKeyResults 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 for details.
Design Patterns
See references/patterns.md for details.