swallow/maestro

Fork 0

oss-sync a6d1879d63

CI / build-and-test (push) Has been cancelled

Details

sync: update from private repo (c764df2f)

2026-06-29 01:32:25 +00:00

7.6 KiB

Raw Blame History

Delegate

サブエージェントを同期的にインライン実行して、重い処理を委譲し本体のコンテキストを節約する。サブエージェントの中間ターンは親に見えないため、複雑な作業の最終結果だけを取得できる。

タスク分解の既定手段。research / general / brainstorming など調査・分析系のピースは、重いサブ調査を Delegate で 1 件ずつ直列に こなす設計になっている。並列の別ジョブ（SpawnSubTask）はデフォルト無効で、本当に並列が必要なワークスペースだけが 設定 → ツール タブで明示的に有効化する。ほとんどのタスクは Delegate で分解が完結するため、まず Delegate を検討する。

基本

Delegate({
  description: "ファイル群を分析",
  prompt: "以下の 10 個のファイルを読み込み、各々の行数・言語・依存関係を分析して、JSON サマリーを output/file-analysis.json に書き込む。ファイルリスト: [リストを展開]"
})

呼び出すと、サブエージェントが自身の conversation context で独立に実行される。サブエージェントが完了（success / aborted）したら、最終結果の文字列だけを返す。サブエージェントの中間会話ターンは親に入らない —— つまり、長い調査や複雑な分析が親のコンテキスト使用量に影響しない。

いつ使うか

Delegate が向いているケース

単一の明確で集中した委譲タスク（「複数ファイルから要約を抽出」「重い分析を実行」「外部情報の深い調査」）
中間結果は不要で、最終成果物だけが欲しい（サブエージェントの思考プロセスは必要ない）
親のコンテキスト節約が最優先（サブの中間ターンが消費メモリ = 親に影響しない）
処理が比較的短時間で完了する見込み

例:

「100 個のファイルを読んで, CSV を生成」→ delegate で委譲, 完了後に result を引き継ぐ
「特定キーワードで 30 件検索し, 記事要約→集約」→ 重い WebFetch も delegate 内で完結
「複数 PDF を OCR → テキスト抽出 → 解析」→ 前処理を delegate, 後続は親が実行

SpawnSubTask が向いているケース（opt-in）

SpawnSubTask はデフォルト無効。使うにはワークスペースの 設定 → ツール タブで有効化する（Bash などと同じセンシティブ扱いの opt-in ツール）。有効化していないワークスペースでは Delegate での直列分解だけになる。

並列の別ジョブが本当に効く、次のようなケースに限って有効化を検討する:

複数の独立したテーマ（A, B, C に分解）で、壁時計時間の短縮が重要
サブタスク間に依存がない（A が完了してから B という制約がない）
各サブの成果物がそれぞれ意味を持つ（集約不要または集約が簡単）

GPU・実行枠を多く消費するため、逐次で足りる場合は Delegate を優先する。

Delegate が向かないケース

対話が必要（ASK ツールを呼ぶ）→ 子の ASK は親に bubbles up する
ネスト深さが 2 を超える（delegate の中から delegate, その中から delegate...）
超長時間タスク（非常に長くかかる処理）→ 親が完了を待ってブロックするため、焦点を絞ったタスクに限定すること

パラメータ

パラメータ	型	必須	説明
`description`	string	✅	委譲タスクを表す 3〜6 語の短いラベル
`prompt`	string	✅	サブエージェントへの自己完結した完全な指示

prompt の書き方

自己完結で書く。サブエージェントは親の conversation history を見られないため：

タスクの全背景を展開する（親の context は参照不可）
前提情報・ファイルリストなどを明示的に記載
期待する成果物を明確に（ファイル名・形式・場所）
成功の定義を簡潔に述べる

❌ 「さっきの調査の続きをやって」
✅ 「以下のキーワード 3 つについて [展開], 各々のメリット・デメリット・ユースケースを調査し, output/comparison.md に Markdown 形式で整理する。セクション: 概要 / メリット / デメリット / 用途 / 参考資料"

❌ 「ファイルを分析して」
✅ 「input/ 配下の全 .ts ファイルを読み込み, 以下を計測して output/stats.json に JSON 形式で出力: { fileName, lineCount, exports[], imports[] }"

結果の使い方

Delegate の result は文字列。次の movement で Read / Bash 等で参照:

const delegateResult = "..."; // Delegate が返した result

// 結果ファイルを読み込む（委譲先が output/ に書いていれば）
Read({ path: "output/analysis.json" })

// またはログを参照
Bash({ command: "cat logs/activity.log | tail -20" })

制限

直列実行: Delegate × N 個を呼ぶとシリアルに実行される（並列不可）。並列が必要なら SpawnSubTask（要 opt-in 有効化）を使う。直列のぶん壁時計時間はやや長くなるが、GPU 負荷は軽く、各サブが綺麗なコンテキストで動くので品質は揃いやすい
ネスト深さ: 約 2 レベル（delegate 内からさらに delegate を呼ぶのは許可だが, 3 段階目以上は危険）
完了待ちブロック: 親は子が完了するまでブロックされるため、1 回の delegate は焦点を絞ること
ASK 必須情報: サブエージェントが ASK を呼んだら, 親に [delegate 要追加情報] ... と bubble up される。親が回答を transition({lessons: "..." }) で与える
ワークスペース共有: 同じ workspace で実行されるため, output/ は親から見える。input/ も共有

使用例

例 1: ファイル分析の要約化

Delegate({
  description: "ソースファイル群を分析",
  prompt: `
以下の 5 つのファイルを読み込み, 各々の:
- 行数
- 主要な exported 関数・クラス名
- 依存 import 数

を計測して, output/file-summary.json に以下形式で出力:

[
  { file: "path/to/file.ts", lines: 123, exports: [...], imports: 5 },
  ...
]

ファイル:
1. src/engine/agent-loop.ts
2. src/engine/piece-runner.ts
3. src/llm/openai-compat.ts
4. src/worker.ts
5. src/config-manager.ts

実行後, 必ず output/file-summary.json に JSON を書き込んで終了すること。
  `
})

例 2: 複数 URL 検索 → 要約集約

Delegate({
  description: "キーワード検索と要約集約",
  prompt: `
以下の 3 つのキーワードで Web 検索し, 上位 5 件ずつ fetch して要約をまとめる:
- キーワード A
- キーワード B
- キーワード C

各キーワード毎に:
1. WebSearch で 5-10 件検索
2. 各 URL を WebFetch で取得
3. テキスト要約（最大 5 行）を抽出

結果を output/search-summary.md に Markdown で出力:

# Search Results

## Keyword A
[上位 3 件の要約]

## Keyword B
[上位 3 件の要約]

## Keyword C
[上位 3 件の要約]

実行後, output/search-summary.md に結果を保存して終了。
  `
})

詳細は ReadToolDoc

詳細な実装・エラーハンドリング・context 管理については ReadToolDoc({ name: "Delegate" }) で確認可能。

7.6 KiB Raw Blame History Unescape Escape