何のためのものか
SDK でサブエージェントを定義・起動する機能。コンテキストの分離、並列実行、専門的な指示の適用に使う。
触る
作り方は 3 通り。
| 方法 | 説明 |
|---|---|
| プログラム定義（推奨） | query() の agents オプションに AgentDefinition を渡す |
| ファイル定義 | .claude/agents/ に Markdown を置く |
組み込み general-purpose | 定義不要 |
同名ならプログラム定義がファイル定義より優先される。
必須は description（Claude がいつ使うかを判断する）と prompt（システムプロンプト）の 2 つだけ。
入れる
絞るフィールドを足す。
tools/disallowedTools— 省略するとサブエージェントが利用可能な全ツールを継承するmodel—'opus'/'sonnet'/'haiku'/'inherit'または完全なモデル IDskills— 起動時にコンテキストへプリロードするスキル名maxTurns/effort/permissionMode/background
Python SDK でも disallowedTools や mcpServers は camelCase のまま。
呼び出しは description に基づく自動選択のほか、プロンプトにエージェント名を含めれば明示的に呼べる。Agent を allowedTools に含めると起動が自動承認される。
効かせる
- 継承されるものとされないものを押さえる。 受け取るのは自身のシステムプロンプトと Agent ツールのプロンプト、（
settingSourcesにprojectを含む場合）プロジェクトのCLAUDE.md、ツール定義。受け取らないのは親の会話履歴・ツール結果・親のシステムプロンプト、そしてskillsに明示していないスキル内容 - 親が受け取るのは最終メッセージだけ。 中間のツール呼び出しや結果は親のコンテキストに蓄積しない
- v2.1.198 以降は既定でバックグラウンド実行。 同期にしたいなら Agent ツール入力に
run_in_background: false、常にバックグラウンドにしたいならAgentDefinition.background: true - 再開するには 3 手順。
ResultMessageからsession_idを取り、Agent ツール結果テキストからagentId: <id>を解析し、次のクエリでresume: sessionIdを渡してプロンプトにエージェント ID を含める
落とし穴
- 組み込みの
Explore/PlanはagentIdを返さないため再開できない query()は既定で新セッションを作る。 再開にはresumeの指定が要る- ツール名の履歴に注意。 現在の SDK は
tool_useブロックで"Agent"を出すが、system:initのツールリストとresult.permission_denials[].tool_nameでは引き続き"Task"を使う initialPromptはメインスレッドエージェントとして動く場合のみ効き、サブエージェント呼び出し時は無視される