ガイド

SDKにおけるサブエージェント

Claude Agent SDKでサブエージェントを使用する方法

Claude Agent SDKにおけるサブエージェントは、メインエージェントによって統制される専門化されたAIです。コンテキスト管理と並列化にサブエージェントを使用してください。

このガイドでは、agentsパラメータを使用してSDKでサブエージェントを定義し使用する方法について説明します。

概要

SDKを使用する際、サブエージェントは2つの方法で定義できます：

プログラム的 - query()オプションでagentsパラメータを使用（SDKアプリケーションに推奨）
ファイルシステムベース - 指定されたディレクトリ（.claude/agents/）にYAMLフロントマターを持つマークダウンファイルを配置

このガイドでは主に、SDKアプリケーションにより統合された開発体験を提供するagentsパラメータを使用したプログラム的アプローチに焦点を当てます。

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

コンテキスト管理

サブエージェントはメインエージェントから分離されたコンテキストを維持し、情報過多を防ぎ、やり取りを集中させます。この分離により、専門化されたタスクが無関係な詳細でメインの会話コンテキストを汚染することがなくなります。

例: research-assistantサブエージェントは、中間検索結果すべてでメインの会話を乱雑にすることなく、数十のファイルとドキュメントページを探索し、関連する発見のみを返すことができます。

並列化

複数のサブエージェントが同時に実行でき、複雑なワークフローを劇的に高速化します。

例: コードレビュー中に、style-checker、security-scanner、test-coverageサブエージェントを同時に実行し、レビュー時間を数分から数秒に短縮できます。

専門化された指示と知識

各サブエージェントは、特定の専門知識、ベストプラクティス、制約を持つカスタマイズされたシステムプロンプトを持つことができます。

例: database-migrationサブエージェントは、メインエージェントの指示では不要なノイズとなるSQLベストプラクティス、ロールバック戦略、データ整合性チェックに関する詳細な知識を持つことができます。

ツール制限

サブエージェントは特定のツールに制限でき、意図しない動作のリスクを軽減します。

例: doc-reviewerサブエージェントはReadとGrepツールのみにアクセスでき、分析はできるがドキュメントファイルを誤って変更することがないことを保証します。

サブエージェントの作成

プログラム的定義（推奨）

agentsパラメータを使用してコード内で直接サブエージェントを定義します：

import { query } from '@anthropic-ai/claude-agent-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設定

フィールド	タイプ	必須	説明
`description`	`string`	はい	このエージェントをいつ使用するかの自然言語説明
`prompt`	`string`	はい	エージェントの役割と動作を定義するシステムプロンプト
`tools`	`string[]`	いいえ	許可されたツール名の配列。省略時は全ツールを継承
`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は：

プログラム的エージェントを読み込み - オプションのagentsパラメータから
ファイルシステムエージェントを自動検出 - .claude/agents/ディレクトリから（オーバーライドされていない場合）
自動的に呼び出し - タスクマッチングとエージェントのdescriptionに基づいて
専門化されたプロンプトを使用 - ツール制限と共に
分離されたコンテキストを維持 - 各サブエージェント呼び出しで

プログラム的に定義されたエージェント（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-ai/claude-agent-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', 'Write', 'Grep', 'Glob']

SDKにおけるサブエージェント

Claude Agent SDKでサブエージェントを使用する方法

このガイドでは、agentsパラメータを使用してSDKでサブエージェントを定義し使用する方法について説明します。

概要

SDKを使用する際、サブエージェントは2つの方法で定義できます：

プログラム的 - query()オプションでagentsパラメータを使用（SDKアプリケーションに推奨）
ファイルシステムベース - 指定されたディレクトリ（.claude/agents/）にYAMLフロントマターを持つマークダウンファイルを配置

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

コンテキスト管理

並列化

複数のサブエージェントが同時に実行でき、複雑なワークフローを劇的に高速化します。

例: コードレビュー中に、style-checker、security-scanner、test-coverageサブエージェントを同時に実行し、レビュー時間を数分から数秒に短縮できます。

専門化された指示と知識

各サブエージェントは、特定の専門知識、ベストプラクティス、制約を持つカスタマイズされたシステムプロンプトを持つことができます。

ツール制限

サブエージェントは特定のツールに制限でき、意図しない動作のリスクを軽減します。

サブエージェントの作成

プログラム的定義（推奨）

agentsパラメータを使用してコード内で直接サブエージェントを定義します：

import { query } from '@anthropic-ai/claude-agent-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設定

フィールド	タイプ	必須	説明
`description`	`string`	はい	このエージェントをいつ使用するかの自然言語説明
`prompt`	`string`	はい	エージェントの役割と動作を定義するシステムプロンプト
`tools`	`string[]`	いいえ	許可されたツール名の配列。省略時は全ツールを継承
`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は：

プログラム的エージェントを読み込み - オプションのagentsパラメータから
ファイルシステムエージェントを自動検出 - .claude/agents/ディレクトリから（オーバーライドされていない場合）
自動的に呼び出し - タスクマッチングとエージェントのdescriptionに基づいて
専門化されたプロンプトを使用 - ツール制限と共に
分離されたコンテキストを維持 - 各サブエージェント呼び出しで

プログラム的に定義されたエージェント（agentsパラメータ経由）は、同じ名前のファイルシステムベースエージェントより優先されます。

サブエージェントの例

SDK統合パターン

自動呼び出し

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-ai/claude-agent-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', 'Write', 'Grep', 'Glob']

概要

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

コンテキスト管理

並列化

専門化された指示と知識

ツール制限

サブエージェントの作成

プログラム的定義（推奨）

AgentDefinition設定

ファイルシステムベース定義（代替）

SDKがサブエージェントを使用する方法

サブエージェントの例

SDK統合パターン

自動呼び出し

明示的呼び出し

動的エージェント設定

ツール制限

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

関連ドキュメント

概要

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

コンテキスト管理

並列化

専門化された指示と知識

ツール制限

サブエージェントの作成

プログラム的定義（推奨）

AgentDefinition設定

ファイルシステムベース定義（代替）

SDKがサブエージェントを使用する方法

サブエージェントの例

SDK統合パターン

自動呼び出し

明示的呼び出し

動的エージェント設定

ツール制限

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

関連ドキュメント