agents
パラメータを使用してSDKでサブエージェントを定義し使用する方法を説明します。
概要
SDKを使用する際、サブエージェントは2つの方法で定義できます:- プログラム的 -
query()
オプションでagents
パラメータを使用(SDKアプリケーションに推奨) - ファイルシステムベース - 指定されたディレクトリ(
.claude/agents/
)にYAMLフロントマターを含むマークダウンファイルを配置
agents
パラメータを使用したプログラム的アプローチに焦点を当てており、SDKアプリケーションにより統合された開発体験を提供します。
サブエージェント使用の利点
コンテキスト管理
サブエージェントはメインエージェントから分離されたコンテキストを維持し、情報過多を防ぎ、インタラクションを集中させます。この分離により、特殊化されたタスクが無関係な詳細でメインの会話コンテキストを汚染することがなくなります。 例:research-assistant
サブエージェントは、数十のファイルやドキュメントページを探索できますが、すべての中間検索結果でメインの会話を混乱させることなく、関連する発見のみを返します。
並列化
複数のサブエージェントが同時に実行でき、複雑なワークフローを劇的に高速化します。 例: コードレビュー中に、style-checker
、security-scanner
、test-coverage
サブエージェントを同時に実行し、レビュー時間を数分から数秒に短縮できます。
特殊化された指示と知識
各サブエージェントは、特定の専門知識、ベストプラクティス、制約を持つカスタマイズされたシステムプロンプトを持つことができます。 例:database-migration
サブエージェントは、SQLベストプラクティス、ロールバック戦略、データ整合性チェックに関する詳細な知識を持つことができ、これらはメインエージェントの指示では不要なノイズとなるでしょう。
ツール制限
サブエージェントは特定のツールに制限でき、意図しない行動のリスクを減らします。 例:doc-reviewer
サブエージェントは読み取りとGrepツールのみにアクセスでき、分析はできるが誤ってドキュメントファイルを変更することがないことを保証します。
サブエージェントの作成
プログラム的定義(推奨)
agents
パラメータを使用してコード内で直接サブエージェントを定義します:
AgentDefinition設定
フィールド | 型 | 必須 | 説明 |
---|---|---|---|
description | string | はい | このエージェントをいつ使用するかの自然言語説明 |
prompt | string | はい | エージェントの役割と動作を定義するシステムプロンプト |
tools | string[] | いいえ | 許可されたツール名の配列。省略時はすべてのツールを継承 |
model | 'sonnet' | 'opus' | 'haiku' | 'inherit' | いいえ | このエージェントのモデルオーバーライド。省略時はメインモデルをデフォルト |
ファイルシステムベース定義(代替)
特定のディレクトリにマークダウンファイルとしてサブエージェントを定義することもできます:- プロジェクトレベル:
.claude/agents/*.md
- 現在のプロジェクトでのみ利用可能 - ユーザーレベル:
~/.claude/agents/*.md
- すべてのプロジェクトで利用可能
agents
パラメータ経由)は、同じ名前のファイルシステムベースエージェントより優先されます。
SDKによるサブエージェントの使用
Claude Agent SDKを使用する際、サブエージェントはプログラム的に定義するか、ファイルシステムから読み込むことができます。Claudeは:- プログラム的エージェントを読み込み - オプションの
agents
パラメータから - ファイルシステムエージェントを自動検出 -
.claude/agents/
ディレクトリから(オーバーライドされていない場合) - 自動的に呼び出し - タスクマッチングとエージェントの
description
に基づいて - 特殊化されたプロンプトを使用 - およびツール制限
- 分離されたコンテキストを維持 - 各サブエージェント呼び出しに対して
agents
パラメータ経由)は、同じ名前のファイルシステムベースエージェントより優先されます。
サブエージェントの例
コードレビュアー、テストランナー、デバッガー、セキュリティ監査人を含むサブエージェントの包括的な例については、メインサブエージェントガイドを参照してください。このガイドには、効果的なサブエージェントを作成するための詳細な設定とベストプラクティスが含まれています。SDK統合パターン
自動呼び出し
SDKは、タスクコンテキストに基づいて適切なサブエージェントを自動的に呼び出します。エージェントのdescription
フィールドが、いつ使用すべきかを明確に示すようにしてください:
明示的呼び出し
ユーザーはプロンプトで特定のサブエージェントを要求できます:動的エージェント設定
アプリケーションのニーズに基づいてエージェントを動的に設定できます:ツール制限
サブエージェントはtools
フィールドを通じてツールアクセスを制限できます:
- フィールドを省略 - エージェントは利用可能なすべてのツールを継承(デフォルト)
- ツールを指定 - エージェントはリストされたツールのみ使用可能
一般的なツールの組み合わせ
読み取り専用エージェント(分析、レビュー):関連ドキュメント
- メインサブエージェントガイド - 包括的なサブエージェントドキュメント
- SDK設定ガイド - 設定アプローチの概要
- 設定 - 設定ファイルリファレンス
- スラッシュコマンド - カスタムコマンド作成