学習目標:
- サブエージェントがなぜコンテキスト管理の一手になるのかを説明する: きれいなウィンドウと、返ってくるサマリー。「過程」をメインウィンドウの外に置く
- 過程トークンと結論トークンの比率、そして実測のコストデータを使って、そのタスクをサブエージェントに渡す価値があるか判断する
- 本シリーズのコース7で書いたハーネスループにサブエージェントのディスパッチを組み込み、1回のディスパッチがメインウィンドウにサマリーをちょうど1件だけ返すようにする
前提: コンパクションとノートを扱ったレッスン4を修了し、本シリーズのコース7「Agent Harness Fundamentals: Loops and Control」で書いたハーネスループを実行できること | 前: レッスン4 << | 次: レッスン6 >>
サブエージェントには本シリーズのコース6「マルチエージェントコラボレーション」ですでに出会っています。タスクをどう分けるか、結果をどう報告するか、複数のエージェントがどう協調するか。あのコースが答えたのは、複数のエージェントがどう協働するかという問いでした。このレッスンが答えるのは別の問いです。そもそもサブエージェントは、なぜコンテキスト管理の技法なのか？
言い換えましょう。リードエージェントが1体だけで、チームの協調がまったく必要ない場合でも、あなたはサブエージェントに手を伸ばしたくなります。分業のためではなく、分離のためにです。
レッスン1の予算という見方を思い出してください。モデルがコンテキストを解析するときはアテンション予算から引き出しており、コンテキストに入る新しいトークンはすべてその予算を少しずつ削ります1。トークンを積み上げるほど、モデルがそのコンテキストから情報を正確に想起する能力は落ちていきます1。そしてエージェントは、まさにトークンが積み上がりやすい場です。ループの各ターンが、次のターンの推論に関係しうる新しいデータを生み、捨てるのも難しく、抱えるのも難しい1。
探索タスクはこの問題が最も鋭く出る形です。たとえばメインエージェントが、数十万行のリポジトリ全体から非推奨 API のすべての呼び出し箇所を追跡しなければならないとします。grep が十数回、開くファイルが 20 個、読む行数が数千行。この中間コンテンツは数万トークンに達するのに、残す価値のある結論はせいぜい5行です。「呼び出し箇所はこの3つのモジュールに集中しており、移行順序の推奨はこうです」。これがすべてメインウィンドウで起きれば、アテンション予算は過程に食い尽くされ、結論とその後の作業のためにほとんど残りません。
サブエージェントは、まさにこの問題に向けられた刃です。
仕組みは1文に収まります。専門化したサブエージェントが、焦点を絞ったタスクをきれいなコンテキストウィンドウで処理し1、探索が生む大量の中間コンテンツ — 検索結果、生のファイル内容、行き止まり — はすべてサブエージェントの内側に留まり1、メインエージェントに返るのは凝縮され蒸留された作業のサマリーだけ、多くの場合 1,000-2,000 トークンです1。
したがってメインエージェントのウィンドウが運ぶのは結論だけで、過程は決して運びません。これは非対称な設計です。サブエージェントは探索に数万トークンを燃やすかもしれませんが、そこから出ていくのは短い一節のテキストだけです。
コードにすれば、これはコース7で書いたハーネスの新しい初手にすぎません。簡潔に保つため、あのコースのループで繰り返し登場した2つの動作をここではヘルパーにまとめています。textOf はレスポンスからテキストブロックを取り出し、appendToolResults はこのターンのツールを実行して tool_result ブロックをメッセージ配列に追加します（内部でやっていることは、あのコースで手書きしたものとまったく同じです。各 tool_use を実行し、結果を集め、送り返す）。
3つの細部に注目してください。第1に、messages はたった1件のタスク記述から始まり、メインエージェントの履歴を一言も運びません。これが「きれいなウィンドウ」の意味のすべてです。第2に、この関数が返すのは textOf(response)、つまりただの文字列です。ループの内側で積み上がった数十回のツール往復は、ローカル変数 messages とともに消えます。第3に、サブエージェントのシステムプロンプトは「生のテキストを繰り返すな」と明示的に要求しています。サマリーの圧縮品質は、まさにここで決まります。
メインエージェント側では、ディスパッチという動作は、すでにある stop_reason ループに差し込むただのツールです。
task フィールドの description を見てください。「自己完結したタスク記述。サブエージェントはこの会話の履歴を見ることができない」。この一文はメインエージェントに向けて書かれています。メインエージェントはタスクを余さず述べなければなりません。向こう側にいるのは記憶を持たない新しいウィンドウだからです。ツールの description で目的と境界をここまで正確に言い切ること自体が、レッスン2の「コンテキストとしてのツール」の考え方そのものです。ツールは自己完結し、エラーに強く、意図された用途について極めて明確であるべきです1。
仕組みは片づきました。次は実測です。Anthropic は自社のマルチエージェントリサーチシステム — Claude の Research 機能の背後にあるアーキテクチャ — を公開の形で書き起こしており、これは希少な一次エンジニアリング資料です2。
そこにある知見のうち、3つがこのレッスンに直結します。
余談ですが、並列性は速度も買います。複数のリサーチの筋が同時に進むからです。ただしそれはオーケストレーションの話題で、本シリーズのコース6ですでに扱っています。このレッスンは圧縮の側面だけを見つめます。
利点を並べたなら、請求書も並べなければなりません。同じ記事に実測値が載っています。これらは Anthropic のリサーチシステムでの実測であり、普遍的な法則ではないことに注意してください。
彼ら自身の結論は率直です。"Multi-agent systems work mainly because they help spend enough tokens to solve the problem."2
なのではっきり言いましょう。サブエージェントはコスト削減策ではありません。 総トークンは上がる一方です。タスクを言い直し、背景を敷き直し、複数のウィンドウが同時に燃えます。買っているのは別のものです。どのウィンドウも劣化していない範囲に留まり、アテンション密度が最後まで高いまま保たれること。これはアテンションの取引です。総トークンを多く払って、それぞれにきれいなウィンドウを得るのです。
その取引が見合うのはどんなときでしょうか。レッスン1の予算という見方に戻ります。コンテキストは限界収穫が逓減する有限の資源です1。判断の物差しは2つです。
サブエージェントのウィンドウがどれほどきれいでも、やはり有限です。本当に長期にわたるタスクについて、あの記事は組み合わせ技を描いています。エージェントは完了した作業フェーズを要約して要点を外部メモリに保存し2、それからきれいなコンテキストを持つ新しいサブエージェントを立ち上げて引き継がせ、丁寧なハンドオフによって連続性を保ちます2。
これはレッスン4とこのレッスンを、ひと続きの手順に縫い合わせます。
NOTES.md、タスクリスト。それらはファイルシステムに住み、どのウィンドウのアテンションも占有しません。引き継ぎ文書には何を書くのでしょうか。レッスン4のコンパクションとまったく同じ取捨の基準を再利用してください。アーキテクチャ上の決定、未解決のバグ、実装詳細を残し、冗長なツール出力を捨てる1。引き継ぎを書くこととコンパクションのサマリーを書くことは同じ技芸で、変わるのは読み手が「未来の自分」から「次のサブエージェント」になることだけです。
最後に、毎日使っている実装と突き合わせてみましょう。Claude Code の公式ベストプラクティスははっきり述べています。コンテキストウィンドウはすぐに埋まり、埋まるにつれてパフォーマンスは劣化する。"The context window is the most important resource to manage."4 コンテキストが根本的な制約である以上、サブエージェントは利用できる最も強力なツールの1つです4。
その実装は、このレッスンが述べてきた仕組みと一致します。サブエージェントは別々のコンテキストウィンドウで走り、サマリーを報告して返します4。Claude Code に「このバグの根本原因を突き止めて」と頼めば、ディスパッチされたサブエージェントは grep し、ファイルを読み、呼び出し連鎖をたどります。その探索はすべてサブエージェント自身のウィンドウで起き、メインの会話が受け取るのは最後の調査サマリーだけです。調査のスコープを狭く切るか、サブエージェントに渡すかすれば、探索がメインのコンテキストを消費することはありません4。
インターフェイスの中でサブタスクがバックグラウンドで走り、終わったときにメインの会話が短いレポートだけを得るのを見たなら、それがこのレッスンが最初から述べてきた「きれいなウィンドウを入り口に、圧縮したサマリーを出口に」です。
ここまでで、長時間タスクの道具箱の3点すべてを見たことになります。コンパクション（レッスン4）、構造化ノート（レッスン4）、そしてマルチエージェントアーキテクチャ（このレッスン）。3つに共通する狙いは、エージェントが一連の行動を通じて一貫性、コンテキスト、目標志向の振る舞いを保てるようにすることです1。レッスン6では、この3つすべてをあなた自身のハーネスに組み込みます。
>> レッスン6: 実践: ハーネスにコンテキスト管理を組み込む
Effective context engineering for AI agents — Anthropic Engineering — https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11
How we built our multi-agent research system — Anthropic Engineering — https://www.anthropic.com/engineering/multi-agent-research-system ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13
Building Effective AI Agents — Anthropic Engineering — https://www.anthropic.com/engineering/building-effective-agents ↩ ↩2
Best practices for Claude Code — Claude Code Docs — https://code.claude.com/docs/en/best-practices ↩ ↩2 ↩3 ↩4 ↩5
LegacyLedgerReader API をまだ使っているすべての呼び出し箇所を見つけ、移行順序を提案する。タスクごとに、分離する（サブエージェントをディスパッチする）か、しない（メインウィンドウでやる）かの判断を書き、当てはまる場合は並列性にも触れ、このレッスンの基準を使って1〜2文の理由を添えてください。
症状: リサーチのディスパッチを3回行ったあと、メインエージェントのコンテキスト使用量がウィンドウの上限に近づき、レッスン4で組み込んだコンパクションロジックが早すぎるタイミングで発動させられます。メインエージェントのメッセージ配列を調べると、トークンの大部分がサブエージェントの生のツール戻り値であることがわかります。
根本原因を指摘し、1回のディスパッチがメインウィンドウにサマリーを1件だけ追加するようにコードを直してください。
const SUBAGENT_SYSTEM = `あなたはリサーチサブエージェントです。
タスクが完了したら、1500 トークン以内の結論を出力してください:
主要な発見、関係するファイルパス、メインエージェントへの推奨アクション。
読んだ生のテキストを繰り返さないでください。`;
async function runSubagent(client, task, maxTurns = 15) {
// 仕掛けはこの1行だけ: まっさらなメッセージ配列で、メインエージェントの履歴は一切ない
let messages = [{ role: "user", content: task }];
for (let turn = 0; turn < maxTurns; turn++) {
const response = await client.messages.create({
model: "claude-sonnet-5",
max_tokens: 4096,
system: SUBAGENT_SYSTEM, // サブエージェント専用のシステムプロンプト
tools: SEARCH_TOOLS, // 探索に必要なツールだけ
messages,
});
if (response.stop_reason === "end_turn") {
return textOf(response); // サブエージェントから出ていくのはこのテキストだけ
}
// ツールを実行し、結果を messages に追加する。すべてサブエージェントの内側に留まる
messages = await appendToolResults(messages, response);
}
return "リサーチはターン予算内に完了しなかった";
}
const DISPATCH_TOOL = {
name: "dispatch_research",
description:
"焦点を絞ったリサーチタスクをサブエージェントに渡し、その発見のサマリーを返す。" +
"大量の探索を必要とするが、結論は簡潔に述べられるタスクに使う。",
input_schema: {
type: "object",
properties: {
task: {
type: "string",
description: "自己完結したタスク記述。サブエージェントはこの会話の履歴を見ることができない",
},
},
required: ["task"],
},
};
async function handleDispatch(mainMessages, toolCall) {
const summary = await runSubagent(client, toolCall.input.task);
mainMessages.push({
role: "user",
content: [{
type: "tool_result",
tool_use_id: toolCall.id,
content: summary, // メインウィンドウが得るのはこの1件だけ
}],
});
}
async function runSubagent(client, task, maxTurns = 15) {
let messages = [{ role: "user", content: task }];
for (let turn = 0; turn < maxTurns; turn++) {
const response = await client.messages.create({
model: "claude-sonnet-5",
max_tokens: 4096,
system: SUBAGENT_SYSTEM,
tools: SEARCH_TOOLS,
messages,
});
if (response.stop_reason === "end_turn") {
// 最後の返信も足して、履歴全体を返す
return [
...messages,
{ role: "assistant", content: textOf(response) },
];
}
messages = await appendToolResults(messages, response);
}
return messages;
}
async function handleDispatch(mainMessages, toolCall) {
const subHistory = await runSubagent(client, toolCall.input.task);
mainMessages.push({
role: "user",
content: [{
type: "tool_result",
tool_use_id: toolCall.id,
// 履歴全体をテキストに変換してメインウィンドウに押し込む
content: renderAsText(subHistory),
}],
});
}