examlab .net 最も価値のある認定資格への最も効率的な道。
Support
このノートについて 約 27 分

サブエージェントの起動・コンテキスト受け渡し・スポーニング

5,400 語 · 約 27 分の読書 ·

CCA-F ドメイン1.3完全解説：Task ツールによるスポーニング・allowedTools の設定・AgentDefinition の構造・コンテキストの明示的受け渡し・fork_session のセマンティクス・並列サブエージェントのファンアウト・Multi-Agent Research と Developer Productivity シナリオの試験対策。

20問の模擬問題に挑戦 → 無料 · 登録不要 · CCA-F

サブエージェントの起動・コンテキスト受け渡し・スポーニングは、Claude Certified Architect — Foundations（CCA-F）試験の中で最もアーキテクチャ密度の高いタスクステートメントだ。タスク1.3はドメイン1（Agentic Architecture and Orchestration、配点比率27%——試験で最も重い）の中に位置し、受験者が Multi-Agent Research System シナリオと Developer Productivity with Claude シナリオを実際に設計できるかどうかを決定する。この二つのシナリオは、あるエージェントが別のエージェントをどう生成するか・どのコンテキストがその境界を越えるか・子エージェントがどのツールを引き継ぐか拒否されるかについて正しく推論できるかどうかに最も直接的に依存する。

本章では CCA-F が期待する深さでサブエージェントの起動・コンテキスト受け渡し・スポーニングを順に解説する。具体的なスポーニングメカニズムとしての Task ツール・サブエージェントを宣言する AgentDefinition の形状・子エージェントができることをスコープする allowedTools 許可リスト・サブエージェントがコーディネーターのコンテキストを自動的に引き継がないというハードルール・分岐探索のための fork_session セマンティクス・単一コーディネーターレスポンス内での並列 Task 呼び出し、そしてマルチエージェントシステムをデバッグ可能に保つ構造化メタデータ分離パターン。すべてのセクションは Anthropic の公式ドキュメントと試験が引く6つのシナリオクラスターに固定されている。末尾の平易な類比がすべてを結びつけ、実際の試験の120分・60問のプレッシャーの下での想起を助ける。

サブエージェントの起動とは何か？ 子エージェントをスポーニングする仕組み

サブエージェントの起動・コンテキスト受け渡し・スポーニングは三つの別々だが密接に結びついた責務を名指しする。起動は、実行中のエージェントが作業の一部を新しいエージェントインスタンスに引き渡すよう求める行為だ。コンテキスト受け渡しはその引き渡しにどの情報を添付するかを決める規律だ。スポーニングは子エージェントを独自の分離された会話履歴・独自のツール許可リスト・独自のループで作成するランタイムイベントだ。

Claude Agent SDK において、主要な起動インターフェースは Task ツールだ。コーディネーターエージェントが Task を呼び出すと、SDK はコーディネーターが提供したプロンプトでシードされ・特定の AgentDefinition（サブエージェントのシステムプロンプト・ツール許可リスト・オプションのモデルオーバーライドを宣言する）に紐付けられた全く新しいエージェントセッションをインスタンス化し、最終結果を生成するまで独自の独立したエージェントループを実行する。その結果はコーディネーターのループにおける Task 呼び出しの tool_result メッセージとして返される。

このサブエージェントの起動・コンテキスト受け渡し・スポーニングのモデルは単純なプロンプトチェーンとは根本的に異なる。コーディネーターはフォローアップのユーザーメッセージを連結して自身の会話を続けるのではない。子エージェントが所有する別のコンテキストウィンドウへ実行をフォークする。子エージェントが知っていることは、Task プロンプトまたは事前登録された AgentDefinition システムプロンプトを通じて明示的に伝えられたことだけだ。

Task ツールは Claude Agent SDK と Claude Code に組み込まれたスポーニングメカニズムで、実行中のコーディネーターエージェントの中から新しいサブエージェントインスタンスを作成する。Task ツールを呼び出すと subagent_type（登録された AgentDefinition を指す）・description（サブエージェントが行うべき作業）・prompt（完全な命令ペイロード）が提供される。SDK はサブエージェントのエージェントループを分離されたコンテキスト内で完了まで実行し、サブエージェントの最終回答をコーディネーターへの tool_result メッセージとして返す。Task ツールはスポーニングが可能であるためにコーディネーターの allowedTools リストに現れなければならない。 出典: https://docs.anthropic.com/en/docs/claude-code/sdk/subagents

アーキテクトがこの語彙を必要とする理由

コミュニティの試験報告と CCA-F 試験ガイドの両方が、サブエージェントのコンテキスト分離をトップ3の誤解の一つとしてフラグしている。コンテキストが言語ランタイムのスタックフレームが変数を引き継ぐような形で階層を下に流れると仮定する受験者は、壊れたマルチエージェントシステムを設計し、「サブエージェントは起動時に何を知っているか？」を問う設問で誤りを選ぶ。答えは：AgentDefinition システムプロンプトが宣言したことと、Task ツールの prompt パラメーターが明示的に渡したことだけだ。それ以上は何もない。

主要なスポーニングメカニズムとしての Task ツール

Task ツールはコーディネーター＝サブエージェントアーキテクチャを図から実行時に変える具体的な動詞だ。CCA-F 受験者は Task ツールをスポーニングメカニズムとして認識しなければならない——汎用のユーティリティツールでも・カスタム MCP ツールでもなく——そしてそのロールの意味を認識しなければならない。

Task ツール呼び出しの形状

コーディネーターからの標準的な Task ツール呼び出しは三つの主要パラメーターを持つ。

  • subagent_type — 登録された AgentDefinition に解決される文字列識別子。Claude Code エージェントチームで見られる一般的な値は researcher・critic・planner・coder、または .claude/agents/ 以下に登録されたカスタム名。
  • description — ログ・トレース・UI サーフェスで使われる短い人間が読めるラベル。サブエージェント自身は消費しない。
  • prompt — サブエージェントが冒頭のユーザーメッセージとして受け取る完全な命令ペイロード。サブエージェントが現在のタスクについて知る必要があるすべてのことがここかサブエージェントのシステムプロンプトに存在しなければならない。

内部では、SDK はこれら三つの入力を取り、一致する AgentDefinition でシードされた新しいセッションを構築し、最初のユーザーメッセージとして prompt を渡し、子のエージェントループを実行する。子が stop_reason: end_turn に達すると、その最終メッセージの内容がキャプチャされ、コーディネーターのメッセージ履歴内の Task 呼び出しの tool_result として返される。

Task は明示的に許可されなければならない

Task ツールはそれ自体が SDK 提供のツールであり、Read・Write・Edit・Bash・Grep・カスタム MCP ツールと同じ allowedTools の平面に存在する。AgentDefinition の allowedTools リストに "Task" が含まれていない場合、そのエージェントはサブエージェントをまったくスポーニングできない。これは頻繁な試験ワナだ。受験者はコーディネーターが本質的にサブエージェントのスポーニング能力を持つと仮定するが、実際にはスポーニング能力は他のすべてのツールと同じ明示的な許可リストメカニズムを通じて付与される。

コーディネーターがサブエージェントをスポーニングできるのは、自身の allowedTools リストに Task ツールが含まれている場合のみだ。コーディネーターの allowedTools から "Task" を省略すると、コーディネーターは Read・Write・Grep などを呼び出せるが子エージェントに作業を委任できない単一エージェントシステムに格下げされる。これは設計によるものだ——スポーニング能力を他のすべての破壊的または拡張的なアクションと同じ権限の平面に置いておく。 出典: https://docs.anthropic.com/en/docs/claude-code/sdk/subagents

Task ツール vs MCP ツール vs 組み込みファイルツール

三つの異なるツールカテゴリーが単一のエージェントの allowedTools に一緒に現れることがあり、CCA-F はそれらを分離する能力をテストする。

  • Task ツール — サブエージェントをスポーニングする。Agent SDK ランタイムが提供する。ユーザーが作成するものではない。
  • 組み込みツール — Read・Write・Edit・Bash・Grep・Glob。Claude Code が提供する。ローカルワークスペースで動作する。
  • MCP ツール — Model Context Protocol サーバーを通じて公開されるユーザー登録のツール。サーバーがラップする外部機能（GitHub・Slack・データベースなど）で動作する。

Task ツールはカスタム MCP ツールではなく・MCP サーバーで再実装することはできず・名前を変更することもできない。「Task をユーザーが書くツールとして」混同する答えの選択肢は誤りだ。

AgentDefinition — サブエージェントの宣言的な形状

Task ツールがスポーニングできるすべてのサブエージェントは AgentDefinition として宣言されなければならない。これが CCA-F がテストする二番目のコアアーティファクトだ。試験は AgentDefinition フィールドの認識と、それらのフィールドがサブエージェントの振る舞いをどう形成するかについての推論能力を期待する。

AgentDefinition のフィールド

Agent SDK における AgentDefinition または Claude Code サブエージェントファイル（.claude/agents/<name>.md）は以下を持つ。

  • description — サブエージェントが何のためにあるかの自然言語の説明。Claude はこの説明を使って、複数のサブエージェントが登録されているとき、特定のサブエージェントタイプに Task 呼び出しをルーティングするかどうかを決定する。description はツールの説明のように扱う。ルーティングシグナルだ。
  • system prompt — サブエージェントの完全な行動憲章。声・制約・好ましい出力形状・禁止されたアクション、そして個々の Task 呼び出しが渡す内容に関係なくサブエージェントが必要とするドメイン知識を宣言する。
  • tools（allowedTools）— サブエージェントが呼び出せるツールの明示的な許可リスト。親が Bash を持っていても子の AgentDefinition が Bash をリストしていなければ子は Bash を呼び出せない。デフォルトで制限的だ。
  • model — オプションのモデルオーバーライド。安価なサブエージェントタスク（大量要約）はコーディネーターがより大きいモデルで動く間、より小さいモデルで動かせるかもしれない。省略した場合、サブエージェントはセッションのデフォルトモデルを引き継ぐ。

ルーティングに description が重要な理由

コーディネーターが複数の登録されたサブエージェントタイプ（researcher・critic・summarizer）を持つとき、コーディネーター Claude は自然言語の説明に基づいて Task ツールに渡す subagent_type を決定する。曖昧または重複する説明は曖昧なルーティングを生む。曖昧なツール説明が曖昧なツール選択を生むのと同じだ。これは AgentDefinition の作成における最も一般的な誤りだ。description: "helpful agent" ではなく description: "arXiv から学術論文を読んで統合する。ページレベルの引用を含む構造化された書誌要約を返す。" と書くこと。

AgentDefinition は Claude Agent SDK におけるサブエージェントの宣言的な仕様だ。四つの主要フィールドをまとめる。親 Claude が Task 呼び出しをルーティングするために使う description・サブエージェントの永続的な行動憲章を設定する system prompt・サブエージェントが呼び出せるツールをスコープする allowedTools 許可リスト・オプションの model オーバーライド。AgentDefinition は静的な設定だ——会話状態を運ばない。各 Task 呼び出しは対応する AgentDefinition でシードされた新しいセッションインスタンスを生成する。 出典: https://docs.anthropic.com/en/docs/claude-code/sub-agents

AgentDefinition の保存場所

Claude Code では AgentDefinition は .claude/agents/<name>.md（プロジェクトスコープ）または ~/.claude/agents/<name>.md（ユーザースコープ）以下の markdown ファイルとして保存される。Agent SDK（Python または TypeScript）ではセッションコンストラクターにオブジェクトとしてプログラム的に渡される。どちらの形式でも同じランタイム動作が生まれる。

allowedTools — サブエージェントが実際にできることをスコープする

AgentDefinition の allowedTools フィールドはサブエージェントの起動・コンテキスト受け渡し・スポーニングにおいて試験で最も関連性の高い単一パラメーターだ。そのセマンティクスを理解することで誤った答えのクラス全体を防げる。

allowedTools は厳密な許可リスト

リストにあるものは呼び出せる。リストにないものは呼び出せない——親の能力の暗黙の引き継ぎはない。allowedTools: ["Read", "Grep"] のサブエージェントは親コーディネーターが Write を持っていても Write を呼び出せない。これは設計によるものだ。サブエージェントの専門化はツールの境界で強制され、プロンプトの境界に委ねられない。

allowedTools は制限するが拡張しない

二番目の重要なルール。AgentDefinition はセッションの全体的な設定が許可するよりも多くの権限をサブエージェントに付与できない。セッションが Bash を禁止するパーミッションプロファイルで起動された場合、Bash を allowedTools にリストするサブエージェントはやはり Bash を実行できない。許可リストは既に許可されたサーフェスを制限する。セッションのセキュリティエンベロープをオーバーライドしない。

一般的な専門化パターン

試験シナリオは通常、専門化に報酬を与える。

  • researcher サブエージェント：["Read", "Grep", "Glob", "WebSearch"] — 探索と読み取りはできるが変更はできない。
  • critic サブエージェント：[]（ツールなし）— 純粋な推論、ファイルシステムやシェルには触れられない。
  • coder サブエージェント：["Read", "Edit", "Write", "Bash", "Grep"] — ソースを変更できるが、さらにサブエージェントをスポーニングすることは許可されないかもしれない（Task なし）。
  • コーディネーター：["Task", "Read"] — その仕事はオーケストレーションであり実行ではないため Task と読み取り専用アクセスを持つ。

サブエージェントの起動・コンテキスト受け渡し・スポーニングのための allowedTools チートシート：

  • allowedTools は厳密な許可リスト——不在 = 拒否。
  • サブエージェントは親の allowedTools を自動的に引き継がない。
  • スポーニングが機能するためにコーディネーターの allowedTools に "Task" がなければならない。
  • allowedTools はセッションの全体的な権限エンベロープを超えて制限のみできる。拡張はできない。
  • 専門化されたサブエージェントは親の完全なリストではなく、最小限のタスクスコープのツールセットを持つべきだ。

引っかけの手がかり：「サブエージェントはコーディネーターのツールを引き継ぐ」を示唆するあらゆる答えは誤りだ。サブエージェントが呼び出すすべてのツールは明示的でなければならない。 出典: https://docs.anthropic.com/en/docs/claude-code/sub-agents

コンテキスト分離 — 受験者が引っかかるルール

サブエージェントの起動・コンテキスト受け渡し・スポーニングに関して CCA-F 試験が叩き続ける唯一のルールがある。サブエージェントは分離されたコンテキストで動作し、コーディネーターの会話履歴を自動的に引き継がない。

分離されたコンテキストが実際に意味すること

Task ツールがサブエージェントをスポーニングすると、SDK はメッセージ履歴として以下のみを含む新しいセッションを作成する。

  1. サブエージェントのシステムプロンプト（AgentDefinition から）。
  2. コーディネーターが Task ツール呼び出しで最初のユーザーメッセージとして提供した prompt 文字列。

これが開始状態のすべてだ。コーディネーターの以前のメッセージ・以前の tool_result エントリ・以前の思考ブロック・以前のユーザー命令——どれもサブエージェントには見えない。コーディネーターが Task プロンプトにその情報をパッケージしない限り、サブエージェントはコーディネーターが何をしたか・どのドキュメントを読み込んだか・どのツールを呼び出したかを知らない。

この設計の理由

コンテキスト分離が存在するのは三つの理由からだ。

  • コンテキストウィンドウの衛生 — コーディネーターのコンテキストウィンドウはすでに50Kトークンの深さかもしれない。それをすべてのサブエージェントにコピーするとサブエージェントの利用可能なトークンと API 費用が無駄になる。
  • 専門化の忠実度 — 集中したサブエージェントのプロンプトは希薄な汎用会話ダンプより高いパフォーマンスを発揮する。
  • セキュリティと監査可能性 — 機密の上流データを見たことがないサブエージェントは、ツール呼び出しや最終出力を通じて誤ってそれを漏洩することができない。

明示的な受け渡しの義務

コンテキストは自動的に流れないため、サブエージェントに何かを知ってほしいコーディネーターはその何かを Task ツールの prompt パラメーターで明示的に渡さなければならない。これが試験概要の「明示的に受け渡さなければならない」ルールだ。次のように見える。

Task(
  subagent_type="summarizer",
  description="サポートチケットのスレッドを要約する",
  prompt="""
以下の顧客サポートチケットのスレッドを
3文のインシデント説明に要約してください。スレッド：
<thread>
  {full_ticket_thread_here}
</thread>
3文の要約のみを返してください。前置きは不要です。
"""
)

コーディネーターはプロンプト内にスレッドをパッケージする責任がある。コーディネーターがサブエージェントが何を要約すべきかを「すでに知っている」ことに依存すれば、サブエージェントはハルシネーションするか拒否するだろう。

「コンテキストはエージェント階層を下に流れる」は CCA-F 試験では誤りだ。

従来のソフトウェアの背景を持つ受験者は、子エージェントが子関数呼び出しが字句スコープを引き継ぐように、コンテキストを引き継ぐと仮定することが多い。そうではない。サブエージェントは AgentDefinition システムプロンプトと Task ツールの prompt パラメーターのみでシードされた完全に分離されたコンテキストウィンドウで動作する。

シナリオが「コーディネーターが顧客記録を読み込んでから要約サブエージェントをスポーニングした——要約者は何を見るか？」と尋ねた場合、正しい答えは「コーディネーターが Task プロンプトに含めたもの」であり、「顧客記録、なぜならサブエージェントはコーディネーターのコンテキストを引き継ぐから」ではない。この誤りだけで Multi-Agent Research シナリオで2〜3問を失いかねない。 出典: https://docs.anthropic.com/en/docs/claude-code/sdk/subagents

コンテキスト受け渡し戦略 — 完全・要約・構造化

コーディネーターは明示的にコンテキストをパッケージしなければならないので、問いはどのように受け渡すかだ。CCA-F は三つのアーキタイプを認識する。アーキテクトはデータの量とサブエージェントの情報ニーズに基づいて一つを選ぶ。

完全な履歴のパス

コーディネーターは関連する会話またはツール出力を Task プロンプトに逐語的に連結する。シンプルで情報の損失がないが、トークンコストが高い。サブエージェントがコーディネーターがすでに見たのと同じ素材について深い推論を行う場合に便利だ。

要約されたパス

コーディネーターは以前のコンテキストをスポーニング前に短いブリーフィング——数文または箇条書き——に圧縮する。より安価だが損失がある。サブエージェントはコーディネーターが省略した詳細を回復できない。サブエージェントのタスクが狭く抽象だけを必要とする場合に適切だ。

構造化ペイロードのパス

コーディネーターはコンテキストを構造化データ——JSON・XML タグ・markdown でフェンスされたブロック——としてパッケージし、メタデータを自然言語のタスク命令からきれいに分離する。これは本番グレードのパターンであり、CCA-F がアーキテクトに Multi-Agent Research System シナリオで推奨することを期待するものだ。

構造化ペイロードは次のように見える。

<task>
  <goal>事実の不一致を特定する</goal>
  <context>
    <source_1 id="arxiv:2301.04567">
      {paper_1_summary}
    </source_1>
    <source_2 id="arxiv:2302.11234">
      {paper_2_summary}
    </source_2>
  </context>
  <instruction>
    {claim, source, conflicts_with} オブジェクトの JSON 配列を返してください。
  </instruction>
</task>

XML タグの分離はサブエージェントにクリーンなメンタルモデルを与える。目標・次にコンテキスト（ソースの出所が保持されている）・次に出力命令。サブエージェントの出力をコーディネーターで監査することも容易になる。

マルチソースリサーチをサブエージェントに渡すことについての CCA-F の問いに答えるとき、「コーディネーターの全会話を渡す」（無駄で出所が混乱する）と「1行の要約を渡す」（情報損失がある）の両方より構造化ペイロードの答えを優先せよ。構造化ペイロードは出所を保持し・メタデータを命令から分離し・Multi-Agent Research および構造化データ抽出シナリオに推奨されるイディオムだ。 出典: https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags

fork_session — 幹を失わずに分岐した探索

fork_session メカニズムはサブエージェントの起動・コンテキスト受け渡し・スポーニングの三番目の CCA-F の柱だ。Task とは異なる問題を解決する。「境界のある作業の一部を行う子をスポーニングする」ではなく「現在のセッションを保持したまま代替パスを探索する」だ。

フォーキングが与えるもの

フォークは現在のセッションの状態——メッセージ履歴・ツール呼び出し履歴・SDK が永続化するすべてのもの——のコピーを独自のセッション ID を持つ新しいセッションとして作成する。フォーク内で取られたアクションは幹に影響しない。実験を実行し・ミスをロールバックし・仮説上のブランチを探索できる。

fork_session vs Task

この二つのメカニズムは別物であり、CCA-F はその区別をテストする。

  • Task は AgentDefinition とプロンプトでのみシードされた新鮮なコンテキスト分離されたサブエージェントを作成する。境界のある作業単位の委任に使う。
  • fork_session は既存のセッションの完全な状態を新しいブランチに複製する。分岐した探索・A/Bツール戦略のテスト・ロールバック安全な実験に使う。

シナリオが「リサーチャーエージェントが元のコンテキストを失わずに2つの異なるデータベースクエリを試みる方法」を問う場合、答えは fork_session だ——二つのフォークをスポーニングし、各フォークでクエリを実行し、結果を比較し、負けフォークを破棄する。

fork_session は、アクティブなセッションをフォーキング時点の親セッションのメッセージ履歴を引き継ぐ独立して実行中の新しいセッションに分岐する Agent SDK メカニズムだ。Task ツール（AgentDefinition と明示的なプロンプトでのみシードされたコンテキスト分離されたサブエージェントを作成する）とは異なり、フォーキングは幹が当時あった同じ地点から推論を続けられるよう完全な会話状態を保持する。フォークは将来の状態を共有しない——フォーク内のアクションは幹を変更しない。一般的なユースケース：分岐した仮説テスト・A/B ツール戦略探索・ロールバック安全な実験。 出典: https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-sessions

フォーキングはセッションエンベロープを超えて権限を複製したり付与したりしない

頻繁にテストされる微妙な点。フォーキングはメッセージ履歴を引き継ぐが、フォークに追加のツール権限を魔法のように付与したりセッションのセキュリティプロファイルを昇格させたりしない。幹が Bash を呼び出せなかったなら、フォークもできない。フォークはメモリ操作であり、権限操作ではない。

並列 Task 呼び出し — 単一コーディネーターレスポンス内でのファンアウト

Agent SDK はコーディネーター Claude が単一のアシスタントレスポンスに複数の tool_use ブロックを出力することを許可する。複数の Task 呼び出しを含む。SDK はそれらのサブエージェントを並列で実行し、すべてが完了したら一緒に tool_result メッセージを返す。

並列スポーニングが重要な理由

Multi-Agent Research シナリオでは、同じ質問に対して三つの観点が必要なコーディネーターが三つの専門サブエージェントを順番ではなく同時にスポーニングできる。

  • researcher_arxiv — arXiv を検索して所見を返す。
  • researcher_github — GitHub を検索して所見を返す。
  • researcher_web — ウェブを検索して所見を返す。

三つすべてが並列で実行され、コーディネーターは三つの tool_result メッセージを一度に見て結合された証拠を統合する。逐次スポーニングはレイテンシを3倍にして下流のすべてのステップを遅らせる。

ファンアウトしてはいけない場合

並列性はサブタスクが依存関係にある場合——サブエージェントBがサブエージェントAの出力を入力として必要とする場合——誤りだ。依存するサブタスクをファンアウトすると失敗（BにAのデータがない）または無駄な作業（Bが古い前提で進む）のどちらかになる。依存するサブタスクは逐次チェーンにすべきで、独立したサブタスクはファンアウトすべきだ。

「コーディネーターが関連するトピックについて三つの独立したリサーチストリームを必要とする」と描写する CCA-F シナリオ問いは、並列ファンアウトの答えを期待する。単一のコーディネーターレスポンスで複数の Task tool_use ブロックを出力し、SDK に並列で実行させ、返された tool_result を集約する。このセットアップでの逐次スポーニングは正しいが劣った答えだ。試験は通常、並列バージョンを最善としてマークする。 出典: https://docs.anthropic.com/en/docs/claude-code/sdk/subagents

スポーニングの深さの上限と再帰的なサブエージェント

AgentDefinition に allowedTools として "Task" が含まれていれば、サブエージェント自身がさらにサブエージェントをスポーニングできる。これはエージェントのツリーを生成する。深さの上限がなければ、バグがあったり暴走した計画エージェントが予算が爆発するまで再帰し続ける可能性がある。

実際の深さの上限

CCA-F は特定の数値の深さ上限をテストしないが、以下の認識はテストする。

  • 深さは実際には中間的な AgentDefinition が allowedTools に Task を含むかどうかによって制限される。
  • 一般的な衛生管理：最外部のコーディネーターだけが Task を持つ。葉の専門家は持たない。
  • ツリーの形状はランタイムの事故ではなく設計上の決定だ。

暴走するツリーの防止

最も安全なデフォルトは浅い階層だ：ルートに一つのコーディネーター、専門葉の一層、それ以上の再帰なし。より深い階層が本当に必要な場合、各中間層の allowedTools は明示的に Task を持ち、その AgentDefinition システムプロンプトは予算を強制すべきだ（「最大2つの子しかスポーニングできない」）。

同期 vs 非同期の起動

コーディネーターの観点から、Task 呼び出しはコーディネーター自身のループ内では同期だ。コーディネーターは tool_use を発行し・tool_result を待ち・再開する。SDK はサブエージェントを返す前に完了まで実行する。Task ツールレイヤーで公開される「fire and forget」プリミティブはない。

並列呼び出しがしないこと

単一のアシスタントレスポンス内の並列 Task 呼び出しはたしかに互いに並列で実行されるが、コーディネーターはすべてが完了するまで待ってから続行する。Task ツールインターフェースを通じて公開されるコールバック・イベントストリーム・プロミスオブジェクトはない。CCA-F は受験者が「Task 呼び出しを発行して続行する」と誤って提案するシナリオをテストする——正しい答えは、コーディネーターのループは発行したすべての Task の tool_result で常にブロックするということだ。

レイテンシ重視のシナリオへの意味

エンドユーザーが待機中のカスタマーサポート解決エージェントシナリオでは、アーキテクトはスポーニングの深さとファンアウト幅を慎重に考慮しなければならない。それぞれ8秒かかる三つの並列サブエージェントは24秒ではなく8秒（最も遅いもの）コーディネーターをブロックする。しかし8秒のサブエージェントの逐次チェーンは24秒ブロックする。ファンアウトがレイテンシのツールだ。

コーディネーターループでの戻り値の処理

サブエージェントが stop_reason: end_turn でループを終了すると、その最終アシスタントメッセージのコンテンツが元の Task 呼び出しの tool_result ボディになる。コーディネーター Claude は次のターンの入力の一部としてその tool_result を読む。

コーディネーターが実際に見るもの

コーディネーターが見るのは：

  • コーディネーター自身が発行した tool_use ブロック。
  • サブエージェントの最終テキストをコンテンツとして持つ tool_result ブロック。

コーディネーターはサブエージェントの中間的な tool_use と tool_result メッセージ・思考ブロック・ステップバイステップの推論を見ない——最終出力だけだ。これが適切に設計されたサブエージェントが鮮明で構造化された最終出力を生成する理由だ。下流のコーディネーターが必要とするすべてのことが最後のメッセージになければならない。

出力の形状付けパターン

サブエージェントの最終出力を構造化する二つの一般的なパターン：

  • 自由形式の要約 — コーディネーターが定性的な所見を推論する探索的タスク用。
  • 構造化された JSON または XML ブロック — コーディネーターがサブエージェントの JSON を解析して次のステップのフィールドを流す機械消費される出力用。これは構造化データ抽出シナリオときれいに対になる。

権限の引き継ぎ vs 制限 — まとめ

権限の糸を一つのメンタルモデルにまとめる。

  • 親セッション権限エンベロープ — 外側の境界。内部のものはこれを超えられない。
  • コーディネーター allowedTools — コーディネーターをエンベロープのサブセットに制限する。スポーニングのために Task を含まなければならない。
  • サブエージェント AgentDefinition allowedTools — サブエージェントをそれ自身のサブセットに制限する。エンベロープによって制限される（コーディネーターのリストによってではない）。サブエージェント自身がスポーニングを許可されているなら Task を含まなければならない。

各層は制限だ。どれも拡張ではない。試験はシナリオレベルでこれをテストする。「コーディネーターは Bash を持つが、リサーチャーサブエージェントは Bash をリストしていない——リサーチャーは Bash を呼び出せるか？」答え：いいえ。

やさしい解説: サブエージェントの起動・コンテキスト受け渡し・スポーニング

抽象的なアイデアは物理的なシステムに固定すると携帯可能になる。三つの類比がサブエージェントの起動・コンテキスト受け渡し・スポーニングの全体像を覆う。

類比1：委任するマネージャーと新入社員

プロジェクトマネージャーが大きな部門横断タスクを持っている。すべての作業を自分でできない。代わりにブリーフィング——目標・コンテキスト・制約・期待される出力フォーマットを説明する自己完結型のドキュメント——を作成し、まさにこの種の作業のために採用されたスペシャリストの契約社員に手渡す。契約社員はそのブリーフィングだけを持って会議室に入る。マネージャーの朝の計画会議に出ていなかった・マネージャーのメールスレッドを読んでいなかった・顧客電話を聞いていなかった。ブリーフィングが不完全なら、契約社員は推測するか聞き返すかのどちらかだ。

これがまさにサブエージェントの起動・コンテキスト受け渡し・スポーニングの仕組みだ。コーディネーター Claude がマネージャーだ。AgentDefinition が契約社員の職務説明書（専門とすること・持参するツール）だ。Task ツールがブリーフィングを手渡す行為だ。prompt パラメーターがブリーフィングの内容だ。サブエージェントはブリーフィングと自身の専門化だけを持って入る——それ以上は何もない。コーディネーターが顧客のチケットテキストをブリーフィングに入れ忘れたなら、要約サブエージェントは見たことのないものを要約できない。

この類比はすべてのコアタームをマッピングする。

  • コーディネーター = 委任するマネージャー。
  • AgentDefinition = 契約社員の役割説明とライセンスを持つツールキット。
  • Task ツール呼び出し = ブリーフィングを手渡す行為。
  • prompt パラメーター = ブリーフィングの内容。
  • allowedTools = 契約社員の許可されたツール（溶接ライセンスを持参していなければ溶接は不可）。
  • 分離されたコンテキスト = 契約社員はあなたの以前の会議に出ていなかった。

類比2：準備されたカンペを持つ持ち込み可試験

持ち込み可試験を受ける学生を考える。カンペ一枚だけ持ち込める。試験中の学生の知識は、持参したカンペと、入室前からすでに知っていたこと（訓練・授業内容）から成る。部屋の外に座っている試験官はすべての講義の詳細なノートを持っている——しかしそのノートは試験中の学生には見えない。

サブエージェントが学生だ。カンペが Task プロンプトだ。学生の既存知識が AgentDefinition システムプロンプトだ。試験官が学生には見えない豊富なコンテキストを持つコーディネーターだ。試験官が学生に何かを知ってほしいなら、学生が試験室に入る前にカンペにそれを書かなければならない。試験が始まったら扉は閉まる。学生は追加コンテキストを得るために外に連絡できない。

この類比は明示的なコンテキスト受け渡しが交渉不可能な理由と、要約または構造化された受け渡しがなぜトークンコストと読みやすさをトレードオフするかを固定する。カンペには限られたスペースがある。何を書くかが重要だ。

類比3：分離された仕込みステーションを持つ料理旅団

繁忙なレストランのヘッドシェフがパスを仕切る。注文が入り、ヘッドシェフが全チケットを読んで誰が何を作るかを決める。ヘッドシェフはソースをソースコックに・タンパク質をグリルコックに・ガルニチュールをガルドマンジェに委任する。各スペシャリストは自分のツールを持つ自分の仕込みステーションに立つ。ソースコックは泡立て器とパンを持つ・グリルコックはトングとライブフレームを持つ・ガルドマンジェはピンセットと冷えたボウルを持つ。ソースコックはグリルに届かない。グリルコックは冷えたハーブに届かない。エクスペダイティングラインのヘッドシェフは全チケットとクリアボードマーカーを持つ——そのツールはコーディネーションであり直接の調理ではない。

ヘッドシェフが「ソースを皿に盛る」と委任するとき、ソースコックは正確な命令（「オランデーズ・2オンス・温かいプレート」）を受け取るが、完全な夕食予約メモ・サーバーのVIPテーブルについての会話・ワインペアリングの決定は受け取らない。各スペシャリストは必要なものだけを持ち、それ以上は持たない。

これがトップダウンのサブエージェントの起動・コンテキスト受け渡し・スポーニングだ。

  • ヘッドシェフ = Task ツールを持つコーディネーター。
  • 仕込みステーション = サブエージェントのランタイムインスタンス。
  • 各コックのツールラック = AgentDefinition ごとの allowedTools。
  • 委任された命令 = Task プロンプト。
  • パスに返された完成した料理 = コーディネーターに返された tool_result。
  • 旅団全体へのファンアウト = 単一コーディネーターレスポンスでの並列 Task 呼び出し。
  • 二つの異なるソースのリダクションを試すために一つのステーションをフォーキングする = 分岐した探索のための fork_session。

試験当日にどの類比を使うか

  • サブエージェントがコーディネーターの知っていることを知らない理由についての問い → 持ち込み可試験の類比。
  • 誰がどのツールを使えるかについての問い → 料理旅団の類比。
  • 委任の契約とプロンプトに何が属するかについての問い → 委任するマネージャーの類比。

Multi-Agent Research System シナリオのマッピング

Multi-Agent Research System シナリオは CCA-F 試験でサブエージェントの起動・コンテキスト受け渡し・スポーニングに最も適合する。典型的な試験の設定：

「チームが arXiv・GitHub・ウェブ用の三つの専門リサーチャーにコーディネーターエージェントが作業を割り振るリサーチシステムを構築する。リサーチャーは並列で作業し・互いの中間的な所見を見ることなく・構造化された引用を返さなければならない。」

正しいアーキテクチャは以下を使う。

  • 三つの AgentDefinition（ソースごとに一つ）。それぞれ引用フォーマットを強制するシステムプロンプトと狭いツール許可リストを持つ。
  • "Task" を allowedTools に持ち、最小限の他のツールを持つコーディネーター AgentDefinition。
  • 単一のコーディネーターレスポンスで並列に発行された Task 呼び出し。それぞれ研究上の質問と期待される引用スキーマを特定する構造化 XML ペイロードを持つ。
  • コーディネーターでの tool_result 集約。次に三つの返された JSON ブロックにわたって統合する。
  • コーディネーターが一つにコミットする前に二つの代替的な統合戦略を探索したい場合、オプションで fork_session。

このシナリオの誤った答えは通常以下を行う。

  • 三つのリサーチャーをすべて一つのサブエージェントに統合する（並列性を失い・専門化を混同する）。
  • コンテキストの引き継ぎを明示的な構造化ペイロードの代わりに頼りにする（サブエージェントはハルシネーションする）。
  • すべてのサブエージェントに "Task" ツールを与える（暴走した再帰を招く）。
  • Task が適切な場合に fork_session を使う（フォークは履歴を引き継ぐ——独立したリサーチストリームには無駄）。

Developer Productivity with Claude シナリオのマッピング

Developer Productivity with Claude シナリオはサブエージェントの起動・コンテキスト受け渡し・スポーニングを Claude Code の組み込みファイルツールの上に重ねる。典型的な試験の設定：

「エンジニアが Claude Code にプルリクエストを三つの専門パスで検討させたい：型安全パス・テストカバレッジパス・セキュリティパス。それぞれ独自のツール許可リストを持つべきだ。エンジニアはできる限り並列で三つのパスを実行させたい。」

正しいアーキテクチャ：

  • .claude/agents/ 以下にサブエージェント markdown ファイルとして三つの AgentDefinition を登録する：type-check-reviewer・test-coverage-reviewer・security-reviewer。
  • それぞれ狭い allowedTools セットを持つ：型チェックとセキュリティには Read と Grep のみ、test-coverage には Bash（スコープ付き）も加えてテストランナーを呼び出せるようにする。
  • トップレベルの Claude Code セッションがコーディネーターとして機能し、allowedTools に Task を持つ。
  • コーディネーターが単一のアシスタントターンで三つの Task tool_use によって三つのレビュアーを並列でスポーニングする。
  • 各レビュアーが構造化された所見ブロックを返す。コーディネーターが統合して一つのまとまったレビューとして提示する。

このシナリオは AgentDefinition がファイルにバックアップできること・並列 Task ファンアウトが正しいレイテンシの選択肢であること・サブエージェントごとの最小 allowedTools がセキュリティ機能であり制限ではないことを認識する受験者に報酬を与える。

試験頻出ワナ — サブエージェントの起動・コンテキスト受け渡し・スポーニング

サブエージェントの起動・コンテキスト受け渡し・スポーニングに関する CCA-F 問いで五つのワナが繰り返し現れる。各パターンを記憶すること。

ワナ1：Task ツールをカスタムツールとして扱う

答えの選択肢が「MCP でカスタム Task ツールを書く」と説明するかもしれない。誤り。Task ツールは Agent SDK 組み込みであり、ユーザーが実装するものではない。Task をユーザー定義ツールとして作成することを示唆するあらゆる答えを拒否すること。

ワナ2：コンテキストが自動的に流れる

最も多く罰せられる誤解。サブエージェントはシステムプロンプトと Task プロンプトを除いて空のメッセージ履歴で始まる。「サブエージェントはコーディネーターの会話にアクセスできる」を示唆するあらゆる答えは、コーディネーターがプロンプトでその会話を明示的に渡した場合を除いて誤りだ。

ワナ3：allowedTools の引き継ぎ

受験者はサブエージェントがコーディネーターのツールリストを引き継ぐと仮定する。そうではない。AgentDefinition の allowedTools が決定的なスタンドアロンの許可リストだ。ツールを省略すれば呼び出せない。

ワナ4：セッションエンベロープを超えた権限付与としての allowedTools

allowedTools は既に許可されたサーフェスのみを制限できる。セキュリティプロファイルで Bash が無効化されたセッションで、サブエージェント定義に Bash をリストしても Bash は有効にならない。制限、決して拡張ではない。

ワナ5：Task と fork_session の混同

Task は新鮮なコンテキスト分離されたサブエージェントをスポーニングする。fork_session は現在のセッションの履歴を新しいブランチに複製する。目標が「完全な以前のコンテキストを保持しながら代替ブランチで推論を続ける」場合は fork_session が必要。目標が「境界のある作業の単位をスペシャリストに委任する」場合は Task が必要。誤ったメカニズムを選ぶと問いを失う。

サブエージェントの起動・コンテキスト受け渡し・スポーニングで最も攻撃的な CCA-F のワナは、単一の問いでワナ2・3・5を組み合わせる。

シナリオのテンプレート：「コーディネーターエージェントが40ページの顧客記録を読み込んで、連絡先の詳細を抽出するサブエージェントをスポーニングする。サブエージェントは allowedTools に Read と Grep を持つ。以下のうち正しいものはどれか？」

一般的に提示される誤った答え：

  • （A）コーディネーターがすでに読み込んでいるので、サブエージェントは顧客記録を読めるだろう。——誤り（コンテキスト分離）。
  • （B）コーディネーターの Write ツールを引き継ぐので、サブエージェントは Write を呼び出せる。——誤り（引き継ぎなし）。
  • （C）fork_session がここではより良いメカニズムだろう。——誤り（フォークは履歴を複製する。サブエージェントが必要なのは対象ペイロードだけのときは無駄）。

正しい答えは：コーディネーターが顧客記録を Task プロンプトに明示的に含める必要があり（またはサブエージェントが Read できるファイルパスを指定する）、サブエージェントは Read と Grep だけを使える。それ以上は何もない。 出典: https://docs.anthropic.com/en/docs/claude-code/sdk/subagents

練習アンカー — タスク1.3のシナリオ問いテンプレート

サブエージェントの起動・コンテキスト受け渡し・スポーニングに関する CCA-F の練習問いは五つの繰り返す形状にまとまる。

テンプレートA：スポーニングメカニズムの特定

「アーキテクトがコーディネーターエージェントに要約タスクをスペシャリストに委任させたい。コーディネーターはどの SDK 提供のツールを呼び出すべきか？」正答：Task。引っかけ：「'delegate' という名前のカスタム MCP ツール」・「Read」・「allowedTools リスト上の任意のツール」。

テンプレートB：allowedTools の推論

「サブエージェントの AgentDefinition は [Read, Grep] をリストする。コーディネーターの allowedTools は [Read, Grep, Bash, Task] をリストする。サブエージェントは Bash を実行できるか？」正答：いいえ。allowedTools はコーディネーターから引き継がない。

テンプレートC：コンテキスト分離の問い

「コーディネーターエージェントがマルチターンの顧客会話を処理している。Task で要約サブエージェントをスポーニングする。要約者は起動時に何を見るか？」正答：その AgentDefinition システムプロンプトとコーディネーターが Task プロンプトパラメーターで提供したもの。 引っかけ：「コーディネーターの完全なメッセージ履歴」・「コーディネーターの最後のアシスタントメッセージ」・「コーディネーターが Read で読んだすべてのもの」。

テンプレートD：Task vs fork_session の選択

「リサーチャーエージェントが現在の状態にロールバックできる能力を保持しながら二つのデータベースクエリ戦略を試したい。どのメカニズムを使うべきか？」正答：fork_session。引っかけ：Task（誤り、Task はブランチに完全な履歴を保持せず、目標は委任ではなく探索だ）。

テンプレートE：並列ファンアウトの認識

「コーディネーターが同じ質問を三つの独立したソースにわたってリサーチしてその所見を統合しなければならない。レイテンシを最小化するパターンはどれか？」正答：単一のコーディネーターレスポンスで複数の Task tool_use ブロックを発行して SDK がサブエージェントを並列で実行するようにする。 引っかけ：「三つの逐次 Task 呼び出しをチェーンする」（正しいが劣る。試験は通常並列を最善としてマークする）。

サブエージェントの起動・コンテキスト受け渡し・スポーニング よくある質問（FAQ）

Task ツールとは何で、なぜ Agent SDK に特有なのか？

Task ツールは Agent SDK の組み込みスポーニングメカニズムだ。subagent_type・description・prompt を指定して Task を呼び出すと、対応する登録された AgentDefinition に紐付いた新しいサブエージェントセッションが作成される。SDK はサブエージェントのエージェントループを分離されたコンテキストウィンドウで実行し、最終出力を tool_result としてコーディネーターのメッセージ履歴に戻す。Agent SDK に特有なのは、スポーニングはユーザーが作成したツールが忠実に実装できるランタイムプリミティブではないからだ——SDK は子セッションを配線し・AgentDefinition をシリアライズし・サブエージェントのループを実行し・結果を親のメッセージ履歴に戻すルーティングをしなければならない。

サブエージェントはコーディネーターの会話履歴を引き継ぐか？

いいえ。これは CCA-F で最も頻繁にテストされる誤解だ。サブエージェントは分離されたコンテキストで動作する。Task ツールがサブエージェントをスポーニングすると、サブエージェントの開始メッセージ履歴は AgentDefinition のシステムプロンプトとコーディネーターが Task 呼び出しに渡した prompt 文字列だけを含む。コーディネーターの以前のメッセージ・tool_result・推論はサブエージェントには見えない。コーディネーターがサブエージェントに何かを知らせたい場合、コーディネーターはその情報を Task prompt パラメーターの中に明示的にパッケージしなければならない。

AgentDefinition に何が含まれ、description がなぜ重要か？

AgentDefinition はサブエージェントの宣言的な仕様だ。description（親 Claude がどの subagent_type をスポーニングするかを選ぶルーティングシグナル）・system prompt（サブエージェントの行動憲章）・allowedTools リスト（サブエージェントのツール許可リスト）・オプションの model オーバーライドを持つ。コーディネーターが複数の登録されたサブエージェントタイプを持つとき、親 Claude は説明を読んでそれらを選択するため description が重要だ——曖昧または重複する説明は曖昧なルーティングを生む。description をツールの説明のように扱え。具体的で・動詞形で・スコープが制限されていること。

allowedTools はコーディネーターのツール権限とどう相互作用するか？

allowedTools は制限のみできる厳密な許可リストだ。サブエージェントは自身の AgentDefinition の allowedTools にリストされたツールのみを呼び出せる。サブエージェントはコーディネーターのツールを引き継がない。セッションの全体的な権限エンベロープを超えることもできない。セッションが Bash を無効化するプロファイルで起動された場合、サブエージェントの allowedTools に Bash をリストしても有効にならない。逆に、スポーニングが可能であるためにコーディネーターは自身の allowedTools に Task ツールを含まなければならない——スポーニング能力は他のすべてのツールと同じ許可リストメカニズムで管理される。

Task ツールの代わりに fork_session をいつ使うか？

スペシャリストサブエージェントに作業の境界のある部分を委任したいが、スペシャリストはコーディネーターの完全な履歴を見る必要がない場合は Task を使う。現在のセッションの正確な状態から代替ブランチに沿って推論を続けたい場合は fork_session を使う——仮説テスト・A/B ツール戦略探索・ロールバック安全な実験。フォークはフォーキング時点の完全なメッセージ履歴を引き継ぐ。Task サブエージェントは AgentDefinition でのみシードされた空の履歴から始まる。経験則：Task は委任、フォークは探索だ。

コーディネーターは複数のサブエージェントを並列でスポーニングできるか？

はい。Agent SDK はコーディネーターが単一のアシスタントレスポンスに複数の tool_use ブロックを——複数の Task 呼び出しを含む——発行することを許可する。SDK はそれらのサブエージェントを並列で実行し、各サブエージェントが完了したら一緒にすべての tool_result メッセージを返す。この並列ファンアウトは独立したサブタスク（例：異なるソースに対する三つのリサーチストリーム）に対する正しいパターンだ。レイテンシは最も遅いサブエージェントに制限され、サブエージェントの期間の合計ではない。並列ファンアウトはサブタスクが依存関係にある場合は誤りだ——下流のサブエージェントが上流の出力を消費できるよう、それらを逐次チェーンにすること。

サブエージェント自身がさらにサブエージェントをスポーニングできるか？

はい、その AgentDefinition の allowedTools に "Task" が含まれていれば。これはマルチ層のツリーを生成する。実際には CCA-F はシャロー（浅い）階層を報酬とする：ルートに Task を持つ一つのコーディネーター、Task を持たない一層の専門葉。より深いツリーは可能だが、中間層がスポーンループに入った場合の再帰リスク・デバッグの複雑さ・予算爆発をもたらす。設計時はデフォルトでシャローにする。深さは明示的に正当化すること。

参考資料

関連 ExamLab 章：コーディネーター＝サブエージェントパターンによるマルチエージェントオーケストレーション、自律タスク実行のための Agentic Loops、ツール呼び出しインターセプションのための Agent SDK Hooks、セッション状態・再開・フォーキング。

公式ソース

その他の CCA-F トピック