Skip to main content
サブエージェントは、Droid が Task ツールを通じて起動し、作業の一部を集中的に処理させる別個のエージェントです。各サブエージェントは独自のコンテキストウィンドウと独立したセッションで動作し、独自のシステムプロンプト、ツールポリシー、モデル、自律レベルを持ちます。完了すると、親エージェントに1つの最終メッセージを返します。 サブエージェントには2種類あります。
  • 組み込みサブエージェント – すぐに使える workerexplorer
  • カスタム Droid – Markdown ファイルとして定義する再利用可能なサブエージェント。チーム固有のレビュー、テスト、リサーチ、リリースチェックリストをコードとして保存し、1回の呼び出しで委任できます。

1 · サブエージェントとは

サブエージェントを使うと、プライマリアシスタントは自分のコンテキストウィンドウを汚さずに、重い作業や並列化しやすい作業を委任できます。親がタスクを説明し、サブエージェントが隔離された環境で実行して結果を報告します。
  • コンテキストの分離 – 各サブエージェントは新しいコンテキストウィンドウで動作するため、親は焦点を保ったまま軽量に維持できます。
  • 独自のツールと自律性 – サブエージェントは読み取り専用、編集専用、または厳選したツールセットに制限でき、独自の自律レベルで実行されます。
  • 独自のモデル – 親のモデルを継承することも、タスクに合わせた別のモデルを使うこともできます。
  • 単一の戻り値 – サブエージェントは最終メッセージを1つだけ返します。親が要約しない限り、その結果がユーザーに直接表示されることはありません。
サブエージェントは非対話型で動作します。AskUser ツールはサブエージェントでは無効化されており、サブエージェント自身がさらにサブエージェントを起動することもできません(Task ツールは利用不可)。不明点やブロッカーがある場合は、問い合わせずに親へ報告します。

カスタム Droid

カスタム Droid は、プロジェクトの .factory/droids/ または個人用の ~/.factory/droids/ ディレクトリ配下にある .md ファイルとして管理されます。CLI はこれらのフォルダをスキャンし(トップレベルファイルのみ)、各定義を検証して、Task ツール用の subagent_type ターゲットとして公開します。
  • プロジェクト Droid<repo>/.factory/droids/ に置かれ、チームメンバーと共有されます。
  • 個人 Droid~/.factory/droids/ に保存され、ワークスペースをまたいで利用できます。
  • 名前が一致する場合は、プロジェクト定義が個人定義を上書きします。
カスタム Droid はデフォルトで有効です。必要に応じて Settings(/settings)の Experimental セクションでオフにできます。

2 · サブエージェントの仕組み

親エージェントは Task ツールでサブエージェントを呼び出します。主な入力は次のとおりです。

フォアグラウンドとバックグラウンド

  • フォアグラウンド(デフォルト) – 親はサブエージェントの完了を待ちます。Task ツールは、サブエージェント実行中のツール呼び出し、結果、TodoWrite 更新をライブ表示し、最後に最終メッセージを返します。
  • バックグラウンド(run_in_background: true – Task ツールは task_id を返してすぐに戻り、サブエージェントは独立して実行を続けます。本当に独立した並列作業がある場合に使います。完了時には親に通知されます。

バックグラウンドタスクの確認

サブエージェントをバックグラウンド実行にした後は、親は次の2つの補助ツールで管理します。
  • TaskOutput – バックグラウンドタスクの出力を取得します。block=true で完了まで待って結果を取得し、block=false で待たずに現在の状態をポーリングできます。起動時に返された task_id を指定します。
  • TaskStop – 実行中のバックグラウンドタスクを task_id で停止します(必要に応じて SIGTERM の後に SIGKILL を送信)。
親は「あとでユーザーに通知されるはず」とみなすのではなく、TaskOutput を使って自分で結果を取得することが想定されています。

以前のサブエージェントを再開する

既存のサブエージェントセッションに追加入力を送るには、以前の task_idresume に指定します。サブエージェントは過去の完全なコンテキスト(会話履歴)を保持し、新しいターンでは親の現在の自律レベルに合わせて再調整されます。これはフォアグラウンド実行とバックグラウンド実行の両方で使えます。

サブエージェントを並列実行する

サブエージェントを並行して動かすには、親が同じターン内で複数の Task ツール呼び出しを行うか、run_in_background: true で複数起動してから TaskOutput で結果を回収します。

3 · 組み込みサブエージェント

Droid には汎用的な組み込みサブエージェントが2つ含まれており、設定なしでいつでも利用できます。 組み込みサブエージェントはデフォルトで親のモデルを継承するため、複雑さ → モデルのルーティングが設定されている場合は、そのデフォルトの complexity に応じて使用モデルが決まります(workermediumexplorerlight)。ただし、親が明示的に complexity を渡した場合はその値が優先されます。
追加の組み込み Droid(例: scrutiny-feature-revieweruser-testing-flow-validator)も一部ありますが、これらは Missions の検証内で使うために ~/.factory/droids/ に書き込まれるもので、一般的な委任用途は想定されていません。

4 · 自律レベルの制御

サブエージェントもメインセッションと同様に自律レベルで実行されます(OffLowMediumHigh。詳しくは 自律レベル を参照)。制御は /settingsSubagents にある Subagent autonomy level 設定で行います。 注記:
  • 解決されるレベルは常に組織の Maximum Autonomy Level によって上限がかかるため、明示的な設定でもエンタープライズ上限を超えることはありません。
  • 親セッションが Spec Mode の場合、サブエージェントは読み取り専用操作と低リスクのシェルコマンドのみに制限され、ファイル編集とファイル作成は無効になります。
  • resume 時には、サブエージェントの自律レベルはフォローアップターン用に親の現在のレベルへ再調整されます。

5 · モデルの制御

各サブエージェントのモデルは、その droid 設定と親の複雑さルーティングを組み合わせて決定されます。
  1. droid 設定の model – droid の frontmatter に model を設定して特定のモデルに固定するか、inherit(デフォルト)で親に委ねます。
    • 組み込みモデル ID の例: claude-sonnet-4-5-20250929利用可能なモデル を参照してください。
    • カスタム(BYOK)モデル: model_display_name ではなく、設定内の model フィールドに custom: を付けて使用します(例: custom:gpt-4o-mini)。
  2. 複雑さ → モデルのルーティング – droid の modelinherit で、親が complexity を渡した場合、Droid は /settingsSubagents で設定したルーティングに基づいて、その複雑さに対応するモデルへマッピングします。
    • Light task modelMedium task modelHeavy task model は、それぞれの complexity に対して特定のモデル(必要に応じて reasoning effort 付き)を割り当てます。Inherit のままにすると、起動元セッションのモデルを使用します。各ティアは具体的なモデルにも、Auto モデルルーターにも向けられます。
  3. 継承時のフォールバック – 明示的なルーティングがない場合、サブエージェントは親セッションで現在有効なモデルと reasoning effort を使います。
  4. 検証時のフォールバック – droid が許可されていないモデル(組織ポリシーでブロックされたモデルや、未設定の BYOK モデルなど)を固定している場合、Droid は失敗する代わりに親のモデルへフォールバックします。
優先順位は 明示的な droid の model複雑さ → モデルのルーティングinherit + complexity の場合)→ 親のモデル です。
組み込みの workerexplorermodel: inherit を使用するため、親が complexity を上書きしない限り、それぞれのデフォルトティア(medium / light)に基づいて複雑さ → モデルのルーティングに従います。
モデルが対応している場合は、droid の frontmatter で reasoningEffort(例: lowmediumhigh)も設定できます。modelinherit の場合は無視され、選択したモデルと互換性がある必要があります。

6 · Enterprise の制御

管理者は、組織管理設定 を通じて、サブエージェントの自律性とモデルを一元管理できます。組織レベルの値はユーザー、プロジェクト、フォルダ設定より優先され、下位レベルで弱めることはできません。
  • subagentAutonomyLevel – Task で起動されるすべてのサブエージェントの自律レベルを固定します(offlowmediumhighinherit)。
  • maxAutonomyLevel – すべてのセッションとサブエージェントの自律性に上限を設けます。解決されるサブエージェントのレベルは常にこの最大値に制限されるため、ユーザーやプロジェクトの設定が組織上限を超えることはありません。
  • subagentModelSettings – complexity ごとのモデルルーティング(lightModelmediumModelheavyModel と任意の reasoning effort)を固定し、サブエージェントが承認済みモデルで動作するようにします。
  • モデルポリシー – droid が組織ポリシーでブロックされているモデルを固定した場合、そのモデルを使う代わりに親のモデルへフォールバックします。
  • ツールと MCP のポリシー – Droid のツールポリシーと Enterprise MCP ポリシー はサブエージェントにも適用されます。組織レベルでブロックされたサーバーやツールは、droid が列挙していても利用できません。
管理設定スキーマ全体と優先順位のルールについては、階層設定と組織管理 を参照してください。

7 · 独自のカスタム Droid を作成する

  1. /droids を実行して Droids メニューを開きます。
  2. Create a new Droid を選択し、保存場所(プロジェクトまたは個人)を選んで、ウィザードに従って以下を設定します。
    • droid が実行すべきことの説明
    • システムプロンプト(自動生成または手動編集)
    • 識別子(droid の名前)
    • モデル(または親セッションから継承)
    • ツール(ツール ID の明示的なリストまたはカテゴリ)
  3. 保存します。CLI は選択した droids/ ディレクトリに <name>.md を書き込み、ファイル名を正規化します(小文字、ハイフン区切り)。
  4. droid に使用を依頼します。例: 「サブエージェント code-reviewer で Task ツールを実行してこの diff をレビューして」、または自動化からトリガーします。
droid ファイルの変更は、次回のメニュー表示または Task ツール呼び出し時に反映されます。

AI による droid 生成

システムプロンプトを手書きしたくありませんか? Droid には、短い説明から完全なカスタム droid 設定を作成する GenerateDroid ツールが組み込まれています。droid に何をさせたいかを記述するだけで(例:「Node.js サービスに焦点を当てて、セキュリティ問題のために PR をレビューする」)、Droid は以下を行います:
  • 正規化された name を提案
  • 焦点を絞ったシステムプロンプトを起草
  • 適切な tools セットと model を選択
  • 結果の .md ファイルを選択したプロジェクトまたは個人の場所に保存
次の 2 つの方法で呼び出せます:
  • /droidsCreate a new Droid ウィザードから、AI 生成プロンプトオプションを選び、説明を入力します。
  • アシスタントに直接依頼します:「GenerateDroid を使って…するdroid を作って」と伝え、location: project または location: personal を渡してファイルの保存先を制御します。
これは新しい droid を雛形作成する最速の方法です。生成された .md ファイルはいつでも開いて、プロンプト、モデル、ツールリストを後から調整できます。

8 · 設定

各droid ファイルは YAML frontmatter を持つMarkdown です。
より細かい制御のため、ツールを配列として指定することもできます:
主要なメタデータフィールド: プロンプトは少なくとも name を含むYAML frontmatter で始まり、空でない本文を含む必要があります。DroidValidator はエラー(無効な名前、未知のモデル、未知のツール)と警告(説明の欠落、重複したツール)を表示します。検証の問題は、ファイルの読み込みに失敗した際にCLI ログに表示されます。

ツールカテゴリ → 具体的なツール

tools 値としてカテゴリ名を直接使用する(例:tools: read-only)か、配列で個別のツールIDを指定できます。 明示的な配列では、上表にある有効なツールID(大文字小文字を区別)および/または登録済みの正確な MCP ツールIDを使用する必要があります。未知のIDは検証エラーを引き起こします。
タスク追跡を有効にするため、TodoWriteはすべてのdroidに自動的に含まれます。ツール一覧に追加する必要はありません。
OpenAIモデルでEditを使用する場合、互換性のためApplyPatchが自動的に含まれます。modelinheritの場合、モデルプロバイダー全体をカバーするため両方のツールが有効になります。

MCP サーバーの選択

mcpServers を使うと、カスタム droid が利用できる MCP サーバー を制限できます。droid は tools で宣言したツールに加えて、列挙した各サーバーのツールを受け取ります。mcp.json で設定されていても、ここに列挙されていないサーバーはサブエージェントのツール許可リストから除外されます。
注記:
  • サーバー名は ~/.factory/mcp.json または .factory/mcp.json にすでに設定されているエントリ名と一致している必要があります(ユーザーレベルまたはプロジェクトレベル)。
  • mcpServers を省略すると既存の動作になり、droid は親セッションから MCP ツールの可用性を継承します。
  • mcpServers: [] を設定すると、グローバルに設定されているものも含めて、すべての MCP サーバーが除外されます。
  • より細かく制御したい場合は、サーバー単位ではなく tools に登録済みの正確な MCP ツールIDを列挙して、特定のツールだけを許可できます。
  • Enterprise MCP ポリシー でブロックされているサーバーは、ここに列挙しても利用できません。
  • 設定されたサーバーは /droids の詳細ビューで MCP Servers: の下に表示されるため、選択内容が保存されていることを確認できます。

9 · UI での droids 管理

/droids でモーダルが開き、以下が表示されます:
  • droids のリスト – 各droid を以下の情報と共に表示:
    • 名前とモデル(括弧内)
    • 説明のプレビュー
    • 場所バッジ(Project / Personal)
    • ツールの概要(例:「All tools」または選択されたツールの数)
  • Create a new Droid – ガイド付きウィザードを起動:
    1. 場所を選択(Project または Personal)
    2. droid が実行すべきことを説明
    3. システムプロンプトを生成または手動編集
    4. 識別子、モデル、ツールを確認
  • Import from Claude Code~/.claude/agents/ の既存エージェントをカスタム Droid としてインポート
  • アクション – droids の表示、編集、削除、またはリロードしてリストを更新

9.5 · Claude Code サブエージェントのインポート

Claude Code で作成されたエージェントをカスタム Droid としてインポートできます。これにより、既存の Claude Code エージェントを Droids システムで再利用できます。

インポート方法

  1. /droids を実行してDroids メニューを開きます
  2. I を押してインポートフローを開始します
  3. CLI がClaude Code エージェントディレクトリをスキャンします:
    • プロジェクトスコープ<repo>/.claude/agents/(ワークスペース固有のエージェント)
    • 個人スコープ~/.claude/agents/(個人エージェント)
  4. 利用可能なエージェントのリストを確認します:
    • (already exists) とマークされたエージェントはデフォルトで非選択状態
    • 事前選択されたエージェントは、まだDroids にインポートされていないもの
  5. Space で個別選択を切り替え、A ですべてを切り替えます
  6. Enter を押して選択されたエージェントをインポートします

インポート中に実行される処理

インポートプロセスはClaude Code エージェントをDroids に変換します:
  1. メタデータの抽出
    • エージェント名 → droid name
    • エージェント説明(例と使用ガイダンスを含む)→ droid description
    • エージェント指示 → droid システムプロンプト(本文)
  2. 設定のマッピング
    • モデル:Claude Code モデルファミリーをFactory モデルにマッピング:
      • inheritinherit
      • sonnet → 利用可能な最初のSonnet モデル
      • haiku → 利用可能な最初のHaiku モデル
      • opus → 利用可能な最初のOpus モデル
    • ツール:Claude Code ツール名をFactory ツールにマッピング(ツールがマッピングされない場合は検証警告を表示)
    • 場所:デフォルトで Personal ~/.factory/droids/ にインポート
  3. ツール検証
    • 一部のClaude Code ツールはFactory に相当するものがない場合があります
    • 無効なツールは警告と共にリスト表示されます:「Invalid tools: [list]」
    • droid を編集してツールマッピングを修正するか、ツールアクセスを調整できます
  4. ファイル作成
    • ~/.factory/droids/(個人場所)に .md ファイルを作成
    • ファイル名は正規化されます(小文字、ハイフン区切り)
    • ファイル形式:YAML frontmatter + システムプロンプト本文
  5. インポートレポート
    • 各エージェントの成功/失敗を表示
    • インポートされたエージェントはすぐにdroid リストで利用可能
    • インポートされたdroid を編集してモデル、ツール、プロンプトを調整可能

インポートフローの例

選択画面(インポート前):
インポート後(droid リストに戻る):

ツール検証エラーの処理

インポート後に 「Invalid tools: [list]」 が表示される場合、一部のClaude Code ツールにFactory 相当品がないことを意味します:
  1. droid を表示(Enter を押す)して完全なツールリストを確認
  2. droid を編集(E を押す)して調整:
    • リストから無効なツールを削除
    • 有効なFactory ツールのみを保持
  3. 利用可能なツールを確認 - リストに利用可能なFactory ツールが表示されます
一般的なマッピングされないツール:
  • WriteNotebookEditBrowseURL などのClaude Code ツールはFactory には存在しません
  • 相当するFactory ツールに置き換え:
    • WriteEditCreate
    • BrowseURLWebSearchFetchUrl
  • または tools セクション全体を削除してすべてのFactory ツールを有効化

10 · サブエージェントを効果的に使う

  • Task ツール経由で呼び出し – Droid は自動的にカスタム Droid を呼び出すことも、直接リクエストを受けて呼び出すこともできます(「この変更にサブエージェント security-auditor を使って」)。
  • モデルを戦略的に選択inherit を使用して親セッションとマッチさせるか、専門タスクに異なるモデルを指定:
    • 単純な分析と要約タスクには小さい/高速なモデル(低コスト)。
    • 複雑な推論、コードレビュー、多段階分析には大きい/高性能なモデル。
    • 利用可能なモデルIDについては 利用可能なモデル を参照してください。
  • ツールアクセスを制限 – 明示的なツールリストを使用してサブエージェントができることを制限し、予期しないシェルコマンドや他の危険な操作を防止。
  • ライブ更新を活用 – Task ツールは、フォアグラウンドで実行されるサブエージェントのツール呼び出し、結果、TodoWrite 更新をリアルタイムで表示します。
  • 独立した作業はバックグラウンドで – 長時間かかる作業や並列化しやすい作業は run_in_background: true で起動し、TaskOutput で結果を回収します(必要に応じて TaskStop で停止できます)。
  • フォローアップでは再開を使う – 最初からやり直す代わりに、既存のサブエージェントの task_idresume に渡してコンテキストを再利用します。
  • 出力を構造化Summary:Findings: などのセクションを出力するようプロンプトを整理し、Task ツールUI が結果を明確に要約できるようにします。
  • 共有と協力 – チームメンバーが共有 Droid を使えるよう .factory/droids/*.md をリポジトリにチェックインし、プロンプトの更新をコードのようにバージョン管理します。
  • Claude Code エージェントを活用 – 既存の Claude Code エージェントは、上の「Claude Code サブエージェントのインポート」セクションを参照して、Factory のカスタム Droid として再利用できます。

11 · 例

コードレビュワー(プロジェクトスコープ)

使用法:「ステージされたdiff で サブエージェント code-reviewer を実行して。」

セキュリティスイーパー(個人スコープ)

タスクコーディネーター(ライブ進行状況付き)


サブエージェントを使うと、チームの暗黙知をコードとして残せます。専門的なプロンプトを一度作成し、適切なツール、モデル、自律性を割り当てれば、フォアグラウンドでもバックグラウンドでも、設計したサブエージェントに重い作業を委任できます。