Subagents in the SDK

概要

Claude Agent SDK でサブエージェントを定義・起動する機能。コンテキストの分離、並列実行、専門的な指示の適用に使う。

仕様

作成方法

方法	説明
プログラム定義（推奨）	`query()` の `agents` オプションに `AgentDefinition` を渡す
ファイル定義	`.claude/agents/` ディレクトリに Markdown ファイルを配置
組み込み `general-purpose`	定義不要。Claude がいつでも Agent ツール経由で起動可能

プログラム定義がファイル定義より優先される（同名の場合）。

AgentDefinition フィールド

フィールド	型	必須	説明
`description`	`string`	○	Claude がこのエージェントをいつ使うかを判断するための説明
`prompt`	`string`	○	サブエージェントのシステムプロンプト
`tools`	`string[]`	—	許可するツール名の配列。省略するとサブエージェントが利用可能な全ツールを継承
`disallowedTools`	`string[]`	—	除外するツール名の配列。`mcp__server`・`mcp__server__`・`mcp__` パターンも可
`model`	`string`	—	モデル上書き。`'opus'`・`'sonnet'`・`'haiku'`・`'inherit'` 等のエイリアスまたは完全なモデルID
`skills`	`string[]`	—	起動時にコンテキストへプリロードするスキル名のリスト
`memory`	`'user' \| 'project' \| 'local'`	—	メモリソース
`mcpServers`	`(string \| object)[]`	—	利用可能な MCP サーバー（名前またはインライン設定）
`initialPrompt`	`string`	—	メインスレッドエージェントとして動作する場合のみ最初のユーザーターンとして自動送信。サブエージェント呼び出し時は無視
`maxTurns`	`number`	—	エージェントが停止するまでの最大ターン数
`background`	`boolean`	—	`true` にすると呼び出し時に非ブロッキングのバックグラウンドタスクとして実行
`effort`	`'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number`	—	推論努力レベル
`permissionMode`	`PermissionMode`	—	このエージェント内のツール実行に使うパーミッションモード

Python SDK では disallowedTools・mcpServers 等は snake_case ではなく camelCase のまま。

コンテキスト継承

サブエージェントが受け取るもの	サブエージェントが受け取らないもの
自身のシステムプロンプト（`AgentDefinition.prompt`）と Agent ツールのプロンプト	親の会話履歴・ツール結果
プロジェクトの `CLAUDE.md`（`settingSources` に `project` を含む場合）	事前ロード済みスキルコンテンツ（`AgentDefinition.skills` に明示した場合を除く）
ツール定義（親から継承、または `tools` フィールドで指定したサブセット）	親のシステムプロンプト

親はサブエージェントの最終メッセージのみを受け取る（中間のツール呼び出しや結果は親のコンテキストに蓄積しない）。

Agent ツール名の変更

Claude Code v2.1.63 より前: ツール名は "Task"
Claude Code v2.1.63 以降: ツール名は "Agent"
現在の SDK は tool_use ブロックで "Agent" を出力するが、system:init のツールリストと result.permission_denials[].tool_name では引き続き "Task" を使用

呼び出し方法

自動呼び出し: description に基づいて Claude が適切なサブエージェントを選択
明示的呼び出し: プロンプトにエージェント名を含める（例: "Use the code-reviewer agent to..."）
Agent を allowedTools に含めると、サブエージェント起動が自動承認される

バックグラウンド実行（v2.1.198 以降での変更）

v2.1.198 以降: デフォルトでサブエージェントはバックグラウンド実行
run_in_background: false を Agent ツール入力に指定すると同期実行
AgentDefinition.background: true で常にバックグラウンド強制実行
v2.1.198 以降: サブエージェントは親セッションの extended thinking 設定を継承

サブエージェントの再開

最初のクエリで ResultMessage から session_id を取得
Agent ツール結果テキストから agentId: <id> を解析
2番目のクエリで resume: sessionId オプションを渡し、プロンプトにエージェントIDを含める

組み込みの Explore・Plan エージェントは agentId を返さないため再開不可
再開には同一セッションIDが必要（query() はデフォルトで新セッションを作成するため resume を指定する）
サブエージェントのトランスクリプトは別ファイルに保存され、メイン会話とは独立して保持される

出力スキャン（v2.1.210 以降）

Claude Code はサブエージェントの最終メッセージを親が読む前にスキャンする:

パターン種別	処理内容
Control-tag の模倣（`<system-reminder>` 等、ハーネスのみが出力するタグ）	開き山括弧の直後にバックスラッシュを挿入。`[harness: ...]` マーカーを先頭に追加
パーミッション設定への言及（`.claude/settings.json`・`bypassPermissions` 等）	そのまま保持。`[harness: ...]` マーカーを先頭に追加
ターンマーカー（行頭の `Human:` または `Assistant:`）	コロンの前にバックスラッシュを挿入（マーカー行は追加しない）

テキストの削除・言い換えは行わない。

SendMessage ツール（v2.1.206 以降）

SendMessage ツールを持つサブエージェントは、セッション内の他の名前付きエージェントのリストを最初のターンに受け取る。フォーク（fork_session）の場合は受け取らない。

実行制限

制限	設定方法	デフォルト	上限到達時の動作
深さ	環境変数 `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`	`3`（メインエージェントの下に3層）	最深層のサブエージェントが自前で処理
同時実行数	環境変数 `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`	`20`	`Concurrent subagent limit reached` を返す（ultracode アクティブ時は拒否しない）
費用	TypeScript: `maxBudgetUsd`、Python: `max_budget_usd`	制限なし	追加サブエージェントの起動拒否・バックグラウンドサブエージェント停止・`error_max_budget_usd` サブタイプでクエリ終了

TypeScript SDK では env オプションがサブプロセス環境を置き換えるため、...process.env をスプレッドして PATH 等を保持する
Python SDK では env が既存の環境変数にマージされる
費用は total_cost_usd と比較（サブエージェントのリクエストも加算される）
上記の制限は TypeScript SDK v0.3.219 / Python SDK v0.2.127 以降（Claude Code v2.1.219 以降をバンドル）が必要

Claude Opus 5 とサブエージェント

claude_code システムプロンプトプリセット使用時: モデルが Opus 5 の場合、Claude Code が「Agent ツールは指示された場合のみ使う」旨を自動的にシステムプロンプトに追加
カスタムプロンプトまたは systemPrompt なしの場合: 上記の一行は追加されない。Opus 5 プロンプトエンジニアリングガイドの委譲指示を自分で追加する

大規模ワークフロー

多数のエージェントを調整する場合は Workflow ツールを使う（TypeScript Agent SDK v0.3.149 以降）。allowedTools に Workflow を含めると自動承認される。

制約・注意点

allowed_tools / allowedTools に Agent を含めないと、サブエージェント呼び出しは canUseTool コールバックに渡されるか、dontAsk モードでは拒否される
親はサブエージェントの最終メッセージを要約する場合がある。逐語的に保持したい場合は query() の systemPrompt オプションに指示を追加する
API エラー（レートリミット等）でサブエージェントが早期終了した場合、そのエラーは Agent ツールの結果として返されない
ファイルシステムベースのエージェント: 新しいディレクトリに最初のファイルが置かれた場合、セッション再起動が必要。--disable-slash-commands で開始されたセッションはディレクトリを監視しない
プログラム定義のエージェントは同名のファイルシステムベースのエージェントより優先される