SDK のサブエージェント

サブエージェントを定義して呼び出し、コンテキストを分離し、タスクを並列実行し、Claude Agent SDK アプリケーションで特殊な指示を適用します。

サブエージェントは、メインエージェントが生成できる個別のエージェントインスタンスで、焦点を絞ったサブタスクを処理します。サブエージェントを使用して、焦点を絞ったサブタスクのコンテキストを分離し、複数の分析を並列実行し、メインエージェントのプロンプトを肥大化させずに特殊な指示を適用します。

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

概要

サブエージェントは 3 つの方法で作成できます。

プログラム的に: query() オプションの agents パラメータを使用します（TypeScript、Python）
ファイルシステムベース: .claude/agents/ ディレクトリ内のマークダウンファイルとしてエージェントを定義します（ファイルとしてサブエージェントを定義するを参照）
組み込みの汎用: Claude は、何も定義することなく、Agent ツールを介して組み込みの general-purpose サブエージェントをいつでも呼び出すことができます

このガイドでは、SDK アプリケーションに推奨されるプログラム的なアプローチに焦点を当てています。

サブエージェントを定義する場合、Claude は各サブエージェントの description フィールドに基づいて、それらを呼び出すかどうかを判断します。サブエージェントをいつ使用すべきかを説明する明確な説明を書いてください。Claude は自動的に適切なタスクを委譲します。プロンプトでサブエージェントを名前で明示的にリクエストすることもできます（例えば、「code-reviewer エージェントを使用して...」）。

サブエージェントを使用する利点

コンテキスト分離

各サブエージェントは独自の新しい会話で実行されます。中間的なツール呼び出しと結果はサブエージェント内に留まり、最終メッセージだけが親に返されます。サブエージェントが継承するものを参照して、サブエージェントのコンテキストに正確に何が含まれているかを確認してください。

例: research-assistant サブエージェントは、そのコンテンツがメイン会話に蓄積されることなく、数十のファイルを探索できます。親は、サブエージェントが読んだすべてのファイルではなく、簡潔なサマリーを受け取ります。

並列化

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

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

特殊な指示と知識

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

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

ツール制限

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

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

サブエージェントの作成

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

agents パラメータを使用してコード内でサブエージェントを直接定義します。この例では、読み取り専用アクセスを持つコードレビュアーとコマンドを実行できるテストランナーの 2 つのサブエージェントを作成します。Claude がサブエージェントを Agent ツール経由で呼び出すため、Agent ツールを allowedTools に含める必要があります。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
async for message in query(
prompt="Review the authentication module for security issues",
options=ClaudeAgentOptions(
# Agent tool is required for subagent invocation
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"code-reviewer": AgentDefinition(
# description tells Claude when to use this subagent
description="Expert code review specialist. Use for quality, security, and maintainability reviews.",
# prompt defines the subagent's behavior and expertise
prompt="""You are a code review specialist with expertise in security, performance, and best practices.

When reviewing code:
- Identify security vulnerabilities
- Check for performance issues
- Verify adherence to coding standards
- Suggest specific improvements

Be thorough but concise in your feedback.""",
# tools restricts what the subagent can do (read-only here)
tools=["Read", "Grep", "Glob"],
# model overrides the default model for this subagent
model="sonnet",
),
"test-runner": AgentDefinition(
description="Runs and analyzes test suites. Use for test execution and coverage analysis.",
prompt="""You are a test execution specialist. Run tests and provide clear analysis of results.

Focus on:
- Running test commands
- Analyzing test output
- Identifying failing tests
- Suggesting fixes for failures""",
# Bash access lets this subagent run test commands
tools=["Bash", "Read", "Grep"],
),
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Review the authentication module for security issues",
options: {
// Agent tool is required for subagent invocation
allowedTools: ["Read", "Grep", "Glob", "Agent"],
agents: {
"code-reviewer": {
// description tells Claude when to use this subagent
description:
"Expert code review specialist. Use for quality, security, and maintainability reviews.",
// prompt defines the subagent's behavior and expertise
prompt: `You are a code review specialist with expertise in security, performance, and best practices.

When reviewing code:
- Identify security vulnerabilities
- Check for performance issues
- Verify adherence to coding standards
- Suggest specific improvements

Be thorough but concise in your feedback.`,
// tools restricts what the subagent can do (read-only here)
tools: ["Read", "Grep", "Glob"],
// model overrides the default model for this subagent
model: "sonnet"
},
"test-runner": {
description:
"Runs and analyzes test suites. Use for test execution and coverage analysis.",
prompt: `You are a test execution specialist. Run tests and provide clear analysis of results.

Focus on:
- Running test commands
- Analyzing test output
- Identifying failing tests
- Suggesting fixes for failures`,
// Bash access lets this subagent run test commands
tools: ["Bash", "Read", "Grep"]
}
}
}
})) {
if ("result" in message) console.log(message.result);
}

AgentDefinition 設定

フィールド	型	必須	説明
`description`	`string`	はい	このエージェントをいつ使用するかについての自然言語説明
`prompt`	`string`	はい	エージェントの役割と動作を定義するシステムプロンプト
`tools`	`string[]`	いいえ	許可されたツール名の配列。省略した場合、すべてのツールを継承します
`disallowedTools`	`string[]`	いいえ	エージェントのツールセットから削除するツール名の配列
`model`	`string`	いいえ	このエージェントのモデルオーバーライド。`'sonnet'`、`'opus'`、`'haiku'`、`'inherit'` などのエイリアス、または完全なモデル ID を受け入れます。省略した場合、メインモデルがデフォルトになります
`skills`	`string[]`	いいえ	スタートアップ時にエージェントのコンテキストにプリロードするスキル名のリスト。リストされていないスキルは Skill ツール経由で呼び出し可能なままです
`memory`	`'user' \| 'project' \| 'local'`	いいえ	このエージェントのメモリソース
`mcpServers`	`(string \| object)[]`	いいえ	このエージェントが利用可能な MCP サーバー（名前またはインライン設定）
`maxTurns`	`number`	いいえ	エージェントが停止する前の最大 agentic ターン数
`background`	`boolean`	いいえ	呼び出されたときにこのエージェントをノンブロッキングバックグラウンドタスクとして実行します
`effort`	`'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number`	いいえ	このエージェントの推論努力レベル
`permissionMode`	`PermissionMode`	いいえ	このエージェント内のツール実行のパーミッションモード

Python SDK では、これらのフィールド名は wire フォーマットに一致するように camelCase を使用します。詳細については、AgentDefinition リファレンスを参照してください。

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

.claude/agents/ ディレクトリ内のマークダウンファイルとしてサブエージェントを定義することもできます。このアプローチの詳細については、Claude Code サブエージェントドキュメントを参照してください。プログラム的に定義されたエージェントは、同じ名前のファイルシステムベースのエージェントより優先されます。

サブエージェントが継承するもの

サブエージェントのコンテキストウィンドウは新しく開始されます（親の会話なし）が、空ではありません。親からサブエージェントへの唯一のチャネルは Agent ツールのプロンプト文字列なので、サブエージェントが必要とするファイルパス、エラーメッセージ、または決定をそのプロンプトに直接含めてください。

サブエージェントが受け取るもの	サブエージェントが受け取らないもの
独自のシステムプロンプト（`AgentDefinition.prompt`）と Agent ツールのプロンプト	親の会話履歴またはツール結果
プロジェクト CLAUDE.md（`settingSources` 経由でロード）	プリロードされたスキルコンテンツ（`AgentDefinition.skills` にリストされている場合を除く）
ツール定義（親から継承、または `tools` のサブセット）	親のシステムプロンプト

サブエージェントの呼び出し

自動呼び出し

Claude は、タスクと各サブエージェントの description に基づいて、サブエージェントをいつ呼び出すかを自動的に決定します。例えば、説明が「クエリチューニング用のパフォーマンス最適化スペシャリスト」である performance-optimizer サブエージェントを定義した場合、プロンプトでクエリの最適化について言及すると、Claude はそれを呼び出します。

Claude がタスクを正しいサブエージェントにマッチングできるように、明確で具体的な説明を書いてください。

明示的な呼び出し

Claude が特定のサブエージェントを使用することを保証するには、プロンプトで名前を言及してください。

"Use the code-reviewer agent to check the authentication module"

これは自動マッチングをバイパスし、名前付きサブエージェントを直接呼び出します。

動的エージェント設定

実行時の条件に基づいて、エージェント定義を動的に作成できます。この例では、異なる厳密性レベルを持つセキュリティレビュアーを作成し、厳密なレビューにはより強力なモデルを使用します。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


# Factory function that returns an AgentDefinition
# This pattern lets you customize agents based on runtime conditions
def create_security_agent(security_level: str) -> AgentDefinition:
is_strict = security_level == "strict"
return AgentDefinition(
description="Security code reviewer",
# Customize the prompt based on strictness level
prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",
tools=["Read", "Grep", "Glob"],
# Key insight: use a more capable model for high-stakes reviews
model="opus" if is_strict else "sonnet",
)


async def main():
# The agent is created at query time, so each request can use different settings
async for message in query(
prompt="Review this PR for security issues",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
# Call the factory with your desired configuration
"security-reviewer": create_security_agent("strict")
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

import { query, type AgentDefinition } from "@anthropic-ai/claude-agent-sdk";

// Factory function that returns an AgentDefinition
// This pattern lets you customize agents based on runtime conditions
function createSecurityAgent(securityLevel: "basic" | "strict"): AgentDefinition {
const isStrict = securityLevel === "strict";
return {
description: "Security code reviewer",
// Customize the prompt based on strictness level
prompt: `You are a ${isStrict ? "strict" : "balanced"} security reviewer...`,
tools: ["Read", "Grep", "Glob"],
// Key insight: use a more capable model for high-stakes reviews
model: isStrict ? "opus" : "sonnet"
};
}

// The agent is created at query time, so each request can use different settings
for await (const message of query({
prompt: "Review this PR for security issues",
options: {
allowedTools: ["Read", "Grep", "Glob", "Agent"],
agents: {
// Call the factory with your desired configuration
"security-reviewer": createSecurityAgent("strict")
}
}
})) {
if ("result" in message) console.log(message.result);
}

サブエージェント呼び出しの検出

サブエージェントは Agent ツール経由で呼び出されます。サブエージェントが呼び出されたときを検出するには、name が "Agent" である tool_use ブロックをチェックしてください。サブエージェントのコンテキスト内からのメッセージには parent_tool_use_id フィールドが含まれます。

この例は、ストリーミングされたメッセージを反復処理し、サブエージェントが呼び出されたときと、その後のメッセージがそのサブエージェントの実行コンテキスト内から発信されたときをログに記録します。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
async for message in query(
prompt="Use the code-reviewer agent to review this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="Expert code reviewer.",
prompt="Analyze code quality and suggest improvements.",
tools=["Read", "Glob", "Grep"],
)
},
),
):
# Check for subagent invocation. Match both names: older SDK
# versions emitted "Task", current versions emit "Agent".
if hasattr(message, "content") and message.content:
for block in message.content:
if getattr(block, "type", None) == "tool_use" and block.name in (
"Task",
"Agent",
):
print(f"Subagent invoked: {block.input.get('subagent_type')}")

# Check if this message is from within a subagent's context
if hasattr(message, "parent_tool_use_id") and message.parent_tool_use_id:
print("  (running inside subagent)")

if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Use the code-reviewer agent to review this codebase",
options: {
allowedTools: ["Read", "Glob", "Grep", "Agent"],
agents: {
"code-reviewer": {
description: "Expert code reviewer.",
prompt: "Analyze code quality and suggest improvements.",
tools: ["Read", "Glob", "Grep"]
}
}
}
})) {
const msg = message as any;

// Check for subagent invocation. Match both names: older SDK versions
// emitted "Task", current versions emit "Agent".
for (const block of msg.message?.content ?? []) {
if (block.type === "tool_use" && (block.name === "Task" || block.name === "Agent")) {
console.log(`Subagent invoked: ${block.input.subagent_type}`);
}
}

// Check if this message is from within a subagent's context
if (msg.parent_tool_use_id) {
console.log("  (running inside subagent)");
}

if ("result" in message) {
console.log(message.result);
}
}

サブエージェントの再開

サブエージェントを再開して、中断したところから続行できます。再開されたサブエージェントは、以前のすべてのツール呼び出し、結果、推論を含む完全な会話履歴を保持します。サブエージェントは新しく開始するのではなく、停止したところから正確に再開します。

サブエージェントが完了すると、Claude は Agent ツール結果でエージェント ID を受け取ります。サブエージェントをプログラム的に再開するには：

セッション ID をキャプチャする: 最初のクエリ中にメッセージから session_id を抽出します
エージェント ID を抽出する: メッセージコンテンツから agentId を解析します
セッションを再開する: 2 番目のクエリのオプションで resume: sessionId を渡し、プロンプトにエージェント ID を含めます

以下の例は、このフローを示しています。最初のクエリはサブエージェントを実行してセッション ID とエージェント ID をキャプチャし、2 番目のクエリはセッションを再開して、最初の分析からのコンテキストが必要なフォローアップ質問をします。

import { query, type SDKMessage } from "@anthropic-ai/claude-agent-sdk";

// Helper to extract agentId from message content
// Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.)
function extractAgentId(message: SDKMessage): string | undefined {
if (!("message" in message)) return undefined;
// Stringify the content so we can search it without traversing nested blocks
const content = JSON.stringify(message.message.content);
const match = content.match(/agentId:\s*([a-f0-9-]+)/);
return match?.[1];
}

let agentId: string | undefined;
let sessionId: string | undefined;

// First invocation - use the Explore agent to find API endpoints
for await (const message of query({
prompt: "Use the Explore agent to find all API endpoints in this codebase",
options: { allowedTools: ["Read", "Grep", "Glob", "Agent"] }
})) {
// Capture session_id from ResultMessage (needed to resume this session)
if ("session_id" in message) sessionId = message.session_id;
// Search message content for the agentId (appears in Agent tool results)
const extractedId = extractAgentId(message);
if (extractedId) agentId = extractedId;
// Print the final result
if ("result" in message) console.log(message.result);
}

// Second invocation - resume and ask follow-up
if (agentId && sessionId) {
for await (const message of query({
prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`,
options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], resume: sessionId }
})) {
if ("result" in message) console.log(message.result);
}
}

import asyncio
import json
import re
from claude_agent_sdk import query, ClaudeAgentOptions


def extract_agent_id(text: str) -> str | None:
"""Extract agentId from Agent tool result text."""
match = re.search(r"agentId:\s*([a-f0-9-]+)", text)
return match.group(1) if match else None


async def main():
agent_id = None
session_id = None

# First invocation - use the Explore agent to find API endpoints
async for message in query(
prompt="Use the Explore agent to find all API endpoints in this codebase",
options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"]),
):
# Capture session_id from ResultMessage (needed to resume this session)
if hasattr(message, "session_id"):
session_id = message.session_id
# Search message content for the agentId (appears in Agent tool results)
if hasattr(message, "content"):
# Stringify the content so we can search it without traversing nested blocks
content_str = json.dumps(message.content, default=str)
extracted = extract_agent_id(content_str)
if extracted:
agent_id = extracted
# Print the final result
if hasattr(message, "result"):
print(message.result)

# Second invocation - resume and ask follow-up
if agent_id and session_id:
async for message in query(
prompt=f"Resume agent {agent_id} and list the top 3 most complex endpoints",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"], resume=session_id
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

サブエージェントのトランスクリプトはメイン会話とは独立して永続化されます。

メイン会話の圧縮: メイン会話が圧縮されると、サブエージェントのトランスクリプトは影響を受けません。これらは別のファイルに保存されます。
セッション永続化: サブエージェントのトランスクリプトはセッション内で永続化されます。同じセッションを再開することで、Claude Code を再起動した後にサブエージェントを再開できます。
自動クリーンアップ: トランスクリプトは cleanupPeriodDays 設定に基づいてクリーンアップされます（デフォルト：30 日）。

ツール制限

サブエージェントは tools フィールド経由で制限されたツールアクセスを持つことができます。

フィールドを省略: エージェントは利用可能なすべてのツールを継承します（デフォルト）
ツールを指定: エージェントはリストされたツールのみを使用できます

この例では、コードを検査できるが、ファイルを変更したりコマンドを実行したりできない読み取り専用分析エージェントを作成します。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
async for message in query(
prompt="Analyze the architecture of this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob", "Agent"],
agents={
"code-analyzer": AgentDefinition(
description="Static code analysis and architecture review",
prompt="""You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.""",
# Read-only tools: no Edit, Write, or Bash access
tools=["Read", "Grep", "Glob"],
)
},
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Analyze the architecture of this codebase",
options: {
allowedTools: ["Read", "Grep", "Glob", "Agent"],
agents: {
"code-analyzer": {
description: "Static code analysis and architecture review",
prompt: `You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.`,
// Read-only tools: no Edit, Write, or Bash access
tools: ["Read", "Grep", "Glob"]
}
}
}
})) {
if ("result" in message) console.log(message.result);
}

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

ユースケース	ツール	説明
読み取り専用分析	`Read`、`Grep`、`Glob`	コードを検査できますが、変更または実行はできません
テスト実行	`Bash`、`Read`、`Grep`	コマンドを実行し、出力を分析できます
コード変更	`Read`、`Edit`、`Write`、`Grep`、`Glob`	コマンド実行なしで完全な読み取り/書き込みアクセス
完全アクセス	すべてのツール	親からすべてのツールを継承します（`tools` フィールドを省略）

トラブルシューティング

Claude がサブエージェントに委譲していない

Claude がサブエージェントに委譲する代わりにタスクを直接完了する場合：

Agent ツールを含める: サブエージェントは Agent ツール経由で呼び出されるため、allowedTools に含める必要があります
明示的なプロンプトを使用する: プロンプトでサブエージェントを名前で言及します（例えば、「code-reviewer エージェントを使用して...」）
明確な説明を書く: サブエージェントをいつ使用すべきかを正確に説明し、Claude がタスクを適切にマッチングできるようにします

ファイルシステムベースのエージェントが読み込まれていない

.claude/agents/ で定義されたエージェントはスタートアップ時にのみ読み込まれます。Claude Code の実行中に新しいエージェントファイルを作成した場合、セッションを再起動して読み込んでください。

Windows：長いプロンプトの失敗

Windows では、非常に長いプロンプトを持つサブエージェントは、コマンドライン長の制限（8191 文字）により失敗する場合があります。プロンプトを簡潔に保つか、複雑な指示にはファイルシステムベースのエージェントを使用してください。

agent-sdk/subagents.md +601 −0 created

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# SDK のサブエージェント

7> サブエージェントを定義して呼び出し、コンテキストを分離し、タスクを並列実行し、Claude Agent SDK アプリケーションで特殊な指示を適用します。

9サブエージェントは、メインエージェントが生成できる個別のエージェントインスタンスで、焦点を絞ったサブタスクを処理します。

10サブエージェントを使用して、焦点を絞ったサブタスクのコンテキストを分離し、複数の分析を並列実行し、メインエージェントのプロンプトを肥大化させずに特殊な指示を適用します。

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

14## 概要

16サブエージェントは 3 つの方法で作成できます。

18* **プログラム的に**: `query()` オプションの `agents` パラメータを使用します（[TypeScript](/ja/agent-sdk/typescript#agentdefinition)、[Python](/ja/agent-sdk/python#agentdefinition)）

19* **ファイルシステムベース**: `.claude/agents/` ディレクトリ内のマークダウンファイルとしてエージェントを定義します（[ファイルとしてサブエージェントを定義する](/ja/sub-agents)を参照）

20* **組み込みの汎用**: Claude は、何も定義することなく、Agent ツールを介して組み込みの `general-purpose` サブエージェントをいつでも呼び出すことができます

22このガイドでは、SDK アプリケーションに推奨されるプログラム的なアプローチに焦点を当てています。

24サブエージェントを定義する場合、Claude は各サブエージェントの `description` フィールドに基づいて、それらを呼び出すかどうかを判断します。サブエージェントをいつ使用すべきかを説明する明確な説明を書いてください。Claude は自動的に適切なタスクを委譲します。プロンプトでサブエージェントを名前で明示的にリクエストすることもできます（例えば、「code-reviewer エージェントを使用して...」）。

26## サブエージェントを使用する利点

28### コンテキスト分離

30各サブエージェントは独自の新しい会話で実行されます。中間的なツール呼び出しと結果はサブエージェント内に留まり、最終メッセージだけが親に返されます。[サブエージェントが継承するもの](#what-subagents-inherit)を参照して、サブエージェントのコンテキストに正確に何が含まれているかを確認してください。

32**例:** `research-assistant` サブエージェントは、そのコンテンツがメイン会話に蓄積されることなく、数十のファイルを探索できます。親は、サブエージェントが読んだすべてのファイルではなく、簡潔なサマリーを受け取ります。

34### 並列化

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

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

40### 特殊な指示と知識

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

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

46### ツール制限

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

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

52## サブエージェントの作成

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

56`agents` パラメータを使用してコード内でサブエージェントを直接定義します。この例では、読み取り専用アクセスを持つコードレビュアーとコマンドを実行できるテストランナーの 2 つのサブエージェントを作成します。Claude がサブエージェントを Agent ツール経由で呼び出すため、`Agent` ツールを `allowedTools` に含める必要があります。

58<CodeGroup>

59 ```python Python theme={null}

60 import asyncio

61 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

64 async def main():

65 async for message in query(

66 prompt="Review the authentication module for security issues",

67 options=ClaudeAgentOptions(

68 # Agent tool is required for subagent invocation

69 allowed_tools=["Read", "Grep", "Glob", "Agent"],

70 agents={

71 "code-reviewer": AgentDefinition(

72 # description tells Claude when to use this subagent

73 description="Expert code review specialist. Use for quality, security, and maintainability reviews.",

74 # prompt defines the subagent's behavior and expertise

75 prompt="""You are a code review specialist with expertise in security, performance, and best practices.

77 When reviewing code:

78 - Identify security vulnerabilities

79 - Check for performance issues

80 - Verify adherence to coding standards

81 - Suggest specific improvements

83 Be thorough but concise in your feedback.""",

84 # tools restricts what the subagent can do (read-only here)

85 tools=["Read", "Grep", "Glob"],

86 # model overrides the default model for this subagent

87 model="sonnet",

88 ),

89 "test-runner": AgentDefinition(

90 description="Runs and analyzes test suites. Use for test execution and coverage analysis.",

91 prompt="""You are a test execution specialist. Run tests and provide clear analysis of results.

93 Focus on:

94 - Running test commands

95 - Analyzing test output

96 - Identifying failing tests

97 - Suggesting fixes for failures""",

98 # Bash access lets this subagent run test commands

99 tools=["Bash", "Read", "Grep"],

100 ),

101 },

102 ),

103 ):

104 if hasattr(message, "result"):

105 print(message.result)

106

107

108 asyncio.run(main())

109 ```

110

111 ```typescript TypeScript theme={null}

112 import { query } from "@anthropic-ai/claude-agent-sdk";

113

114 for await (const message of query({

115 prompt: "Review the authentication module for security issues",

116 options: {

117 // Agent tool is required for subagent invocation

118 allowedTools: ["Read", "Grep", "Glob", "Agent"],

119 agents: {

120 "code-reviewer": {

121 // description tells Claude when to use this subagent

122 description:

123 "Expert code review specialist. Use for quality, security, and maintainability reviews.",

124 // prompt defines the subagent's behavior and expertise

125 prompt: `You are a code review specialist with expertise in security, performance, and best practices.

126

127 When reviewing code:

128 - Identify security vulnerabilities

129 - Check for performance issues

130 - Verify adherence to coding standards

131 - Suggest specific improvements

132

133 Be thorough but concise in your feedback.`,

134 // tools restricts what the subagent can do (read-only here)

135 tools: ["Read", "Grep", "Glob"],

136 // model overrides the default model for this subagent

137 model: "sonnet"

138 },

139 "test-runner": {

140 description:

141 "Runs and analyzes test suites. Use for test execution and coverage analysis.",

142 prompt: `You are a test execution specialist. Run tests and provide clear analysis of results.

143

144 Focus on:

145 - Running test commands

146 - Analyzing test output

147 - Identifying failing tests

148 - Suggesting fixes for failures`,

149 // Bash access lets this subagent run test commands

150 tools: ["Bash", "Read", "Grep"]

151 }

152 }

153 }

154 })) {

155 if ("result" in message) console.log(message.result);

156 }

157 ```

158</CodeGroup>

159

160### AgentDefinition 設定

161

162| フィールド | 型 | 必須 | 説明 |

163| :---------------- | :---------------------------------------------------------- | :-- | :------------------------------------------------------------------------------------------------------------------- |

176

177Python SDK では、これらのフィールド名は wire フォーマットに一致するように camelCase を使用します。詳細については、[`AgentDefinition` リファレンス](/ja/agent-sdk/python#agentdefinition)を参照してください。

178

179<Note>

180 サブエージェントは独自のサブエージェントを生成することはできません。サブエージェントの `tools` 配列に `Agent` を含めないでください。

181</Note>

182

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

184

185`.claude/agents/` ディレクトリ内のマークダウンファイルとしてサブエージェントを定義することもできます。このアプローチの詳細については、[Claude Code サブエージェントドキュメント](/ja/sub-agents)を参照してください。プログラム的に定義されたエージェントは、同じ名前のファイルシステムベースのエージェントより優先されます。

186

187<Note>

188 カスタムサブエージェントを定義しなくても、`Agent` が `allowedTools` にある場合、Claude は組み込みの `general-purpose` サブエージェントを生成できます。これは、特殊なエージェントを作成せずに研究または探索タスクを委譲するのに便利です。

189</Note>

190

191## サブエージェントが継承するもの

192

193サブエージェントのコンテキストウィンドウは新しく開始されます（親の会話なし）が、空ではありません。親からサブエージェントへの唯一のチャネルは Agent ツールのプロンプト文字列なので、サブエージェントが必要とするファイルパス、エラーメッセージ、または決定をそのプロンプトに直接含めてください。

194

195| サブエージェントが受け取るもの | サブエージェントが受け取らないもの |

196| :------------------------------------------------------ | :-------------------------------------------------------- |

197| 独自のシステムプロンプト（`AgentDefinition.prompt`）と Agent ツールのプロンプト | 親の会話履歴またはツール結果 |

198| プロジェクト CLAUDE.md（`settingSources` 経由でロード） | プリロードされたスキルコンテンツ（`AgentDefinition.skills` にリストされている場合を除く） |

199| ツール定義（親から継承、または `tools` のサブセット） | 親のシステムプロンプト |

200

201<Note>

202 親はサブエージェントの最終メッセージを Agent ツール結果として逐語的に受け取りますが、独自の応答で要約する場合があります。サブエージェント出力を逐語的にユーザー向けの応答で保持するには、**メイン** `query()` 呼び出しに渡すプロンプトまたは `systemPrompt` オプションに指示を含めてください。

203</Note>

204

205## サブエージェントの呼び出し

206

207### 自動呼び出し

208

209Claude は、タスクと各サブエージェントの `description` に基づいて、サブエージェントをいつ呼び出すかを自動的に決定します。例えば、説明が「クエリチューニング用のパフォーマンス最適化スペシャリスト」である `performance-optimizer` サブエージェントを定義した場合、プロンプトでクエリの最適化について言及すると、Claude はそれを呼び出します。

210

211Claude がタスクを正しいサブエージェントにマッチングできるように、明確で具体的な説明を書いてください。

212

213### 明示的な呼び出し

214

215Claude が特定のサブエージェントを使用することを保証するには、プロンプトで名前を言及してください。

216

217```text theme={null}

218"Use the code-reviewer agent to check the authentication module"

219```

220

221これは自動マッチングをバイパスし、名前付きサブエージェントを直接呼び出します。

222

223### 動的エージェント設定

224

225実行時の条件に基づいて、エージェント定義を動的に作成できます。この例では、異なる厳密性レベルを持つセキュリティレビュアーを作成し、厳密なレビューにはより強力なモデルを使用します。

226

227<CodeGroup>

228 ```python Python theme={null}

229 import asyncio

230 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

231

232

233 # Factory function that returns an AgentDefinition

234 # This pattern lets you customize agents based on runtime conditions

235 def create_security_agent(security_level: str) -> AgentDefinition:

236 is_strict = security_level == "strict"

237 return AgentDefinition(

238 description="Security code reviewer",

239 # Customize the prompt based on strictness level

240 prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",

241 tools=["Read", "Grep", "Glob"],

242 # Key insight: use a more capable model for high-stakes reviews

243 model="opus" if is_strict else "sonnet",

244 )

245

246

247 async def main():

248 # The agent is created at query time, so each request can use different settings

249 async for message in query(

250 prompt="Review this PR for security issues",

251 options=ClaudeAgentOptions(

252 allowed_tools=["Read", "Grep", "Glob", "Agent"],

253 agents={

254 # Call the factory with your desired configuration

255 "security-reviewer": create_security_agent("strict")

256 },

257 ),

258 ):

259 if hasattr(message, "result"):

260 print(message.result)

261

262

263 asyncio.run(main())

264 ```

265

266 ```typescript TypeScript theme={null}

267 import { query, type AgentDefinition } from "@anthropic-ai/claude-agent-sdk";

268

269 // Factory function that returns an AgentDefinition

270 // This pattern lets you customize agents based on runtime conditions

271 function createSecurityAgent(securityLevel: "basic" | "strict"): AgentDefinition {

272 const isStrict = securityLevel === "strict";

273 return {

274 description: "Security code reviewer",

275 // Customize the prompt based on strictness level

276 prompt: `You are a ${isStrict ? "strict" : "balanced"} security reviewer...`,

277 tools: ["Read", "Grep", "Glob"],

278 // Key insight: use a more capable model for high-stakes reviews

279 model: isStrict ? "opus" : "sonnet"

280 };

281 }

282

283 // The agent is created at query time, so each request can use different settings

284 for await (const message of query({

285 prompt: "Review this PR for security issues",

286 options: {

287 allowedTools: ["Read", "Grep", "Glob", "Agent"],

288 agents: {

289 // Call the factory with your desired configuration

290 "security-reviewer": createSecurityAgent("strict")

291 }

292 }

293 })) {

294 if ("result" in message) console.log(message.result);

295 }

296 ```

297</CodeGroup>

298

299## サブエージェント呼び出しの検出

300

301サブエージェントは Agent ツール経由で呼び出されます。サブエージェントが呼び出されたときを検出するには、`name` が `"Agent"` である `tool_use` ブロックをチェックしてください。サブエージェントのコンテキスト内からのメッセージには `parent_tool_use_id` フィールドが含まれます。

302

303<Note>

304 ツール名は Claude Code v2.1.63 で `"Task"` から `"Agent"` に変更されました。現在の SDK リリースは `tool_use` ブロックで `"Agent"` を出力しますが、`system:init` ツールリストと `result.permission_denials[].tool_name` では引き続き `"Task"` を使用します。SDK バージョン全体での互換性を確保するために、`block.name` で両方の値をチェックしてください。

305</Note>

306

307この例は、ストリーミングされたメッセージを反復処理し、サブエージェントが呼び出されたときと、その後のメッセージがそのサブエージェントの実行コンテキスト内から発信されたときをログに記録します。

308

309<Note>

310 メッセージ構造は SDK 間で異なります。Python では、コンテンツブロックは `message.content` 経由で直接アクセスされます。TypeScript では、`SDKAssistantMessage` が Claude API メッセージをラップするため、コンテンツは `message.message.content` 経由でアクセスされます。

311</Note>

312

313<CodeGroup>

314 ```python Python theme={null}

315 import asyncio

316 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

317

318

319 async def main():

320 async for message in query(

321 prompt="Use the code-reviewer agent to review this codebase",

322 options=ClaudeAgentOptions(

323 allowed_tools=["Read", "Glob", "Grep", "Agent"],

324 agents={

325 "code-reviewer": AgentDefinition(

326 description="Expert code reviewer.",

327 prompt="Analyze code quality and suggest improvements.",

328 tools=["Read", "Glob", "Grep"],

329 )

330 },

331 ),

332 ):

333 # Check for subagent invocation. Match both names: older SDK

334 # versions emitted "Task", current versions emit "Agent".

335 if hasattr(message, "content") and message.content:

336 for block in message.content:

337 if getattr(block, "type", None) == "tool_use" and block.name in (

338 "Task",

339 "Agent",

340 ):

341 print(f"Subagent invoked: {block.input.get('subagent_type')}")

342

343 # Check if this message is from within a subagent's context

344 if hasattr(message, "parent_tool_use_id") and message.parent_tool_use_id:

345 print(" (running inside subagent)")

346

347 if hasattr(message, "result"):

348 print(message.result)

349

350

351 asyncio.run(main())

352 ```

353

354 ```typescript TypeScript theme={null}

355 import { query } from "@anthropic-ai/claude-agent-sdk";

356

357 for await (const message of query({

358 prompt: "Use the code-reviewer agent to review this codebase",

359 options: {

360 allowedTools: ["Read", "Glob", "Grep", "Agent"],

361 agents: {

362 "code-reviewer": {

363 description: "Expert code reviewer.",

364 prompt: "Analyze code quality and suggest improvements.",

365 tools: ["Read", "Glob", "Grep"]

366 }

367 }

368 }

369 })) {

370 const msg = message as any;

371

372 // Check for subagent invocation. Match both names: older SDK versions

373 // emitted "Task", current versions emit "Agent".

374 for (const block of msg.message?.content ?? []) {

375 if (block.type === "tool_use" && (block.name === "Task" || block.name === "Agent")) {

376 console.log(`Subagent invoked: ${block.input.subagent_type}`);

377 }

378 }

379

380 // Check if this message is from within a subagent's context

381 if (msg.parent_tool_use_id) {

382 console.log(" (running inside subagent)");

383 }

384

385 if ("result" in message) {

386 console.log(message.result);

387 }

388 }

389 ```

390</CodeGroup>

391

392## サブエージェントの再開

393

394サブエージェントを再開して、中断したところから続行できます。再開されたサブエージェントは、以前のすべてのツール呼び出し、結果、推論を含む完全な会話履歴を保持します。サブエージェントは新しく開始するのではなく、停止したところから正確に再開します。

395

396サブエージェントが完了すると、Claude は Agent ツール結果でエージェント ID を受け取ります。サブエージェントをプログラム的に再開するには：

397

3981. **セッション ID をキャプチャする**: 最初のクエリ中にメッセージから `session_id` を抽出します

3992. **エージェント ID を抽出する**: メッセージコンテンツから `agentId` を解析します

4003. **セッションを再開する**: 2 番目のクエリのオプションで `resume: sessionId` を渡し、プロンプトにエージェント ID を含めます

401

402<Note>

403 サブエージェントのトランスクリプトにアクセスするには、同じセッションを再開する必要があります。各 `query()` 呼び出しはデフォルトで新しいセッションを開始するため、同じセッションで続行するには `resume: sessionId` を渡してください。

404

405 カスタムエージェント（組み込みエージェントではない）を使用している場合は、両方のクエリで `agents` パラメータに同じエージェント定義を渡す必要もあります。

406</Note>

407

408以下の例は、このフローを示しています。最初のクエリはサブエージェントを実行してセッション ID とエージェント ID をキャプチャし、2 番目のクエリはセッションを再開して、最初の分析からのコンテキストが必要なフォローアップ質問をします。

409

410<CodeGroup>

411 ```typescript TypeScript theme={null}

412 import { query, type SDKMessage } from "@anthropic-ai/claude-agent-sdk";

413

414 // Helper to extract agentId from message content

415 // Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.)

416 function extractAgentId(message: SDKMessage): string | undefined {

417 if (!("message" in message)) return undefined;

418 // Stringify the content so we can search it without traversing nested blocks

419 const content = JSON.stringify(message.message.content);

420 const match = content.match(/agentId:\s*([a-f0-9-]+)/);

421 return match?.[1];

422 }

423

424 let agentId: string | undefined;

425 let sessionId: string | undefined;

426

427 // First invocation - use the Explore agent to find API endpoints

428 for await (const message of query({

429 prompt: "Use the Explore agent to find all API endpoints in this codebase",

430 options: { allowedTools: ["Read", "Grep", "Glob", "Agent"] }

431 })) {

432 // Capture session_id from ResultMessage (needed to resume this session)

433 if ("session_id" in message) sessionId = message.session_id;

434 // Search message content for the agentId (appears in Agent tool results)

435 const extractedId = extractAgentId(message);

436 if (extractedId) agentId = extractedId;

437 // Print the final result

438 if ("result" in message) console.log(message.result);

439 }

440

441 // Second invocation - resume and ask follow-up

442 if (agentId && sessionId) {

443 for await (const message of query({

444 prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`,

445 options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], resume: sessionId }

446 })) {

447 if ("result" in message) console.log(message.result);

448 }

449 }

450 ```

451

452 ```python Python theme={null}

453 import asyncio

454 import json

455 import re

456 from claude_agent_sdk import query, ClaudeAgentOptions

457

458

459 def extract_agent_id(text: str) -> str | None:

460 """Extract agentId from Agent tool result text."""

461 match = re.search(r"agentId:\s*([a-f0-9-]+)", text)

462 return match.group(1) if match else None

463

464

465 async def main():

466 agent_id = None

467 session_id = None

468

469 # First invocation - use the Explore agent to find API endpoints

470 async for message in query(

471 prompt="Use the Explore agent to find all API endpoints in this codebase",

472 options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"]),

473 ):

474 # Capture session_id from ResultMessage (needed to resume this session)

475 if hasattr(message, "session_id"):

476 session_id = message.session_id

477 # Search message content for the agentId (appears in Agent tool results)

478 if hasattr(message, "content"):

479 # Stringify the content so we can search it without traversing nested blocks

480 content_str = json.dumps(message.content, default=str)

481 extracted = extract_agent_id(content_str)

482 if extracted:

483 agent_id = extracted

484 # Print the final result

485 if hasattr(message, "result"):

486 print(message.result)

487

488 # Second invocation - resume and ask follow-up

489 if agent_id and session_id:

490 async for message in query(

491 prompt=f"Resume agent {agent_id} and list the top 3 most complex endpoints",

492 options=ClaudeAgentOptions(

493 allowed_tools=["Read", "Grep", "Glob", "Agent"], resume=session_id

494 ),

495 ):

496 if hasattr(message, "result"):

497 print(message.result)

498

499

500 asyncio.run(main())

501 ```

502</CodeGroup>

503

504サブエージェントのトランスクリプトはメイン会話とは独立して永続化されます。

505

506* **メイン会話の圧縮**: メイン会話が圧縮されると、サブエージェントのトランスクリプトは影響を受けません。これらは別のファイルに保存されます。

507* **セッション永続化**: サブエージェントのトランスクリプトはセッション内で永続化されます。同じセッションを再開することで、Claude Code を再起動した後にサブエージェントを再開できます。

508* **自動クリーンアップ**: トランスクリプトは `cleanupPeriodDays` 設定に基づいてクリーンアップされます（デフォルト：30 日）。

509

510## ツール制限

511

512サブエージェントは `tools` フィールド経由で制限されたツールアクセスを持つことができます。

513

514* **フィールドを省略**: エージェントは利用可能なすべてのツールを継承します（デフォルト）

515* **ツールを指定**: エージェントはリストされたツールのみを使用できます

516

517この例では、コードを検査できるが、ファイルを変更したりコマンドを実行したりできない読み取り専用分析エージェントを作成します。

518

519<CodeGroup>

520 ```python Python theme={null}

521 import asyncio

522 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

523

524

525 async def main():

526 async for message in query(

527 prompt="Analyze the architecture of this codebase",

528 options=ClaudeAgentOptions(

529 allowed_tools=["Read", "Grep", "Glob", "Agent"],

530 agents={

531 "code-analyzer": AgentDefinition(

532 description="Static code analysis and architecture review",

533 prompt="""You are a code architecture analyst. Analyze code structure,

534 identify patterns, and suggest improvements without making changes.""",

535 # Read-only tools: no Edit, Write, or Bash access

536 tools=["Read", "Grep", "Glob"],

537 )

538 },

539 ),

540 ):

541 if hasattr(message, "result"):

542 print(message.result)

543

544

545 asyncio.run(main())

546 ```

547

548 ```typescript TypeScript theme={null}

549 import { query } from "@anthropic-ai/claude-agent-sdk";

550

551 for await (const message of query({

552 prompt: "Analyze the architecture of this codebase",

553 options: {

554 allowedTools: ["Read", "Grep", "Glob", "Agent"],

555 agents: {

556 "code-analyzer": {

557 description: "Static code analysis and architecture review",

558 prompt: `You are a code architecture analyst. Analyze code structure,

559 identify patterns, and suggest improvements without making changes.`,

560 // Read-only tools: no Edit, Write, or Bash access

561 tools: ["Read", "Grep", "Glob"]

562 }

563 }

564 }

565 })) {

566 if ("result" in message) console.log(message.result);

567 }

568 ```

569</CodeGroup>

570

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

572

573| ユースケース | ツール | 説明 |

574| :------- | :---------------------------------- | :--------------------------------- |

575| 読み取り専用分析 | `Read`、`Grep`、`Glob` | コードを検査できますが、変更または実行はできません |

576| テスト実行 | `Bash`、`Read`、`Grep` | コマンドを実行し、出力を分析できます |

577| コード変更 | `Read`、`Edit`、`Write`、`Grep`、`Glob` | コマンド実行なしで完全な読み取り/書き込みアクセス |

578| 完全アクセス | すべてのツール | 親からすべてのツールを継承します（`tools` フィールドを省略） |

579

580## トラブルシューティング

581

582### Claude がサブエージェントに委譲していない

583

584Claude がサブエージェントに委譲する代わりにタスクを直接完了する場合：

585

5861. **Agent ツールを含める**: サブエージェントは Agent ツール経由で呼び出されるため、`allowedTools` に含める必要があります

5872. **明示的なプロンプトを使用する**: プロンプトでサブエージェントを名前で言及します（例えば、「code-reviewer エージェントを使用して...」）

5883. **明確な説明を書く**: サブエージェントをいつ使用すべきかを正確に説明し、Claude がタスクを適切にマッチングできるようにします

589

590### ファイルシステムベースのエージェントが読み込まれていない

591

592`.claude/agents/` で定義されたエージェントはスタートアップ時にのみ読み込まれます。Claude Code の実行中に新しいエージェントファイルを作成した場合、セッションを再起動して読み込んでください。

593

594### Windows：長いプロンプトの失敗

595

596Windows では、非常に長いプロンプトを持つサブエージェントは、コマンドライン長の制限（8191 文字）により失敗する場合があります。プロンプトを簡潔に保つか、複雑な指示にはファイルシステムベースのエージェントを使用してください。

597

598## 関連ドキュメント

599

600* [Claude Code サブエージェント](/ja/sub-agents)：ファイルシステムベースの定義を含む包括的なサブエージェントドキュメント

601* [SDK 概要](/ja/agent-sdk/overview)：Claude Agent SDK の開始方法

agent-sdk/subagents.md 2026-05-07 22:59 UTC to 2026-05-08 22:00 UTC

SDK のサブエージェント

概要

サブエージェントを使用する利点

コンテキスト分離

並列化

特殊な指示と知識

ツール制限

サブエージェントの作成

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

AgentDefinition 設定

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

サブエージェントが継承するもの

サブエージェントの呼び出し

自動呼び出し

明示的な呼び出し

動的エージェント設定

サブエージェント呼び出しの検出

サブエージェントの再開

ツール制限

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

トラブルシューティング

Claude がサブエージェントに委譲していない

ファイルシステムベースのエージェントが読み込まれていない

Windows：長いプロンプトの失敗

関連ドキュメント