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?

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"

⚠️ Note: mode="session" must also have thread=true set, otherwise subsequent messages cannot be routed correctly.

Three-Tier Security Protection

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.