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#

javascript

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:

javascript

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

Step 3: Send Message#

javascript

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#

javascript

// 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#

TypeFormat ExampleUsable for Agent-Agent?Agent-Human DMagent:sienna:feishu:direct:ou_xxx❌ ForbiddenAgent in Groupagent:sienna:feishu:group:oc_xxx❌ ForbiddenSubagent Sessionagent:maxwell:subagent:xxx✅ Allowed

---

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#

text

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)#

AgentLabelsessionIdleomaxwell-to-leo9d519dc9-0239-4284-8077-3ed4bccd486dsiennamaxwell-to-sienna05a93e6d-4a50-4503-a9c8-4aaf7da8c414letusmaxwell-to-letus391a4a78-43ab-4e04-95fe-abfd414b1c64codingmaxwell-to-codingebba5ff4-87f6-430b-80e5-269319b122c0mainmaxwell-to-maind7eb2edc-7acc-40e7-838d-8a9cb08820c0

---

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:

javascript

// 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#

javascript

sessions_list({ limit: 50 })

Step 2: Create New Session (if none found)#

javascript

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

Step 2.5: Protect Session (New)#

javascript

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

Step 3: Send Message#

javascript

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

---

Last updated: 2026-03-17