Claude Agent SDKにおけるサブエージェントは、メインエージェントによって統制される特殊化されたAIです。 コンテキスト管理と並列化にサブエージェントを使用してください。 このガイドでは、agentsパラメータを使用してSDKでサブエージェントを定義し使用する方法を説明します。

概要

SDKを使用する際、サブエージェントは2つの方法で定義できます:
  1. プログラム的 - query()オプションでagentsパラメータを使用(SDKアプリケーションに推奨)
  2. ファイルシステムベース - 指定されたディレクトリ(.claude/agents/)にYAMLフロントマターを含むマークダウンファイルを配置
このガイドは主にagentsパラメータを使用したプログラム的アプローチに焦点を当てており、SDKアプリケーションにより統合された開発体験を提供します。

サブエージェント使用の利点

コンテキスト管理

サブエージェントはメインエージェントから分離されたコンテキストを維持し、情報過多を防ぎ、インタラクションを集中させます。この分離により、特殊化されたタスクが無関係な詳細でメインの会話コンテキストを汚染することがなくなります。 : research-assistantサブエージェントは、数十のファイルやドキュメントページを探索できますが、すべての中間検索結果でメインの会話を混乱させることなく、関連する発見のみを返します。

並列化

複数のサブエージェントが同時に実行でき、複雑なワークフローを劇的に高速化します。 : コードレビュー中に、style-checkersecurity-scannertest-coverageサブエージェントを同時に実行し、レビュー時間を数分から数秒に短縮できます。

特殊化された指示と知識

各サブエージェントは、特定の専門知識、ベストプラクティス、制約を持つカスタマイズされたシステムプロンプトを持つことができます。 : database-migrationサブエージェントは、SQLベストプラクティス、ロールバック戦略、データ整合性チェックに関する詳細な知識を持つことができ、これらはメインエージェントの指示では不要なノイズとなるでしょう。

ツール制限

サブエージェントは特定のツールに制限でき、意図しない行動のリスクを減らします。 : doc-reviewerサブエージェントは読み取りとGrepツールのみにアクセスでき、分析はできるが誤ってドキュメントファイルを変更することがないことを保証します。

サブエージェントの作成

プログラム的定義(推奨)

agentsパラメータを使用してコード内で直接サブエージェントを定義します:
import { query } from '@anthropic/claude-code-sdk';

const result = query({
  prompt: "認証モジュールのセキュリティ問題をレビューしてください",
  options: {
    agents: {
      'code-reviewer': {
        description: 'エキスパートコードレビュー専門家。品質、セキュリティ、保守性のレビューに使用。',
        prompt: `あなたはセキュリティ、パフォーマンス、ベストプラクティスの専門知識を持つコードレビュー専門家です。

コードをレビューする際:
- セキュリティ脆弱性を特定
- パフォーマンス問題をチェック
- コーディング標準への準拠を確認
- 具体的な改善を提案

徹底的でありながら簡潔なフィードバックを提供してください。`,
        tools: ['Read', 'Grep', 'Glob'],
        model: 'sonnet'
      },
      'test-runner': {
        description: 'テストスイートを実行し分析。テスト実行とカバレッジ分析に使用。',
        prompt: `あなたはテスト実行専門家です。テストを実行し、結果の明確な分析を提供してください。

以下に焦点を当てる:
- テストコマンドの実行
- テスト出力の分析
- 失敗したテストの特定
- 失敗の修正提案`,
        tools: ['Bash', 'Read', 'Grep'],
      }
    }
  }
});

for await (const message of result) {
  console.log(message);
}

AgentDefinition設定

フィールド必須説明
descriptionstringはいこのエージェントをいつ使用するかの自然言語説明
promptstringはいエージェントの役割と動作を定義するシステムプロンプト
toolsstring[]いいえ許可されたツール名の配列。省略時はすべてのツールを継承
model'sonnet' | 'opus' | 'haiku' | 'inherit'いいえこのエージェントのモデルオーバーライド。省略時はメインモデルをデフォルト

ファイルシステムベース定義(代替)

特定のディレクトリにマークダウンファイルとしてサブエージェントを定義することもできます:
  • プロジェクトレベル: .claude/agents/*.md - 現在のプロジェクトでのみ利用可能
  • ユーザーレベル: ~/.claude/agents/*.md - すべてのプロジェクトで利用可能
各サブエージェントはYAMLフロントマターを含むマークダウンファイルです:
---
name: code-reviewer
description: エキスパートコードレビュー専門家。品質、セキュリティ、保守性のレビューに使用。
tools: Read, Grep, Glob, Bash
---

サブエージェントのシステムプロンプトをここに記述します。これはサブエージェントの
役割、能力、問題解決へのアプローチを定義します。
注意: プログラム的に定義されたエージェント(agentsパラメータ経由)は、同じ名前のファイルシステムベースエージェントより優先されます。

SDKによるサブエージェントの使用

Claude Agent SDKを使用する際、サブエージェントはプログラム的に定義するか、ファイルシステムから読み込むことができます。Claudeは:
  1. プログラム的エージェントを読み込み - オプションのagentsパラメータから
  2. ファイルシステムエージェントを自動検出 - .claude/agents/ディレクトリから(オーバーライドされていない場合)
  3. 自動的に呼び出し - タスクマッチングとエージェントのdescriptionに基づいて
  4. 特殊化されたプロンプトを使用 - およびツール制限
  5. 分離されたコンテキストを維持 - 各サブエージェント呼び出しに対して
プログラム的に定義されたエージェント(agentsパラメータ経由)は、同じ名前のファイルシステムベースエージェントより優先されます。

サブエージェントの例

コードレビュアー、テストランナー、デバッガー、セキュリティ監査人を含むサブエージェントの包括的な例については、メインサブエージェントガイドを参照してください。このガイドには、効果的なサブエージェントを作成するための詳細な設定とベストプラクティスが含まれています。

SDK統合パターン

自動呼び出し

SDKは、タスクコンテキストに基づいて適切なサブエージェントを自動的に呼び出します。エージェントのdescriptionフィールドが、いつ使用すべきかを明確に示すようにしてください:
const result = query({
  prompt: "APIレイヤーのデータベースクエリを最適化してください",
  options: {
    agents: {
      'performance-optimizer': {
        description: 'コード変更がパフォーマンスに影響する可能性がある場合にPROACTIVELYに使用。最適化タスクには必須。',
        prompt: 'あなたはパフォーマンス最適化専門家です...',
        tools: ['Read', 'Edit', 'Bash', 'Grep'],
        model: 'sonnet'
      }
    }
  }
});

明示的呼び出し

ユーザーはプロンプトで特定のサブエージェントを要求できます:
const result = query({
  prompt: "code-reviewerエージェントを使用して認証モジュールをチェックしてください",
  options: {
    agents: {
      'code-reviewer': {
        description: 'エキスパートコードレビュー専門家',
        prompt: 'あなたはセキュリティに焦点を当てたコードレビュアーです...',
        tools: ['Read', 'Grep', 'Glob']
      }
    }
  }
});

動的エージェント設定

アプリケーションのニーズに基づいてエージェントを動的に設定できます:
import { query, type AgentDefinition } from '@anthropic/claude-code-sdk';

function createSecurityAgent(securityLevel: 'basic' | 'strict'): AgentDefinition {
  return {
    description: 'セキュリティコードレビュアー',
    prompt: `あなたは${securityLevel === 'strict' ? '厳格な' : 'バランスの取れた'}セキュリティレビュアーです...`,
    tools: ['Read', 'Grep', 'Glob'],
    model: securityLevel === 'strict' ? 'opus' : 'sonnet'
  };
}

const result = query({
  prompt: "このPRのセキュリティ問題をレビューしてください",
  options: {
    agents: {
      'security-reviewer': createSecurityAgent('strict')
    }
  }
});

ツール制限

サブエージェントはtoolsフィールドを通じてツールアクセスを制限できます:
  • フィールドを省略 - エージェントは利用可能なすべてのツールを継承(デフォルト)
  • ツールを指定 - エージェントはリストされたツールのみ使用可能
読み取り専用分析エージェントの例:
const result = query({
  prompt: "このコードベースのアーキテクチャを分析してください",
  options: {
    agents: {
      'code-analyzer': {
        description: '静的コード分析とアーキテクチャレビュー',
        prompt: `あなたはコードアーキテクチャアナリストです。コード構造を分析し、
パターンを特定し、変更を加えることなく改善を提案してください。`,
        tools: ['Read', 'Grep', 'Glob']  // 書き込みや実行権限なし
      }
    }
  }
});

一般的なツールの組み合わせ

読み取り専用エージェント(分析、レビュー):
tools: ['Read', 'Grep', 'Glob']
テスト実行エージェント
tools: ['Bash', 'Read', 'Grep']
コード変更エージェント
tools: ['Read', 'Edit', 'MultiEdit', 'Write', 'Grep', 'Glob']

関連ドキュメント