【2026年最新】Claude Agent SDK サブエージェント実装ガイド

「複数ファイルのコードレビューを1つのエージェントに全部やらせたら、途中でコンテキストが溢れて肝心の指摘が薄くなった」——Claude Agent SDKでエージェントを組んでいると、こうした壁に一度はぶつかります。

原因の多くは、1つの会話スレッドにあらゆる調査・実行・検証を詰め込みすぎていることです。ファイルを大量に読み、コマンドを何度も叩き、その結果が全部同じコンテキストウィンドウに積み上がっていく。そうなると、本当に重要な指示や過去の判断がノイズに埋もれてしまいます。

この記事では、Claude Agent SDKの「サブエージェント」機能を、公式ドキュメントの仕様に基づいて実装コード付きで整理します。定義方法・並列実行・モデルの使い分け・階層生成の制限・よくある失敗パターンまで、実際にコードを書いて試す前に押さえておきたいポイントをまとめました。

そもそも「サブエージェント」とは何か — 3つの作り方

サブエージェントとは、メインのエージェントが特定のサブタスクを任せるために生成する、独立したエージェントインスタンスです。公式ドキュメントでは、サブエージェントを作る方法として次の3つが挙げられています。

作り方	定義場所	向いている用途
プログラム定義（推奨）	query()のagentsパラメータ	SDKアプリケーション全般。実行時に動的な条件でエージェント設定を変えたい場合
ファイルシステム定義	.claude/agents/配下のMarkdownファイル	チームで共有・再利用したいエージェント定義をリポジトリに残したい場合
組み込みgeneral-purpose	定義不要（Claudeが自動で呼び出す）	調査・探索タスクを、専用エージェントを作らずに委任したい場合

同じ名前のエージェントが両方に存在する場合は、プログラム定義がファイルシステム定義より優先されます。この記事では、SDKアプリケーション向けに推奨されているプログラム定義を中心に解説します。

セットアップと最小構成（5分で動かす）

まずはSDK本体をインストールします。Python版は3.10以上が必要です。

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python（3.10以上が必要）
pip install claude-agent-sdk

# 認証（Anthropic Consoleで発行したAPIキー）
export ANTHROPIC_API_KEY=your-api-key

最小構成の例として、コードレビュー専門のサブエージェントを1つ定義してみます。ポイントは、サブエージェントを呼び出すAgentツールをallowed_toolsに含めておくことです。含めないと呼び出しのたびに許可確認が挟まります。

# 動作環境: Python 3.10+, claude-agent-sdk
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
    reviewer = AgentDefinition(
        description="Code review specialist",
        prompt="Review code for security issues",
        tools=["Read", "Grep", "Glob"],
        model="sonnet",
    )
    async for message in query(
        prompt="Review the auth module",
        options=ClaudeAgentOptions(
            # Agentを含めておくと、サブエージェント呼び出しの許可確認が省略される
            allowed_tools=["Read", "Grep", "Glob", "Agent"],
            agents={"code-reviewer": reviewer},
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

Claudeは各サブエージェントのdescriptionを見て、いつ呼び出すべきかを自動判断します。狙って呼びたい場合は「Use the code-reviewer agent to check the authentication module」のようにプロンプト内で名指しすれば、自動判定を経由せず確実に指定のサブエージェントが起動します。

単発のサブエージェント呼び出しだけでなく、AIエージェントをどう本番のワークフローに組み込むかという全体設計は、AIエージェント実装ロードマップ｜RAG・実行・運用の必須技術【2026】で体系的にまとめています。

まず試したい実践パターン3選

1. 並列実行で複数のレビューを同時に走らせる

公式ドキュメントは「独立したサブタスクは、全てを合計した時間ではなく最も遅い1つの時間で完了する」と説明しています。style-checker・security-scanner・test-coverageのような独立したチェックは、逐次実行ではなく並列化するメリットが大きい典型例です。

# 動作環境: Python 3.10+, claude-agent-sdk
style_checker = AgentDefinition(
    description="Style checker",
    prompt="Check formatting",
    tools=["Read", "Grep"],
)
security_scanner = AgentDefinition(
    description="Security scanner",
    prompt="Find vulnerabilities",
    tools=["Read", "Grep", "Glob"],
)
test_coverage = AgentDefinition(
    description="Test runner",
    prompt="Run tests, report coverage",
    tools=["Bash", "Read"],
)

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Grep", "Glob", "Bash", "Agent"],
    agents={
        "style-checker": style_checker,
        "security-scanner": security_scanner,
        "test-coverage": test_coverage,
    },
)
# プロンプト側で「3つを並行して実行して」と明示すると、
# Claudeは3つのサブエージェントを同時に起動しやすくなる

ポイント：サブエージェントはそれぞれ独立した会話として起動されるため、途中経過や中間ファイルの内容は親のコンテキストに積み上がりません。親が受け取るのは最終メッセージだけです。

2. タスクの重要度でモデルを動的に切り替える

AgentDefinitionのmodelフィールドには、'sonnet'や'opus'、'haiku'、'fable'、'inherit'といったエイリアス、またはフルのモデルIDを指定できます。省略した場合はメインエージェントと同じモデルが使われます。実行時に条件分岐して、重要なレビューだけ上位モデルを使う設計も可能です。

# 動作環境: Python 3.10+, claude-agent-sdk
def create_security_agent(level: str) -> AgentDefinition:
    strict = level == "strict"
    mode = "strict" if strict else "balanced"
    return AgentDefinition(
        description="Security reviewer",
        prompt=f"Run a {mode} security review",
        tools=["Read", "Grep", "Glob"],
        # 重要度が高いレビューだけ上位モデルを割り当てる
        model="opus" if strict else "sonnet",
    )

# query()呼び出しの直前に生成するので、リクエストごとに設定を変えられる
agents = {"security-reviewer": create_security_agent("strict")}

ポイント：全サブエージェントを一律で上位モデルにするとコストが膨らみます。「本番デプロイ前のレビューだけopus、日常的な巡回チェックはsonnet」のように使い分けると、精度とコストのバランスを取りやすくなります。

3. ツール権限を絞った読み取り専用サブエージェントを作る

サブエージェントのtoolsフィールドを省略すると親の全ツールを継承しますが、明示的に指定すればアクセスできる範囲を制限できます。ドキュメント編集や誤操作のリスクを避けたい調査系タスクでは、読み取り専用に絞るのが安全です。

# 動作環境: Python 3.10+, claude-agent-sdk
doc_reviewer = AgentDefinition(
    description="Read-only doc reviewer",
    prompt="Flag inaccuracies, do not edit",
    # EditやWriteを含めないことで、誤って書き換えるリスクを排除する
    tools=["Read", "Grep"],
)

なぜ重要か：ツール制限はプロンプトでの「編集しないでください」という指示より確実です。権限そのものを絞ることで、モデルの解釈ミスによる意図しない書き込みを構造的に防げます。

AgentDefinitionの主要設定項目

プログラム定義で使える設定項目は、公式リファレンス時点で以下の通りです。descriptionとprompt以外はすべて省略可能です。

フィールド	型	必須	説明
description	string	○	このエージェントをいつ使うべきかの自然言語説明。自動委任の判断材料になる
prompt	string	○	エージェントの役割・振る舞いを定義するシステムプロンプト
tools	string[]	–	許可するツール名の配列。省略すると全ツールを継承
disallowedTools	string[]	–	除外するツール名。MCPサーバー単位の指定（mcp__server等）も可能
model	string	–	‘opus’/’sonnet’/’haiku’/’fable’/’inherit’などのエイリアス、またはフルモデルID
skills	string[]	–	起動時にプリロードするスキル名のリスト
memory	‘user’|’project’|’local’	–	このエージェントが参照するメモリソース
mcpServers	配列	–	このエージェントで使えるMCPサーバー
maxTurns	number	–	エージェントが停止するまでの最大ターン数
background	boolean	–	呼び出し時に非ブロッキングのバックグラウンドタスクとして実行するか
effort	‘low’〜’max’	–	このエージェントの推論負荷レベル
permissionMode	PermissionMode	–	このエージェント内でのツール実行時の権限モード

Python SDKではdisallowedToolsやmcpServersのような複数語のフィールド名も、ワイヤーフォーマットに合わせてキャメルケースのまま使う点に注意してください（Pythonのスネークケース慣習には従いません）。

階層的なサブエージェント生成とバージョンごとの変遷

サブエージェントがさらにサブエージェントを生成する「入れ子構造」は、Claude Codeのバージョンアップで段階的に整備されてきました。公式ドキュメントに明記されている変更点を時系列で整理します。

バージョン	変更内容
v2.1.63	サブエージェント呼び出しのツール名がTaskからAgentに変更（互換性のため両方を検出するのが安全）
v2.1.172	サブエージェントが自分自身のサブエージェントを生成できるようになった。メインエージェントから数えて5階層下のサブエージェントは、それ以上サブエージェントを生成できない
v2.1.198	サブエージェントは既定でバックグラウンド実行になった。結果が必要な場合はClaude側がrun_in_background: falseを設定する
v2.1.199	レート制限や過負荷などのAPIエラーでサブエージェントが途中終了した場合、それまでのテキスト出力を「未完了」の注記付きで返すようになった
v2.1.200	テキスト出力が一切ないままAPIエラーで終了した場合は、明示的なエラーメッセージで失敗を返すようになった

入れ子を深くしすぎると、どのサブエージェントが何を担当しているかの見通しが悪くなります。特定のサブエージェントにさらなる委任をさせたくない場合は、そのエージェントのtoolsからAgentを外すか、disallowedToolsに加えることで生成そのものを止められます。

サブエージェントを使うべきかの判断基準

Anthropicが2026年4月7日に公開したガイドでは、サブエージェントへの委任を検討すべき具体的なシグナルが示されています。「10以上のファイル探索、または3つ以上の独立した作業が必要な場合」は委任を検討する強いシグナルだとしています。逆に、順序依存の強い作業や同一ファイルへの並列編集、サブエージェント間で頻繁な調整が必要なタスクは、サブエージェント向きではないとも明記されています。

設計の考え方自体は、複数エージェントを協調させるオーケストレーター・ワーカー型のパターンとも共通しています。役割分担の設計パターンはマルチエージェント設計パターン完全ガイド【2026年最新】で扱っているので、あわせて参照してください。

大規模になったらWorkflowツールへ

サブエージェントは「1ターンあたり数個の委任」を想定した仕組みです。数十から数百のエージェントを協調させるような規模になると、会話ターンの中でオーケストレーションし続けるのは非効率になります。公式ドキュメントは、その規模では会話コンテキストの外でスクリプトとして実行されるWorkflowツールへの移行を推奨しています。TypeScript版Agent SDKではv0.3.149以降で利用可能です。

【要注意】よくある失敗パターンと回避策

失敗1：Agentツールの許可漏れでサブエージェントが呼ばれない

❌ allowed_toolsにAgentを含めずに実行し、動かないと思い込む
⭕ allowed_toolsにAgentを明示的に含める。含めない場合、呼び出しはcanUseToolコールバックに回されるか、dontAskモードでは拒否される

なぜ重要か：サブエージェントはAgentツール経由で呼び出される仕組みのため、この許可がないと自動委任そのものが発生しません。

失敗2：新規に作った.claude/agents/ディレクトリが検知されない

❌ ディレクトリを追加してすぐ動かないと判断してデバッグに時間をかける
⭕ ファイル監視はセッション開始時に存在していたディレクトリだけを対象にするため、新規ディレクトリの最初の1ファイルはセッションの再起動が必要と理解しておく

失敗3：Windowsで長いプロンプトのサブエージェントが失敗する

❌ プロンプトを長文化してすべての指示を1つのサブエージェントに詰め込む
⭕ Windows環境ではコマンドライン長の上限（8191文字）に達すると失敗するため、プロンプトは簡潔にするか、長い指示はファイルシステム定義のエージェントに移す

失敗4：プログラム定義とファイルシステム定義の優先順位を誤解する

❌ 同名のエージェントを両方に定義してしまい、意図しない設定が使われる
⭕ 同じ名前で両方に定義した場合、プログラム定義（query()のagentsパラメータ）が常にファイルシステム定義より優先されることを踏まえて設計する

よくある質問

Q1. Claude Agent SDKとClaude Codeは何が違うのですか？

どちらも同じエージェントループとツール実行の仕組みを使いますが、インターフェースが異なります。Claude Codeは対話的なCLI、Claude Agent SDKはPython/TypeScriptのライブラリとして自分のアプリケーションに組み込む用途です。公式ドキュメントは、対話開発にはCLI、CI/CDパイプラインや本番の自動化にはSDKを使い分けることを推奨しています。

Q2. サブエージェントは何階層まで入れ子にできますか？

Claude Code v2.1.172以降、サブエージェントは自分のサブエージェントを生成できますが、メインエージェントから数えて5階層下のサブエージェントはそれ以上生成できません。

Q3. PythonかTypeScriptのどちらか一方しか使えないのですか？

いいえ、両方に公式SDKが提供されています。Python版はpip install claude-agent-sdk（Python 3.10以上が必要）、TypeScript版はnpm install @anthropic-ai/claude-agent-sdkでインストールできます。

Q4. サブエージェントは親の会話履歴を引き継ぎますか？

いいえ。サブエージェントは自分のpromptとAgentツール呼び出し時のプロンプト文字列だけを受け取り、親の会話履歴やツール実行結果は引き継ぎません。サブエージェントに必要な情報は、呼び出し時のプロンプトに明示的に含める必要があります。

Q5. 数十〜数百のエージェントを動かす大規模なワークフローはどう組みますか？

その規模になると、ターンごとのサブエージェント委任ではなく、会話コンテキストの外でスクリプトとして実行されるWorkflowツールを使うのが公式の推奨です。

参考・出典

• Agent SDK overview — Anthropic Claude Code Docs（参照日: 2026-07-09）
• Subagents in the SDK — Anthropic Claude Code Docs（参照日: 2026-07-09）
• Building agents with the Claude Agent SDK — Anthropic（2025年9月29日公開、参照日: 2026-07-09）
• How and when to use subagents in Claude Code — Anthropic（2026年4月7日公開、参照日: 2026-07-09）

まとめ：今日から始める3つのアクション

1. 今日やること：pip install claude-agent-sdkまたはnpm install @anthropic-ai/claude-agent-sdkで、読み取り専用のサブエージェントを1つ定義して動かしてみる
2. 今週中：現状1つのエージェントに詰め込んでいるタスクの中から、独立して並列化できる作業を洗い出し、専用サブエージェントに切り出す
3. 今月中：委任するタスクの重要度に応じてmodelを使い分け、コストと精度のバランスを見直す

あわせて読みたい:

• Claude Code Skills ガイド｜Skill自作7パターン+配布【2026】 — サブエージェントのskillsフィールドで使う自作スキルの作り方
• AIエージェントの並列ツール利用設計パターン完全ガイド — 並列化をサブエージェントより低レイヤーで設計したい場合

---

著者：佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー10万人超。100社以上の企業向けAI研修・導入支援。著書累計2.5万部突破。