Sub-Agentsでバックグラウンドタスクを効率化する

開発をしていると、時間のかかる処理を待っている間に他の作業を進めたい場面がよくあります。重いデータの解析や広範囲なリサーチなど、一つのタスクが終わるまで次の指示が出せない状況は、開発のスピードを落とす原因になります。

Sub-Agents を使えば、メインの会話をブロックすることなく、バックグラウンドでタスクを実行できます。Sub-Agents は独立したセッションで動作し、完了すると結果をチャットに報告してくれるため、作業の手を止める必要がありません。

必要なもの

• Sub-Agents 機能が有効なエージェント環境
• sessions_spawn ツールへのアクセス権限

クイックスタート

Sub-Agents を使い始める最も簡単な方法は、エージェントに自然な言葉で依頼することです。

「最新の Node.js のリリースノートを調査するために Sub-Agent を作成して」

エージェントは裏側で sessions_spawn ツールを呼び出します。Sub-Agent が完了すると、その結果がチャットに自動的に報告されます。

また、特定のオプションを明示的に指定することも可能です。

「今日のサーバーログを分析する Sub-Agent を作成して。モデルは gpt-5.2 を使い、タイムアウトは 5 分に設定して」

動作の仕組み

1. メインエージェントが生成: メインのエージェントが sessions_spawn を呼び出します。この呼び出しは non-blocking であり、すぐにステータスが返されます。
2. バックグラウンド実行: 新しい独立したセッション（agent:<agentId>:subagent:<uuid>）が専用の subagent キューで作成されます。
3. 結果の通知: Sub-Agent が完了すると、結果が元のチャットに報告されます。メインのエージェントが自然言語で要約を投稿します。
4. 自動アーカイブ: Sub-Agent のセッションは 60 分後（設定可能）に自動的にアーカイブされます。

Configuration

Sub-Agents は設定なしでも動作しますが、プロジェクトに合わせてカスタマイズすることをおすすめします。

モデルのデフォルト設定

トークンコストを抑えるために、Sub-Agents には安価なモデルを設定するのが良い方法です。

{
  agents: {
    defaults: {
      subagents: {
        model: "minimax/MiniMax-M2.1",
      },
    },
  },
}

エージェントごとの個別設定

マルチエージェント構成では、エージェントごとに異なる Sub-Agent 設定を適用できます。

{
  agents: {
    list: [
      {
        id: "researcher",
        subagents: {
          model: "anthropic/claude-sonnet-4",
        },
      },
      {
        id: "assistant",
        subagents: {
          model: "minimax/MiniMax-M2.1",
        },
      },
    ],
  },
}

並行実行数とアーカイブ設定

同時に実行できる Sub-Agent の数や、セッションがアーカイブされるまでの時間を制御できます。

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 4, // デフォルト: 8
        archiveAfterMinutes: 120, // デフォルト: 60
      },
    },
  },
}

Sub-Agents はメインのエージェントとは別の専用キュー（subagent）を使用するため、バックグラウンドの処理が原因でメインのレスポンスが遅れることはありません。

トラブルシューティング

• アーカイブされたデータの場所: アーカイブが実行されると、トランスクリプトは削除されず、同じフォルダ内で *.deleted.<timestamp> という名前に変更されます。
• Gateway 再起動時の挙動: 自動アーカイブのタイマーはベストエフォートで動作します。Gateway が再起動した場合、待機中のタイマーは失われる可能性があるため注意してください。

設定や導入に関する具体的なアドバイスが必要な場合は、AI Setup Assistant を活用してください。

次のステップ

• Setting a Default Model
• Multi-Agent Setup Guide

複雑なタスクを一つのエージェントだけで完結させようとすると、プロンプトが長くなりすぎたり、コンテキストが混乱したりすることがあります。本来集中すべきメインの処理が、細かなサブタスクの管理に埋もれてしまうのは避けたいところです。

そんな時に役立つのが、タスクを切り出して専用のサブエージェントに任せる方法です。役割を分担することで、メインのエージェントは全体の流れの制御に集中できるようになります。

必要なもの

• sessions_spawn ツールへのアクセス権限
• 有効な agentId のリスト

クイックスタート

sessions_spawn は、エージェントが新しいサブエージェントを作成するために呼び出すツールです。以下のパラメータを指定して実行します。

Parameters

パラメータ	型	デフォルト	説明
task	string	(必須)	サブエージェントが実行する内容
label	string	—	識別用の短いラベル
agentId	string	(呼び出し元と同じ)	別のエージェント ID で起動する場合（許可が必要）
model	string	(任意)	このサブエージェントで使用するモデルを上書きする
thinking	string	(任意)	思考レベルの上書き (off, low, medium, high など)
runTimeoutSeconds	number	0 (制限なし)	指定した秒数後にサブエージェントを停止する
cleanup	"delete" | "keep"	"keep"	"delete" を指定すると、完了通知の直後にアーカイブされる

モデルと思考レベルの決定ルール

サブエージェントの model は、以下の優先順位で決定されます。

1. sessions_spawn 呼び出し時の model パラメータ
2. エージェントごとの設定: agents.list[].subagents.model
3. グローバルなデフォルト設定: agents.defaults.subagents.model
4. ターゲットエージェントが新しいセッションで通常使用するモデル

thinking レベルについても、同様の優先順位が適用されます。

1. sessions_spawn 呼び出し時の thinking パラメータ
2. エージェントごとの設定: agents.list[].subagents.thinking
3. グローバルなデフォルト設定: agents.defaults.subagents.thinking
4. 上記がない場合、サブエージェント固有の上書きは行われません

[!NOTE] 無効なモデル名が指定された場合は、エラーにならずにスキップされます。ツール実行結果に警告が表示され、次に優先度の高い有効なデフォルトモデルで実行されます。

エージェント間での起動設定

デフォルトの状態では、エージェントは自分自身の agentId を使ってしかサブエージェントを起動できません。orchestrator エージェントから researcher などの異なるエージェントを起動させたい場合は、以下のように設定を追加します。

{
  agents: {
    list: [
      {
        id: "orchestrator",
        subagents: {
          allowAgents: ["researcher", "coder"], // または ["*"] ですべてのエージェントを許可
        },
      },
    ],
  },
}

[!TIP] 現在どの agentId が sessions_spawn で利用可能かを知るには、agents_list ツールを使用してください。

トラブルシューティング

指定したモデルで動かない

指定した model の値が間違っている可能性があります。無効なモデル名を入力すると、システムはそれを無視してデフォルトのモデルを使用します。ツールの実行結果に含まれる警告メッセージを確認してください。

別の agentId で起動できない

起動元のエージェントの設定で、対象の agentId が allowAgents リストに含まれているか確認してください。許可されていない ID を指定しても、サブエージェントを作成することはできません。

導入方法や設定の詳細で困ったことがあれば、AI Setup Assistant でいつでも質問してください。

次のステップ

• agents_list ツールのドキュメント
• エージェント設定のカスタマイズガイド

複雑なタスクを自動化していると、複数のエージェントがバックグラウンドで同時に動くことがあります。今どの子がどのタスクを処理しているのか、あるいは期待と違う動きをしているエージェントをすぐに止めたい、といった状況に直面したことはありませんか？

実行中のプロセスがブラックボックスになってしまうと、デバッグやリソースの管理が難しくなります。こうした状況を解決するために用意されているのが /subagents コマンドです。

必要なもの

この機能を利用するには、以下の準備が必要です。

• Sub-agent の実行が可能なアクティブなセッション
• 実行中または完了済みの Sub-agent の履歴

クイックスタート

まずは 5 分で基本操作をマスターしましょう。現在のセッションで動いている Sub-agent を操作する手順は以下の通りです。

1. 実行状態を一覧表示する

まず、どの Sub-agent が動いているかを確認します。

/subagents list

実行すると、以下のようなリストが表示されます。

🧭 Subagents (current session)
Active: 1 · Done: 2
1) ✅ · research logs · 2m31s · run a1b2c3d4 · agent:main:subagent:...
2) ✅ · check deps · 45s · run e5f6g7h8 · agent:main:subagent:...
3) 🔄 · deploy staging · 1m12s · run i9j0k1l2 · agent:main:subagent:...

2. 特定の Sub-agent を停止する

リストのインデックス番号（例: 3）を使って、実行中のタスクを停止できます。

/subagents stop 3

3. 詳細情報を確認する

特定の Sub-agent のメタデータやタスク内容を確認したい場合は info を使います。

/subagents info 1

4. ログ（Transcript）を表示する

直近のやり取りを確認したい場合は log コマンドが便利です。

/subagents log 1 10

※末尾に tools を付けると、Tool call のメッセージも含めて表示されます。

---

コマンドリファレンス

/subagents コマンドで利用できるオプションの一覧です。Sub-agent の指定には、リストのインデックス番号（1, 2）、Run ID の接頭辞、フルセッションキー、または last が使用できます。

Command	Description
/subagents list	すべての Sub-agent 実行（実行中および完了）をリスト表示
/subagents stop <id|#|all>	実行中の Sub-agent を停止
/subagents log <id|#> [limit] [tools]	Sub-agent の Transcript（ログ）を表示
/subagents info <id|#>	詳細な実行メタデータを表示
/subagents send <id|#> <message>	実行中の Sub-agent にメッセージを送信

追記メッセージの送信

実行中の Sub-agent に対して、追加の指示を送ることも可能です。

/subagents send 3 "Also check the staging environment"

このコマンドを送ると、実行中のセッションにメッセージが注入され、返答を最大 30 秒間待機します。

---

Announce（結果の通知）

Sub-agent がタスクを終えると、Announce と呼ばれるステップが実行されます。

1. Sub-agent の最終回答がキャプチャされます。
2. 実行結果、ステータス、統計情報を含むサマリーメッセージがメインエージェントのセッションに送られます。
3. メインエージェントが、自然言語によるサマリーをチャットに投稿します。

この通知は、Slack スレッド、Telegram トピック、Matrix スレッドなどのルーティング情報を保持したまま返されます。

Announce Stats（統計情報）

通知には以下の統計情報が含まれます。

• Runtime（実行時間）
• Token 使用量（Input / Output / Total）
• 推定コスト（models.providers.*.models[].cost が設定されている場合）
• Session Key、Session ID、Transcript のパス

Announce Status（実行ステータス）

ステータスはモデルの出力ではなく、ランタイムの実行結果から判定されます。

• successful completion (ok): タスクが正常に完了
• error: タスクが失敗（詳細はノートに記載）
• timeout: runTimeoutSeconds を超過
• unknown: ステータスを特定不能

[!TIP] ユーザーへの通知が不要な場合は、メインエージェントのサマリーステップで NO_REPLY を返すと、何も投稿されません。これは、エージェント間通信で使用される ANNOUNCE_SKIP とは異なる仕組みです。

---

トラブルシューティング

よくあるステータス関連の問題と解決策です。

• Status が error になる: エージェントの実行中にエラーが発生しています。/subagents info <id> でエラーの詳細を確認してください。
• Status が timeout になる: タスクが制限時間を超えています。設定の runTimeoutSeconds を調整するか、タスクをより細かく分割することを検討してください。

---

関連情報

• AI Setup Assistant

次のステップ

• Agent Sessions の詳細
• Tool Call の設定

---
title: Sub-agent の Tool Policy を設定する
description: Sub-agent が使用できるツールを制限し、安全にタスクを実行するための設定方法について解説します。
---

複数のエージェントにタスクを任せる際、セキュリティや安全性が気になることはありませんか？特にバックグラウンドで動く Sub-agent には、必要最小限のツールだけを渡して、予期しない操作を防ぎたいものです。

Sub-agent の権限を適切に管理することで、メインのワークフローを邪魔することなく、安全にタスクを自動化できます。ここでは、推奨される Tool Policy の設定方法を見ていきましょう。

## 必要なもの

- 設定対象となる Main agent と Sub-agent
- JSON5 形式の設定ファイル

## クイックスタート

デフォルトでは、Sub-agent は「デフォルトの禁止リスト」に含まれるツールを除き、すべてのツールを使用できます。特定のツールをさらに制限したい場合は、以下のように設定ファイルへ `deny` リストを追加するのが最短の道です。

```json
{
  tools: {
    subagents: {
      tools: {
        // deny は常に allow よりも優先されます
        deny: ["browser", "firecrawl"],
      },
    },
  },
}

もし Sub-agent に特定のツールだけを使わせたい場合は、allow を使用します。

{
  tools: {
    subagents: {
      tools: {
        allow: ["read", "exec", "process", "write", "edit", "apply_patch"],
        // allow を設定していても、deny に記載がある場合はそちらが優先されます
      },
    },
  },
}

ノート

カスタムの deny エントリは、デフォルトの禁止リストに追加されます。allow を設定した場合、そのツールのみが利用可能になりますが、デフォルトの禁止リストは引き続きその上から適用されます。

デフォルトで禁止されているツール

Sub-agent がバックグラウンドタスクで不安全な操作や不要な操作を行わないよう、以下のツールは最初から制限されています。

禁止ツール	理由
sessions_list	Session 管理は Main agent が担当するため
sessions_history	Session 管理は Main agent が担当するため
sessions_send	Session 管理は Main agent が担当するため
sessions_spawn	ネストされたファンアウト（Sub-agent がさらに Sub-agent を作る動作）を避けるため
gateway	Sub-agent からのシステム管理操作は危険なため
agents_list	システム管理操作に該当するため
whatsapp_login	インタラクティブなセットアップはタスクに含まれないため
session_status	ステータスやスケジューリングは Main agent が調整するため
cron	ステータスやスケジューリングは Main agent が調整するため
memory_search	必要な情報は spawn 時のプロンプトで渡すべきなため
memory_get	必要な情報は spawn 時のプロンプトで渡すべきなため

Authentication（認証）

Sub-agent の認証は、セッションタイプではなく agent id によって解決されます。

• 認証情報は、対象となるエージェントの agentDir から読み込まれます。
• Main agent の認証プロファイルは、フォールバックとしてマージされます（競合した場合は、エージェント側のプロファイルが優先されます）。
• このマージは加算的であり、Main agent のプロファイルは常にフォールバックとして利用可能です。

ノート

現在、Sub-agent ごとに完全に独立した認証を設定することはサポートされていません。

Context と System Prompt

Sub-agent に渡される System Prompt は、Main agent よりも簡略化されています。

• 含まれるもの: Tooling, Workspace, Runtime セクション、および AGENTS.md, TOOLS.md
• 含まれないもの: SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md

また、Sub-agent にはタスクに特化した System Prompt が与えられます。これにより、割り当てられたタスクに集中し、Main agent のように振る舞わないよう指示されます。

トラブルシューティング

• allow リストに入れたツールが Sub-agent で使えません。 そのツールが「デフォルトの禁止リスト」に入っていないか、または deny リストに重複して記載されていないか確認してください。deny 設定は常に allow よりも優先されます。

• Sub-agent ごとに独自の認証情報を使わせたい。 現在の仕様では、Sub-agent ごとの完全な認証分離はできません。Main agent の認証プロファイルが常にフォールバックとしてマージされる点に注意してください。

AI Setup Assistant

次のステップ

• Sub-agents の作成
• Custom Tools の構築

並列で複数のタスクを走らせていると、「あ、今のリクエストは一度止めたい」という場面がどうしても出てきます。特にリソースを消費する Sub-Agent を運用している場合、それらをどうやって安全に、かつ確実に停止させるかを知っておくことは非常に重要です。

Sub-Agent の制御をマスターして、効率的な開発環境を整えましょう。

## 必要なもの

- Sub-Agent が設定された Gateway 環境
- `agents.defaults.subagents` の設定に関する基本知識

## クイックスタート

Sub-Agent を停止するには、手動で行う方法と自動で行う方法の大きく分けて 3 つの手段があります。

### 1. チャットから停止する
もっとも直感的な方法は、チャットインターフェースでコマンドを入力することです。

- **`/stop`**: メインセッションと、そこから派生して動いているすべての Sub-Agent の実行を強制終了します。
- **`/subagents stop <id>`**: メインセッションはそのままに、特定の Sub-Agent だけを個別に停止させたい場合に使います。

### 2. タイムアウトを設定する
あらかじめ実行時間を制限しておきたい場合は、`runTimeoutSeconds` を設定するのがベストです。指定した時間を過ぎると、Sub-Agent の実行が自動的に中止されます。

> [!NOTE]
> `runTimeoutSeconds` は実行を停止させるためのもので、セッション自体をアーカイブするものではありません。セッションは、通常のアーカイブタイマーが作動するまで保持されます。

## Full Configuration Example

Sub-Agent の挙動を細かく制御するための設定例です。`maxConcurrent` を使った同時実行数の制限や、特定のツール使用制限などを組み合わせて定義できます。

```json
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4" },
      subagents: {
        model: "minimax/MiniMax-M2.1",
        thinking: "low",
        maxConcurrent: 4,
        archiveAfterMinutes: 30,
      },
    },
    list: [
      {
        id: "main",
        default: true,
        name: "Personal Assistant",
      },
      {
        id: "ops",
        name: "Ops Agent",
        subagents: {
          model: "anthropic/claude-sonnet-4",
          allowAgents: ["main"], // ops can spawn sub-agents under "main"
        },
      },
    ],
  },
  tools: {
    subagents: {
      tools: {
        deny: ["browser"], // sub-agents can't use the browser
      },
    },
  },
}

トラブルシューティング

運用中に遭遇する可能性のある制限事項や注意点です。

• 通知の消失: Gateway が再起動した場合、処理待ちの通知（announce）は失われます。
• ネストの禁止: Sub-Agent がさらに別の Sub-Agent を起動することはできません。
• リソースの共有: Sub-Agent は Gateway プロセスを共有します。安全弁として maxConcurrent を適切に設定してください。
• アーカイブの挙動: Gateway が再起動すると、保留されていた自動アーカイブ用のタイマーはリセットされます。

設定や操作で不明な点があれば、AI Setup Assistant でいつでも質問してください。

次のステップ

• Session Tools — sessions_spawn やその他のセッションツールの詳細
• Multi-Agent Sandbox and Tools — エージェントごとのツール制限とサンドボックス化
• Configuration — agents.defaults.subagents のリファレンス
• Queue — subagent レーンの仕組みについて