122 lines
6.6 KiB
Markdown
122 lines
6.6 KiB
Markdown
# SpawnSubTask
|
||
|
||
タスクを並列サブタスクに分解して実行する。各サブタスクは独立した worker（ジョブ）で動き、完了後に親タスクが結果を集約する。
|
||
|
||
> **デフォルト無効（opt-in）**。SpawnSubTask は Bash などと同じセンシティブ扱いのツールで、初期状態ではエージェントに提示されない。使うにはワークスペースの **設定 → ツール** タブで明示的に有効化する。有効化していない場合、SpawnSubTask は呼べず、分解は [`Delegate`](./delegate.md)（直列・インプロセス）で行う。
|
||
>
|
||
> タスク分解の既定手段は Delegate（直列）。research / general / brainstorming などのピースは Delegate でサブ調査を 1 件ずつこなす。SpawnSubTask は「壁時計時間の短縮のために独立テーマを本当に並列で走らせたい」ワークスペースだけが有効化する。
|
||
|
||
## 基本
|
||
|
||
```js
|
||
SpawnSubTask({
|
||
title: "ローカル LLM 比較調査",
|
||
instruction: "Ollama, vLLM, llama.cpp の最新性能ベンチマークを比較する。各ツールについて: 1) 直近6ヶ月の主要ベンチマーク, 2) ハードウェア要件, 3) 対応モデル一覧 を output/report.md にまとめる。",
|
||
piece: "research" // 任意。指定しないと自動分類
|
||
})
|
||
```
|
||
|
||
呼び出すと `subtasks/{index}/` にサブタスクのワークスペースが作られ、結果はそこに集約される。
|
||
|
||
## いつ使うか
|
||
|
||
まず Delegate（直列）で足りるかを検討する。SpawnSubTask は opt-in で有効化したうえで、**並列の別ジョブで壁時計時間を縮めたい**場合に限って使う。
|
||
|
||
### 並列分解が効果的なケース
|
||
|
||
- 2 つ以上の **独立したテーマ**（互いに参照しない）
|
||
- 各テーマが軽くなく、調査・処理に時間がかかる
|
||
- 分解後の各タスクが単独でも意味を持つ成果物になる
|
||
- 壁時計時間の短縮が GPU・実行枠の追加消費に見合う
|
||
|
||
例:
|
||
- 「3 つの製品比較レポート」→ 製品ごとに 3 サブタスク
|
||
- 「複数 PDF の OCR 処理」→ ファイルごとに分解
|
||
- 「複数 SNS の情報収集」→ プラットフォーム別に分解
|
||
|
||
### 分解しないほうがよいケース
|
||
|
||
- 単一テーマで論理的に連続する処理（A→B→C のように依存）
|
||
- サブタスクが極端に小さい（オーバーヘッドの方が大きい）
|
||
- 全体像を見ながら判断する必要がある作業（対話的タスク等）
|
||
|
||
## instruction の書き方
|
||
|
||
- **完結した依頼文**で書く（親タスクの文脈を持たないので、サブタスクは instruction だけで判断する）
|
||
- 期待する成果物（出力ファイル名・場所）を明示
|
||
- 必要な前提情報があれば文中に展開
|
||
|
||
❌ 「これと同じ調査を別キーワードでやって」
|
||
✅ 「キーワード『A』『B』『C』について、各々のメリット・デメリットを比較する独立した調査を行い、output/A-vs-B.md にまとめる」
|
||
|
||
## piece の指定
|
||
|
||
- 省略時: 親と同じ classifier ロジックで自動選択
|
||
- 明示する場合: `research`, `general`, `office-process` 等の piece 名を指定
|
||
|
||
## WaitSubTask（完了待ち）
|
||
|
||
`SpawnSubTask` でサブタスクを起動したあとは、**`WaitSubTask`（引数なし）を 1 回呼んで全サブタスクの完了を待つ**。
|
||
|
||
```js
|
||
SpawnSubTask({ title: "A の調査", instruction: "..." })
|
||
SpawnSubTask({ title: "B の調査", instruction: "..." })
|
||
SpawnSubTask({ title: "C の調査", instruction: "..." })
|
||
WaitSubTask() // ここで全部の完了を待つ
|
||
// 再開後、subtasks/*/result.md を Read して集約 → complete
|
||
```
|
||
|
||
- `WaitSubTask` は **同期的にブロックしない**。呼ぶとジョブはいったん停止（park）して worker を解放し、全サブタスクが終わると **同じ movement のまま再開** する
|
||
- 再開時、各サブタスクの結果は `subtasks/{index}/result.md` に書き出されている。Read で読んで集約レポートを作る
|
||
- 起動した分の成果物は `subtasks/{index}/output/` 以下にも残る
|
||
|
||
### ワークフロー
|
||
|
||
1. `SpawnSubTask` を必要な数だけ呼ぶ（並列に起動される）
|
||
2. `WaitSubTask()` を 1 回呼ぶ
|
||
3. 再開後、`subtasks/*/result.md` を読んで集約する
|
||
4. `complete` で終了する
|
||
|
||
### auto-park（取りこぼし防止）
|
||
|
||
サブタスクがまだ走っている最中に `complete`（success）を呼んでも、エンジンが**偽の完了を返さず、自動で park して完了を待つ**。`WaitSubTask` を呼び忘れても結果を取りこぼさない安全網。とはいえ意図を明示するため、原則 `WaitSubTask` を明示的に呼ぶこと。
|
||
|
||
### orphan の自動キャンセル
|
||
|
||
親ジョブが**失敗・キャンセル・リトライ**したとき、まだ走っているサブタスクは**自動でキャンセル**される。親が消えたのに子だけ GPU を使い続ける「ゾンビサブタスク」は発生しない。
|
||
|
||
ただし **ASK（ユーザー回答待ち）で停止した場合は子を残す**。親があとで再開して結果を使うため。
|
||
|
||
### delegate との違い
|
||
|
||
| | delegate | SpawnSubTask + WaitSubTask |
|
||
|---|---|---|
|
||
| 既定 | **デフォルト有効**（分解の既定手段） | **デフォルト無効**（要 opt-in 有効化） |
|
||
| 実行 | 直列・インプロセス | 並列・別ジョブ |
|
||
| 待機 | 自動（1 ツール呼び出しで完結） | `WaitSubTask` で待つ |
|
||
| 負荷 | GPU・実行枠が軽い | 並列ぶん多く消費する |
|
||
| 向く用途 | 逐次の分解・重い委譲全般 | 独立テーマを並列で短時間化したいとき |
|
||
|
||
## 起動の間隔（spawn_stagger_ms）
|
||
|
||
短時間に大量の `SpawnSubTask` を呼ぶと、その一団が GPU スロットの優先順位を一気に奪ってしまう。これを避けるため、`SpawnSubTask` のキュー投入の間に既定で 1 秒の間隔を入れる。
|
||
|
||
```yaml
|
||
subtasks:
|
||
spawn_stagger_ms: 1000 # SpawnSubTask 投入間の間隔（ミリ秒、デフォルト 1000、0 で無効）
|
||
```
|
||
|
||
- `0` にすると間隔を入れず即時に投入する
|
||
- エージェントから見た呼び出し方は変わらない（透過的に間隔が入るだけ）
|
||
|
||
## 結果の参照
|
||
|
||
サブタスク完了後、親タスクは:
|
||
- `subtasks/{index}/result.md` にサブタスクの要約結果がある（Read で読む）
|
||
- `subtasks/{index}/output/` 以下にサブタスクの成果物がある
|
||
|
||
## 制限
|
||
|
||
- ネスト深さは `subtasks.maxDepth`（デフォルト 2）まで
|
||
- サブタスクが waiting_human 等で停止すると親もブロックされる
|