概念

Subagent 是「子 agent」— 讓主 agent 分派長時間任務給背景執行。

主要工具：sessions_spawn

為什麼需要 Subagent？

問題	解法
任務太長（> 10 分鐘）	spawn 到背景
需要不同 model	指定 subagent model
避免 context 膨脹	獨立 session
並行任務	同時 spawn 多個

sessions_spawn 使用

{
  "tool": "sessions_spawn",
  "task": "研究 ANU 商學院所有科系，整理成表格",
  "agentId": "dev-agent",          // 可選：指定 agent
  "model": "anthropic/claude-sonnet-4-5", // 可選：指定 model
  "thinking": "high",                  // 可選：思考深度
  "runTimeoutSeconds": 3600,           // 最長執行時間
  "cleanup": "delete"                  // 完成後刪除 session
}

核心代碼

1. Spawn 流程

async function sessionsSpawn(params) {
  const { task, agentId, model, runTimeoutSeconds } = params;
  
  // 1. 產生 session key
  const label = generateLabel();
  const sessionKey = `spawn:${label}`;
  
  // 2. 建立獨立 session
  const session = {
    key: sessionKey,
    parent: currentSession.key,  // 記錄父 session
    model: model || agent.defaultModel,
    history: []
  };
  
  // 3. 背景執行
  runInBackground(async () => {
    const result = await runAgent(session, task, {
      timeout: runTimeoutSeconds
    });
    
    // 4. 完成後通知父 session
    await notifyParent(currentSession, {
      type: 'spawn_complete',
      label,
      result
    });
  });
  
  // 5. 立即返回（不等待完成）
  return {
    status: 'spawned',
    label,
    sessionKey
  };
}

2. 完成通知

// 子 agent 完成後，會發訊息給父 session
async function notifyParent(parentSession, result) {
  const message = `
🔔 子任務完成
Label: ${result.label}
結果摘要: ${result.summary}
`;
  
  // 注入到父 session
  await injectSystemEvent(parentSession, message);
  
  // 觸發 heartbeat 讓父 agent 看到
  await triggerHeartbeat(parentSession);
}

3. 追蹤 Subagent

// 列出所有 session（包括 subagents）
{
  "tool": "sessions_list",
  "kinds": ["main", "isolated"],
  "activeMinutes": 60,
  "messageLimit": 5
}

// 查看特定 session 歷史
{
  "tool": "sessions_history",
  "sessionKey": "spawn:research-anu",
  "limit": 50
}

// 發訊息給 subagent
{
  "tool": "sessions_send",
  "sessionKey": "spawn:research-anu",
  "message": "加入學費資訊"
}

使用場景

長時間研究任務

// 父 agent
{
  "tool": "sessions_spawn",
  "task": "搜尋並整理過去一週的 AI 新聞，產生報告",
  "runTimeoutSeconds": 1800  // 30 分鐘
}

// 子 agent 會：
// 1. web_search 搜尋新聞
// 2. web_fetch 抓取內容
// 3. 整理成報告
// 4. 完成後通知父 agent

並行任務

// 同時 spawn 多個子任務
await sessionsSpawn({ task: "研究 ANU" });
await sessionsSpawn({ task: "研究 USyd" });
await sessionsSpawn({ task: "研究 UNSW" });

// 三個子 agent 同時執行
// 各自完成後會通知

Cleanup 選項

{
  "cleanup": "delete"  // 完成後刪除 session
  // 或
  "cleanup": "keep"    // 保留 session（可以查看歷史）
}

💡 關鍵洞察

Spawn 是「非同步」的
- 立即返回，不等待完成
- 適合長時間任務
- 完成後會通知
子 agent 有獨立 context
- 不繼承父 session 歷史
- 只有 task 指令
- 適合獨立任務
可以指定不同 model
- 簡單任務用便宜 model
- 複雜任務用強 model
- 例：Sonnet 做研究，Haiku 做整理
sessions_send 可以「指揮」
- 任務進行中可以追加指令
- 像是遠端操控另一個 agent

工作分派策略

| 任務時長 | 執行方式 |
|---------|---------|
| < 10 分鐘 | 直接對話 |
| 10-60 分鐘 | sessions_spawn |
| 定期重複 | cron job |

🔗 核心檔案

Subagent 文檔：/opt/homebrew/lib/node_modules/openclaw/docs/tools/subagents.md
Multi-agent：/opt/homebrew/lib/node_modules/openclaw/docs/concepts/multi-agent.md

明天： Browser Control（CDP, profiles, snapshots）

Day 11: Subagents（sessions_spawn）