Agent Communication

⚠️ Important Rules

NEVER reuse agent-human conversation sessions!

• Human-agent session format: agent:xxx:feishu:direct:ou_xxx
• Agent-Agent calls MUST use sessions_spawn to create subagent sessions

Strict Workflow (Do Not Skip)

Step 1: Check for Existing Session

sessions_list({ limit: 50 })

Find in results:

• Contains "subagent" marker
• Label matches sender-to-receiver or receiver-to-sender (bidirectional check)

Example:

• If main wants to find sienna, look for main-to-sienna or sienna-to-main
• Either one works, no need to create new

Step 2: Create New Session (if none found)

If Step 1 returns nothing, create with sessions_spawn:

sessions_spawn({
  label: "main-to-sienna",  // Format: sender-to-receiver
  runtime: "subagent",
  task: "",                 // Task goes in Step 3
  mode: "run"
})

Step 3: Send Message

sessions_send({
  sessionKey: "agent:main:subagent:xxx",  // From Step 1 or 2
  message: "Task description..."           // Actual task here
})

⚡ Key Rules (Must Follow)

1. No skipping Step 1: Must run sessions_list first
2. No shortcuts: Must follow Step 1 → 2 → 3
3. Bidirectional reuse: a-to-b and b-to-a both work, no need for two
4. Reply to sender directly: Without special instructions, reply to the initiator
5. Use subagent marker: sessionKey must contain "subagent"

❌ Wrong Examples

// Wrong 1: Create without checking
sessions_spawn({...})  // Must check first!

// Wrong 2: Use human conversation session
sessionKey: "agent:sienna:feishu:direct:ou_xxx"  // Forbidden!

// Wrong 3: Create both directions
// main-to-sienna and sienna-to-main - one is enough!

// Wrong 4: Reply to others
// Should reply directly to sender, no forward or group post

SessionKey Format Guide

Response Rules

Default: Response goes directly to the sender

• Sender sends message → Reply directly to sender
• No need to forward to others
• No need to post to group
• Unless sender explicitly asks to forward

Workflow Pseudocode

1. Call sessions_list({ limit: 50 })
2. Loop through results, find both:
   - Contains "subagent" marker
   - Label matches "sender-to-receiver" OR "receiver-to-sender"
3. Found → Use that sessionKey, goto Step 5
4. Not found → Create with sessions_spawn, save sessionKey
5. Call sessions_send({ sessionKey, message })
6. Done

Current Active Channels (Reference)

Notes

• thread=true mode temporarily unavailable
• Labeled subagent sessions can be found by sessions_list
• mode="session" requires thread=true, currently unavailable

Session Protection Mechanism (New)

Step 2.5: Protect Session (Run After Creation)

New subagent sessions may be auto-cleaned by default. To ensure long-term availability, protect after creation:

// Protect session from auto-cleanup
exec({
  command: `openclaw sessions cleanup --agent [target-agent] --active-key "${sessionKey}" --enforce`
})

Note: Replace ${sessionKey} with actual sessionKey

Complete Flow (With Protection)

Step 1: Check for Existing Session

sessions_list({ limit: 50 })

Step 2: Create New Session (if none found)

sessions_spawn({
  label: "main-to-sienna",
  runtime: "subagent",
  task: "",
  mode: "run"
})
// Returns sessionKey, format: agent:xxx:subagent:xxx

Step 2.5: Protect Session (New)

exec({
  command: `openclaw sessions cleanup --active-key "agent:xxx:subagent:xxx" --enforce`
})

Step 3: Send Message

sessions_send({
  sessionKey: "agent:main:subagent:xxx",
  message: "Task description..."
})

Last updated: 2026-03-17