agents パラメータを使用して SDK でサブエージェントを定義および使用する方法について説明します。
概要
サブエージェントは 3 つの方法で作成できます。- プログラム的に:
query()オプションのagentsパラメータを使用します。TypeScript および Python リファレンスを参照してください - ファイルシステムベース:
.claude/agents/ディレクトリ内のマークダウンファイルとしてエージェントを定義します。ファイルとしてサブエージェントを定義するを参照してください - 組み込みの汎用: Claude は、何も定義することなく、Agent ツールを介して組み込みの
general-purposeサブエージェントをいつでも呼び出すことができます
description フィールドに基づいて、それらを呼び出すかどうかを判断します。サブエージェントをいつ使用すべきかを説明する明確な説明を書いてください。Claude は自動的に適切なタスクを委譲します。プロンプトでサブエージェントを名前で明示的にリクエストすることもできます。例えば「code-reviewer エージェントを使用して…」のようにです。
サブエージェントを使用する利点
コンテキスト分離
各サブエージェントは独自の新しい会話で実行されます。中間的なツール呼び出しと結果はサブエージェント内に留まり、最終メッセージだけが親に返されます。サブエージェントが継承するものを参照して、サブエージェントのコンテキストに正確に何が含まれているかを確認してください。 例:research-assistant サブエージェントは、そのコンテンツがメイン会話に蓄積されることなく、数十のファイルを探索できます。親は、サブエージェントが読んだすべてのファイルではなく、簡潔なサマリーを受け取ります。
並列化
複数のサブエージェントを同時に実行でき、独立したサブタスクはすべての合計ではなく、最も遅いものの時間で完了します。 例: コードレビュー中に、style-checker、security-scanner、test-coverage サブエージェントを順序立てて実行するのではなく、同時に実行できます。
特殊な指示と知識
各サブエージェントは、特定の専門知識、ベストプラクティス、制約を備えたカスタマイズされたシステムプロンプトを持つことができます。 例:database-migration サブエージェントは、SQL ベストプラクティス、ロールバック戦略、データ整合性チェックに関する詳細な知識を持つことができます。これらはメインエージェントの指示では不要なノイズになります。
ツール制限
サブエージェントは特定のツールに制限でき、意図しないアクションのリスクを軽減します。 例:doc-reviewer サブエージェントは Read と Grep ツールのみにアクセスでき、ドキュメントファイルを分析できますが、誤って変更することはありません。
サブエージェントの作成
プログラム的な定義（推奨）
agents パラメータを使用してコード内でサブエージェントを直接定義します。Claude はサブエージェントを Agent ツール経由で呼び出すため、allowedTools に Agent を含めて、パーミッション プロンプトなしでサブエージェント呼び出しを自動承認する必要があります。
このページのほとんどの例は最終結果のみを出力します。Claude がサブエージェントに委譲したことを確認するには、サブエージェント呼び出しの検出を参照してください。
この例では、読み取り専用アクセスを持つコードレビュアーとコマンドを実行できるテストランナーの 2 つのサブエージェントを作成します。