Agent SDK のサブエージェント｜作り方と任せ方の線引き

Claude Agent SDK は、Claude Code と同じ仕組みの AI エージェントを自分のアプリの中で動かすための道具です。全体像は Claude Agent SDK とは で解説しました。

この記事では、公式ドキュメント「Subagents in the SDK」（2026年11月8日確認）にもとづいて、親の AI が作業を「別の AI」に切り出して任せる仕組み＝サブエージェント を、SDK で使う視点から整理します。Claude Code の画面で使うサブエージェントの話は Codex と Claude Code のサブエージェント にまとめています。

結論：調べものは「別の担当」に出して、要点だけ受け取る

サブエージェントは、親のエージェントが必要なときに立ち上げる 別の AI のインスタンス です。子は自分専用の会話の中で作業し、親に返ってくるのは最後のメッセージだけ です。

公式は、任せることで得られる良さを4つ挙げています。

サブエージェントを用意する3つの方法

結論から言うと、SDK のアプリでは「コードで定義する」方法が推奨 です。用意の仕方は次の3つです。

1. コードで定義する：query() の options にある agents に書く（この記事の中心）
2. ファイルで定義する：.claude/agents/ に Markdown ファイルとして置く
3. 最初から入っている汎用の子を使う：何も定義しなくても、Claude は general-purpose という子を Agent ツールでいつでも呼べる

同じ名前の子がコードとファイルの両方にある場合は、コードで定義した方が優先 されます。なお、汎用の子を使わせたくない場合は、環境変数 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 で外せます。その場合、種類を指定しない呼び出しはエラーになります。

Claude は子を Agent ツール で呼び出します。そのため、親の許可リストには Agent を入れておきます。

定義に書く項目

子の定義で必須なのは、「いつ使うか」の説明と、子への指示の2つだけ です。そのほかは必要に応じて足します。

公式の例では、読む道具だけを持ったコードの確認役 と、コマンドを動かせるテスト役 の2つを定義しています。役割ごとに道具をはっきり分けるのが基本の形です。

また、定義は実行のたびに組み立て直せます。たとえば「厳しく確認する日は性能の高いモデル、それ以外は軽いモデル」のように、条件によって子の中身を変える 使い方も公式に載っています。考える深さの調整は Claude Code のサブエージェントと effort も参考になります。

子に渡るもの・渡らないもの

いちばん誤解しやすいのがここです。子は親の会話を知りません。 親から子へ渡るのは、Agent ツールに渡す依頼文だけです。

そのため、ファイルの場所・エラーの文面・決めたことなど、子が必要な情報は依頼文に直接書く 必要があります。「さっきのあれ」は子には通じません。

例外は フォーク です。フォークは会話を空から始めるのではなく、それまでの会話をコピーして始める子です。

また、親は子の報告を受け取りますが、自分の返事の中で要約してしまうことがあります。子の報告をそのまま見せたい場合は、親への指示にそう書いておきます。

呼び出し方は「自動」「名指し」「フォーク」

ふだんは AI が説明を読んで自動で呼びます。 確実に使わせたいときは、依頼文の中で名前を出します。

• 自動：作業の内容と各子の description を見て、Claude が呼ぶかどうかを決める。説明は具体的に書く
• 名指し：「code-reviewer エージェントを使って確認して」のように名前を書くと、その子が直接呼ばれる
• フォーク：会話をコピーした子。新しい版では何も設定しなくても Claude が始められる。止めたいときは禁止ルールに Agent(fork) を入れる

待つか、裏で走らせるか

子は基本的に裏で動きます。 結果は後のターンで届きます。ただし、次の作業に子の報告が要るときは、Claude はその場で待ちます。

自分で決めたい場合は、依頼文で「テスト役を動かして、終わるまで待って」と頼むか、定義の background を true にして常に裏で動かします。

子が呼ばれたかを確かめる・続きから再開する

子が呼ばれたかどうかは、流れてくるメッセージで確かめられます。 道具の呼び出しの名前が Agent になっているものを探します。古い版では Task という名前だったので、公式は両方を見るよう勧めています。子の中から出たメッセージには、親の呼び出しを指す印（parent_tool_use_id）が付きます。

途中で止まった子は、最初からやり直さずに続きから再開 できます。手順は3つです。

1. 1回目の呼び出しで、セッションの ID を控える
2. Agent ツールの結果に入っている子の ID（agentId）を読み取る
3. 2回目の呼び出しで同じセッションを再開し、依頼文に子の ID を書く

このとき、2回とも同じ子の定義を渡します。なお、最初から入っている調査用・計画用の子は使い切りで、再開用の ID を返しません。再開したい場合は、自分で定義した子か汎用の子を使います。

増えすぎを止める：深さ・同時数・金額

業務で使ううえで、ここがいちばん大事です。子を何人呼ぶかは Claude が自分で決めます。 しかも子が子を呼べるので、1つの依頼が木のように広がることがあります。各子の利用料は、その呼び出し全体の金額に加算されます。

公式は、3つの上限で広がりを抑える方法を示しています。

公式の例では、孫は作らせない・同時は5つまで・見積もりが5ドルに届いたら止める という設定にしています。環境変数は options の env で渡します。TypeScript では env が環境変数を置き換えるので、元の環境変数も一緒に渡す点に注意します。

また、新しいモデルの Claude Opus 5 は、以前のモデルより子に任せがちだと公式は書いています。指示で控えめにさせることもできますが、指示はあくまで誘導なので、上限は別に設定しておく のが公式の考え方です。金額をどう読むかは Agent SDK の料金と使用量の確認 で解説しています。

数十〜数百の子を動かすような大きな仕事は、会話の外で台本として動かす Workflow ツールの出番だと公式は案内しています。

うまく任せてくれないとき

子に任せずに親が自分で片付けてしまう場合は、名指しと説明の見直し が効きます。

• 依頼文の中で子の名前を出す
• description に「どんな作業のときに使うか」を具体的に書く

ファイルで定義した子が読み込まれないときは、新しく作った agents フォルダ がよくある原因です。起動時に無かったフォルダは監視されないので、最初のファイルを置いたら作り直しが要ります。名前の重複や、設定部分の書き間違いも確認します。

仕事に入れるときの考え方

サブエージェントを業務に入れるときは、「読むだけの子」から始めて、道具と上限を先に決める のが安全です。

1. まず調べもの・確認だけをする子を作り、読む道具だけを渡す
2. 呼び出しの深さ・同時数・金額の上限を決めてから動かす
3. 子が返す報告の形（何を何行で）を指示に書いておき、親がまとめやすくする

子の報告を決まった形のデータで受け取りたい場合は、Agent SDK の構造化出力 と組み合わせると扱いやすくなります。複数の AI をどう分担させるかの全体像は Claude Code のマルチエージェント も参考にしてください。

まとめ

• サブエージェントは 作業を切り出して任せる別の AI。途中のやり取りは子の中に閉じ、親には最後の報告だけが返る
• SDK では agents に 説明・指示・道具・モデル を書いて定義する。子は親の会話を知らないので、必要な情報は依頼文に書く
• 業務では 深さ・同時数・金額の3つの上限 を必ず決め、読むだけの子から始める

出典

• Claude Code 公式ドキュメント「Subagents in the SDK」

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。