【AI】Claude Agent SDKでサブエージェントを実装する方法

2026年8月26日

当ページのリンクには広告が含まれています。

この記事で解決できる悩み

Claude Agent SDKでサブエージェントを実装する方法は？

いずみ

こんな悩みを解決できる記事を書きました！

僕は現役フリーランスエンジニア（歴10年）で、資格は13個保有しています。

「Claude Agent SDKでサブエージェントを実装する方法を知りたい」とお考えではありませんか？

Claude Agent SDKでエージェントアプリを構築していると、1つのエージェントに全てのタスクを任せてしまい、処理が長くなったりコンテキストが肥大化したりすることがあります。

サブエージェントを使えば、タスクごとに専門化したエージェントへ処理を委譲し、コンテキストを分離しながら並列実行することが可能です。

いずみ

実装自体はシンプルなので、サクッと解説します。

ということで、本記事ではClaude Agent SDKでサブエージェントを実装する方法を解説します。

スクロールできます

【当サイト】おすすめフリーランスエージェント3選
エージェント	評価	ポイント	公式サイト
レバテックフリーランス	5.0	業界最大級のエージェント。高単価案件が豊富。	公式
Midworks	4.8	満足度調査で 3年連続3冠を達成。	公式
ITプロパートナーズ	4.6	週2〜3向けの案件が豊富。	公式

執筆者／監修者

フリーランスエンジニア（保有資格13個、企業と直接契約）
ブログ・アフィリエイト歴7年（2018年〜）
ブランドせどりで月利50万円⇨脱サラ
投資（仮想通貨・FX）歴7年（2018年〜）
X（旧Twitter）フォロワー約1,900人
運営者情報はこちら

いずみです

よく読まれている記事はこちら！

【AI】Claude Agent SDKでサブエージェントを実装する方法

早速ですが、Claude Agent SDKでサブエージェントを定義して呼び出す方法を解説します。

サブエージェントとは

サブエージェントとは、メインのエージェントが呼び出す独立したエージェントインスタンスです。

サブエージェントは会話履歴を持たない新しいコンテキストで起動するため、大量のファイルを読み込んでも、メインの会話には内容が蓄積されません。

メインのエージェントには、サブエージェントが返した最終メッセージだけが渡されます。

複数のサブエージェントは同時に実行できるため、独立したタスクであれば並列処理によって全体の完了時間を短縮できます。

サブエージェントごとに専門的なシステムプロンプトや使用できるツールを設定できるため、役割を絞った運用が可能です。

いずみ

役割ごとにエージェントを分けると、無駄なツール実行も減らせて安心感がありますね。

環境準備

まずは、Claude Agent SDKを使う環境を準備します。

STEP

claude-agent-sdkをインストールする

Python 3.10以上の環境で、pipからインストールします。

pip install claude-agent-sdk

STEP

APIキーを環境変数に設定する

Claude ConsoleでAPIキーを発行し、環境変数ANTHROPIC_API_KEYに設定します。

export ANTHROPIC_API_KEY="your_api_key"

プログラムでサブエージェントを定義する（コード付き）

Claude Agent SDKでは、query関数のagentsパラメータにAgentDefinitionを渡すことで、サブエージェントをコード上で定義できます。

STEP

AgentDefinitionでサブエージェントを定義する

descriptionには使用タイミング、promptには役割を書きます。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

agents = {
    "code-reviewer": AgentDefinition(
        description="コードの品質・セキュリティレビューを行う専門エージェント",
        prompt="""あなたはセキュリティとパフォーマンスに強いコードレビュアーです。
脆弱性の指摘、パフォーマンス上の懸念、コーディング規約からの逸脱を確認してください。""",
        tools=["Read", "Grep", "Glob"],
        model="sonnet",
    ),
}

STEP

query呼び出し時にagentsパラメータへ渡す

allowed_toolsにAgentを含めることで、サブエージェント呼び出しが自動承認されます。

async def main():
    async for message in query(
        prompt="code-reviewerエージェントで認証まわりのコードをレビューして",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Agent"],
            agents=agents,
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

promptの中でエージェント名を明示すると、狙い通りのサブエージェントを確実に呼び出せます。

いずみ

descriptionの書き方が曖昧だと、Claudeがサブエージェントを呼ばずに自分で処理してしまうことがあるので、具体的に書くのがコツです。

サブエージェントが使えるツールを制限する

AgentDefinitionのtoolsフィールドを省略すると、サブエージェントは利用可能な全ツールを引き継ぎます。

toolsフィールドにリストを渡すと、対象のサブエージェントが使えるツールを限定できます。

例えば、ファイルを閲覧するだけのレビュー用エージェントには、Read・Grep・Globだけを渡し、EditやBashは渡さないようにします。

リストに含まれていないツールは、サブエージェントのセッションに存在しないものとして扱われ、権限エラーも発生しません。

いずみ

誤操作でファイルを書き換えられたくないレビュー用エージェントには、読み取り系のツールだけを渡すようにしています。

複数のサブエージェントを並列実行する

agentsパラメータには、複数のAgentDefinitionを同時に登録できます。

agents = {
    "code-reviewer": AgentDefinition(
        description="コード品質・セキュリティレビュー用エージェント",
        prompt="あなたはコードレビュアーです。品質とセキュリティを確認してください。",
        tools=["Read", "Grep", "Glob"],
    ),
    "test-runner": AgentDefinition(
        description="テストを実行し結果を分析する専門エージェント",
        prompt="あなたはテスト実行の専門家です。テストを実行し、失敗の原因を分析してください。",
        tools=["Bash", "Read", "Grep"],
    ),
}

code-reviewerとtest-runnerのように独立したタスクを担うエージェントを複数登録しておくと、Claudeが状況に応じて並列に呼び出してくれます。

逐次実行では合計時間がかかっていた処理も、並列実行によって最も時間のかかるサブエージェント1つ分の時間まで短縮できます。

いずみ

コードレビューとテスト実行を並列で走らせると、待ち時間がかなり減った実感があります。

スクロールできます

【当サイト】おすすめフリーランスエージェント3選
エージェント	評価	ポイント	公式サイト
レバテックフリーランス	5.0	業界最大級のエージェント。高単価案件が豊富。	公式
Midworks	4.8	満足度調査で 3年連続3冠を達成。	公式
ITプロパートナーズ	4.6	週2〜3向けの案件が豊富。	公式

【厳選】フリーランスエンジニアにおすすめなエージェント3選

フリーランスエンジニアになるにはエージェントから案件をもらう必要があります。

僕が実際に利用しているおすすめエージェントを紹介しますね。

いずみ

エージェントは必ず複数登録してください。

担当者によっては「全然案件紹介してくれない…」みたいなこともあるので…

僕は実際に5つのエージェントを使い回していますよ。

フリーランスを始めるなら「レバテックフリーランス」

案件数	マージン率	単価
約88,000件	非公開	高
初心者	福利厚生	申し込み
		無料

Good Point

業界最大級の案件数。
業界トップクラスの高単価報酬、低マージン（平均年収862万円）。
案件参画中のフォローの充実。

※詳細は「【業界最大手】レバテックフリーランスとは？メリットや利用手順を解説！」を参照。

レバテックフリーランス は業界最大手のフリーランスエージェントです。

とにかく案件数が多いので、とりあえず登録しておけば間違いないエージェントです！

いずみ

僕もはじめてフリーランスの案件を貰ったのはレバテックフリーランス です。

保有している案件数が多いので、業務経験がなくても何かしらの案件は紹介してもらえますよ（僕はJavaの経験3年でも案件を貰えました）。

詳細はコチラ

公式サイトを詳しく見る

手厚い保障を重視したいなら「Midworks 」

案件数	マージン率	単価
約10,000件	非公開	中
初心者	福利厚生	申し込み
		無料

Good Point

手厚い保障で正社員並みの安心感。
還元率60％超え＆単価公開でクリアな契約。
給与保障制度（審査あり）。

Midworks は手厚い保障が特徴のフリーランスエージェントです。

フリーランスを目指しているけど不安な方や保障を重視したい方におすすめです。

いずみ

僕も何度か案件を紹介してもらいました。

自分のスキルに合った案件を紹介してもらえましたし、電話のやり取りも非常に丁寧でした。

詳細はコチラ

公式サイトを詳しく見る

週2〜3日の案件探しなら「ITプロパートナーズ」

案件数	マージン率	単価
約5,000件	非公開	高
初心者	福利厚生	申し込み
経験者向け		無料

Good Point

IT案件に特化したフリーランスエージェント。
週2〜3日の案件が豊富。
リモート案件が多く、直エンドなので単価も高い。

※詳細は「【週2・3案件】ITプロパートナーズとは？メリットや利用手順を解説！」を参照。

ITプロパートナーズ はIT案件に特化したフリーランスエージェントです。

週2〜3日から参画できる案件が豊富なので、起業したい人にもおすすめです。

いずみ

週2〜3日の案件はある程度スキルがないと紹介してもらえない印象です。

とはいえ、週5の案件ももちろんありますし、僕が利用した時は迅速・丁寧に対応していただきました！

詳細はコチラ

公式サイトを詳しく見る

よくある質問

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

引き継ぎません。

サブエージェントに渡されるのは、Agentツール呼び出し時のprompt文字列のみです。

必要なファイルパスやエラーメッセージ、判断の経緯があれば、prompt文字列の中に明示的に含める必要があります。

サブエージェントは同時にいくつまで実行できますか？

デフォルトでは、最大20個のサブエージェントを同時に実行できます。

環境変数CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSを設定すると、同時実行数の上限を変更できます。

上限に達すると、新しいサブエージェントの起動は実行中の数が減るまで拒否されます。

サブエージェントごとに使用するモデルを変更できますか？

変更できます。

AgentDefinitionのmodelフィールドに、opusやsonnetといったモデル名を指定します。

高精度な判断が必要なレビュー用エージェントだけ上位モデルを割り当てる、といった使い分けが可能です。

まとめ

今回は、Claude Agent SDKでサブエージェントを実装する方法について解説しました。

以下が本記事のまとめになります。

まとめ

AgentDefinitionのdescription・prompt・toolsを設定するだけでサブエージェントを定義できる。
query呼び出し時にallowed_toolsへAgentを含めると、サブエージェント呼び出しが自動承認される。
toolsフィールドで権限を絞り込むことで、安全に役割を分担できる。
独立したタスクを複数のサブエージェントに任せると、並列実行によって処理時間を短縮できる。

まとめ

いずみ

最後までお読みいただき、ありがとうございました！

スクロールできます

【当サイト】おすすめフリーランスエージェント3選
エージェント	評価	ポイント	公式サイト
レバテックフリーランス	5.0	業界最大級のエージェント。高単価案件が豊富。	公式
Midworks	4.8	満足度調査で 3年連続3冠を達成。	公式
ITプロパートナーズ	4.6	週2〜3向けの案件が豊富。	公式