Agent SDK のサブエージェント：agents オプションで作業を分担させる

Claude Agent SDK のサブエージェントは、メインのエージェントが特定の作業を任せるために起動する、別のエージェントインスタンスです。調べものや検査を切り出して文脈を汚さない、独立した作業を並行して進める、専門の指示やツール制限を付けて任せる、といった使い方ができます。

この記事では、公式ドキュメント「Subagents in the SDK」に沿って、query() の agents オプションでサブエージェントを定義する方法、AgentDefinition の各項目、サブエージェントに渡る情報、呼び出しの検出と再開、ツール制限と深さ・同時実行数・費用の上限までを整理します。対話型の Claude Code でサブエージェントを使う方法は「Claude Code のサブエージェント活用法」を参照してください。

サブエージェントを使う利点

SDK でサブエージェントを作る方法は3つあります。

• プログラムで定義：query() のオプション agents に渡す（SDK アプリではこれが推奨）
• ファイルで定義：.claude/agents/ ディレクトリに Markdown ファイルとして置く
• 組み込みの general-purpose：何も定義しなくても、Claude は Agent ツール経由で組み込みの general-purpose サブエージェントを呼べる

公式は、サブエージェントに任せる利点として次の4つを挙げています。

agents オプションと AgentDefinition

プログラムで定義する場合は、agents に「名前 → AgentDefinition」のオブジェクトを渡します。Claude はサブエージェントを Agent ツールで呼び出すので、事前承認したいときは allowedTools に "Agent" を入れます。次は読み取り専用のレビュー担当とテスト実行担当を定義する TypeScript の例です（公式の例の prompt を短くしたもの）。

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review the authentication module for security issues",
  options: {
    allowedTools: ["Read", "Grep", "Glob", "Agent"],
    agents: {
      "code-reviewer": {
        description: "Expert code review specialist. Use for quality, security, and maintainability reviews.",
        prompt: "You are a code review specialist with expertise in security, performance, and best practices.",
        tools: ["Read", "Grep", "Glob"],
        model: "sonnet"
      },
      "test-runner": {
        description: "Runs and analyzes test suites. Use for test execution and coverage analysis.",
        prompt: "You are a test execution specialist. Run tests and provide clear analysis of results.",
        tools: ["Bash", "Read", "Grep"]
      }
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Python では ClaudeAgentOptions(agents={"code-reviewer": AgentDefinition(...)}) の形で同じ内容を渡します。AgentDefinition の主な項目は次のとおりです（必須は description と prompt のみ）。

ほかに memory・initialPrompt・omitClaudeMd（TypeScript のみ）もあります。Python でも disallowedTools や mcpServers のような複数語の項目は、snake_case ではなく camelCase のまま書きます。同じ名前のエージェントがファイルにもある場合は、agents で渡した定義が優先されます。

サブエージェントは既定でバックグラウンド実行です。Agent ツールの呼び出しで run_in_background が省略されるとバックグラウンドで起動し、結果を待つ必要があるときは Claude が run_in_background: false を付けます。

定義は実行時に組み立てられるので、条件に応じて中身を変えることもできます。公式の例では、厳しさのレベルを引数に取るファクトリ関数を作り、厳格なレビューのときだけ model: "opus" を使う AgentDefinition を返しています。

サブエージェントが受け取るもの

サブエージェント（フォークでないもの）の文脈は親の会話を含まずに始まります。親から渡せるのは Agent ツールの prompt 文字列だけなので、必要なファイルパス・エラーメッセージ・決定事項はその prompt に直接書きます。

拡張思考の設定はメインのセッションから引き継ぎます。親が受け取るのはサブエージェントの最終報告ですが、親はそれを要約して返すことがあります。サブエージェントの出力をそのまま利用者に見せたい場合は、メインの query() に渡す prompt か systemPrompt にその旨を書いておきます。

呼び出し方と検出・再開

自動の呼び出しと明示的な呼び出し

Claude はタスクの内容と各サブエージェントの description を照らし合わせて、任せるかどうかを自分で判断します。確実に特定のエージェントを使わせたいときは、prompt の中で名前を出します。

"Use the code-reviewer agent to check the authentication module"

Claude がサブエージェントに任せずに自分で処理してしまう場合も、この「名前を出す」方法と、いつ使うかがはっきり分かる description を書くことが公式の対処です。

呼び出しを検出する

サブエージェントの起動は、name が "Agent" の tool_use ブロックとして現れます。ただし system:init のツール一覧では "Task" と表示され、Claude Code v2.1.63 より前は tool_use でも "Task" だったため、両方の名前に一致させるのが安全です。サブエージェント内から来たメッセージには parent_tool_use_id が入ります（メインのセッションのメッセージでは null）。

for await (const message of query({ prompt, options })) {
  const msg = message as any;
  for (const block of msg.message?.content ?? []) {
    if (block.type === "tool_use" && (block.name === "Task" || block.name === "Agent")) {
      console.log(`Subagent invoked: ${block.input.subagent_type}`);
    }
  }
  if (msg.parent_tool_use_id) {
    console.log("  (running inside subagent)");
  }
}

TypeScript ではコンテンツは message.message.content にあります（Python は message.content）。TypeScript SDK v0.3.292 以降では、サブエージェントのメッセージに agent_id も付きます。

サブエージェントを再開する

再開したサブエージェントは、それまでのツール呼び出しや結果を含む会話履歴をすべて保ったまま続きから動きます。手順は次の3つです。

1. 最初の query() のメッセージから session_id を控える
2. Agent ツールの結果テキストに含まれる agentId: <id> を取り出す
3. 2回目の query() に resume: sessionId を渡し、prompt にエージェント ID を含める（例：Resume agent ${agentId} and list the top 3 most complex endpoints）

query() は毎回新しいセッションを始めるため、同じセッションを再開しないとサブエージェントの記録にアクセスできません。カスタムエージェントの場合は、2回とも同じ agents 定義を渡します。組み込みの Explore と Plan は1回限りで agentId を返さないので、再開したいときはカスタムエージェントか general-purpose を使います。

ツール制限と上限の設定

tools でできることを絞る

tools を省略するとサブエージェントが使えるツールをすべて持ち、列挙するとそのツールだけになります。外したツールはセッションに存在しないので、許可の確認やエラーも出ずに、Claude はそれ以外の手段で作業します。公式は典型的な組み合わせを次のように示しています。

深さ・同時実行数・費用に上限を付ける

サブエージェントはさらに自分のサブエージェントを起動できるため、1つの prompt がエージェントの木に広がることがあります。各サブエージェントの API リクエストはクエリ全体の total_cost_usd に加算されます。公式は次の3つの上限を用意しています（TypeScript SDK v0.3.219・Python SDK v0.2.127 以降）。

環境変数は env オプションで渡します。TypeScript SDK の env はサブプロセスの環境を置き換えるので、PATH などを残すために ...process.env を展開します（Python は継承した環境にマージされます）。

options: {
  allowedTools: ["Read", "Grep", "Glob", "Agent"],
  env: {
    ...process.env,
    CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH: "1",
    CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS: "5",
  },
  maxBudgetUsd: 5,
}

数十〜数百のエージェントを協調させる規模になったら、オーケストレーションをスクリプトに移す Workflow ツール（TypeScript Agent SDK v0.3.149 以降）が公式の示す次の選択肢です。詳しくは「Claude Code のダイナミックワークフローで多数のサブエージェントを動かす」も参考にしてください。

本ページは Subagents in the SDK の内容に基づく非公式の日本語解説で、AgentDefinition の項目と parent_tool_use_id は Agent SDK reference - TypeScript と照合しています（確認日 2026-10-14）。オプション名・フィールド名は公式表記のまま記載しています。最新の仕様は公式ドキュメントを確認してください。