163 lines
7.6 KiB
Markdown
163 lines
7.6 KiB
Markdown
# Delegate
|
||
|
||
サブエージェントを同期的にインライン実行して、重い処理を委譲し本体のコンテキストを節約する。サブエージェントの中間ターンは親に見えないため、複雑な作業の最終結果だけを取得できる。
|
||
|
||
**タスク分解の既定手段**。research / general / brainstorming など調査・分析系のピースは、重いサブ調査を Delegate で **1 件ずつ直列に** こなす設計になっている。並列の別ジョブ（SpawnSubTask）はデフォルト無効で、本当に並列が必要なワークスペースだけが **設定 → ツール** タブで明示的に有効化する。ほとんどのタスクは Delegate で分解が完結するため、まず Delegate を検討する。
|
||
|
||
## 基本
|
||
|
||
```js
|
||
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 等で参照:
|
||
|
||
```js
|
||
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: ファイル分析の要約化
|
||
|
||
```js
|
||
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 検索 → 要約集約
|
||
|
||
```js
|
||
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" })` で確認可能。
|